Porting

Get port-in details

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

Retrieves a single port-in request, including failure reason when terminal.

get/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

profileReferencestringrequired

The eSIM's profile reference (16-digit numeric string)

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

portInRequestReferencestringrequired

Public port-in request reference (8-char uppercase base36)

Responses

200Port-in detailsapplication/json

Show response body

dataobject

Show properties

portInRequestReferencestringrequired

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestringrequired

esimReferencestringrequired

The eSIM this port-in belongs to

msisdnstringrequired

The number being ported, in international format (E.164 without a leading +)

detailsobject

Provider-specific donor details. The exact fields and validation depend on the eSIM variant. Fields that are accepted, required, or mutually exclusive are resolved from the selected eSIM's number-porting provider. Unknown fields are rejected.

Show properties

donorContractTypestringrequired

Contract type of the number at the donor operator

Optionsprepaidpostpaid

donorIccidstring

Donor SIM ICCID at the donor operator. Exact format is validated per eSIM variant.

donorAccountNumberstring

Account/customer number at the donor operator

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

submittedAtstring | null · date-time

When the port-in was submitted to the provider; null while submission is still pending

completedAtstring | null · date-time

When the port completed

abandonedboolean

Whether porting was abandoned in favour of the temporary number (irreversible; no corrected request possible)

createdAtstring · date-timerequired

updatedAtstring · date-timerequired

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/port-ins/%7BportInRequestReference%7D"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

curl 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/port-ins/%7BportInRequestReference%7D"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

{
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "details": {
      "donorContractType": "postpaid",
      "donorIccid": "8932030478002000352",
      "donorAccountNumber": "123456789"
    },
    "status": "requested",
    "reason": {
      "code": "msisdn_account_mismatch",
      "message": "MSISDN/Account number mismatch"
    },
    "scheduledDate": "2026-01-15",
    "submittedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "abandoned": true,
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}