PortingExperimental

Get port-in details

Retrieves a single port-in request, including the reason it was rejected or failed.

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

dataobjectoptional

Show properties

portInRequestReferencestring

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

profileReferencestring

esimReferencestring

The eSIM this port-in belongs to

msisdnstring

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

detailsone of Belgium | Netherlandsoptional

Donor details of the number to port. Their shape depends on the country of the selected eSIM's variant: the Belgian or the Dutch shape. Unknown fields are rejected.

Show properties

Belgiumobjectoptional

Donor details of a Belgian number. A prepaid contract takes donorIccid and/or donorSimNumber; a postpaid contract any of donorIccid, donorSimNumber and donorAccountNumber; a business contract donorAccountNumber only.

Show properties

donorContractTypestring

Contract type of the number at the donor operator

Optionsprepaidpostpaidbusiness

donorIccidstringoptional

ICCID of the donor SIM card, with a valid check digit. The preferred proof of a donor SIM: most donor operators accept it.

donorSimNumberstringoptional

The number printed on the donor SIM card. Send it only when the donor SIM's ICCID is not available; donorIccid is accepted by more donor operators.

donorAccountNumberstringoptional

Account/customer number at the donor operator

Netherlandsobjectoptional

Donor details of a Dutch number. A postpaid contract requires donorAccountNumber.

Show properties

donorContractTypestring

Contract type of the number at the donor operator

Optionsprepaidpostpaid

donorAccountNumberstringoptional

Customer number at the donor operator

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider confirmation
completed: The donor released the number and it is assigned to this SIM
rejected: Donor rejected the request (see reason); submit a corrected request. A rejection the customer can still correct may keep the request requested until it is final
failed: Port failed (see reason); submit a corrected request
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled

reasonobjectoptional

Why the port-in was rejected or failed. Present when status is rejected or failed, and on a requested port-in the donor has rejected for a reason the customer can still correct

Show properties

codestring

Normalized cause of the rejection or failure, the same for every porting provider. provider_failure covers every cause without a more specific code. The list of values is open-ended; new values may be added

Examplesmsisdn_sim_mismatchmsisdn_account_mismatchdonor_contract_type_mismatchnumber_not_activenumber_not_portablenumber_porting_in_progressporting_window_unavailableprovider_failure

messagestring | null

Human-readable detail of the cause for support; free-form, not intended to be parsed. Null when there is none

scheduledAtstring | null · date-time

When the number moves to this SIM, as the donor agreed when it approved the port; null until known. It may move until the port completes

submittedAtstring | null · date-time

When the port-in was submitted to the provider; null while submission is still pending, and for a port-in whose request was not accepted

completedAtstring | null · date-time

When the port completed

abandonedbooleanoptional

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

createdAtstring · date-time

updatedAtstring · date-time

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.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/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}"

	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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}"

	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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "details": {
      "donorContractType": "postpaid",
      "donorIccid": "8932031234567890128"
    },
    "status": "approved",
    "scheduledAt": "2026-01-16T09:00:00Z",
    "submittedAt": "2026-01-15T09:30:00Z",
    "completedAt": null,
    "abandoned": false,
    "createdAt": "2026-01-15T09:29:58Z",
    "updatedAt": "2026-01-15T10:12:04Z"
  }
}

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