Porting

Create a corrected port-in request

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

Creates and submits a new port-in request for the eSIM. Use this after a previous request ended rejected, failed, or cancelled (e.g. with corrected donor details), or to start porting on an eSIM that is still pre-active. The previous terminal request is superseded (marked abandoned), so only the newest request is ever live.

Rejected when the eSIM's subscription is already activated (no longer portable), when a request is still in progress, or when the eSIM's porting was abandoned.

For the initial port-in, prefer the portIn block on POST /esims — it guarantees the eSIM cannot activate before the port-in is registered.

post/profiles/{profileReference}/esims/{esimReference}/port-ins

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)

Headers

X-Idempotency-Keystring

Optional idempotency key for mutating requests (POST, PATCH). If provided, duplicate requests with the same key within 48 hours will return the cached original response without duplicating side effects.

Behavior:

Same key + same request body → returns cached response (prevents duplicate operations)
Same key + different request body → returns 422 error
Same key + in-flight request → returns 409 error with Retry-After header
Keys expire after 48 hours

Request Body Matching: Request bodies are compared using a deterministic fingerprint. The fingerprint is computed by canonicalizing the JSON (sorting object keys recursively) and hashing with SHA-256. This means:

{"a":1,"b":2} and {"b":2,"a":1} are treated as identical ✓
Whitespace differences are ignored ✓
URL parameters and headers are NOT included in the fingerprint

Best Practices:

Use UUIDs or client-generated unique strings
Store keys on your side to support retries
Don't reuse keys across different operations

Request body

application/json · required

msisdnstringrequired

The number to port, in international format (E.164 without a leading +) — i.e. the country code, not the national 0 trunk prefix. Belgium: 324 + 8 digits, e.g. 32470123456; Netherlands: 316 + 8 digits, e.g. 31612345678.

detailsobjectrequired

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

Responses

201Port-in request created and submittedapplication/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

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

400Validation failed (number format, donor detail rules for the eSIM variant)application/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

409eSIM already activated, a non-terminal request exists, or the latest request was abandonedapplication/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

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' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "msisdn": "32470123456",
  "details": {
    "donorContractType": "postpaid",
    "donorIccid": "8932030478002000352",
    "donorAccountNumber": "123456789"
  }
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    msisdn: '32470123456',
    details: {
      donorContractType: 'postpaid',
      donorIccid: '8932030478002000352',
      donorAccountNumber: '123456789'
    }
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "msisdn": "32470123456",
      "details": {
        "donorContractType": "postpaid",
        "donorIccid": "8932030478002000352",
        "donorAccountNumber": "123456789"
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'msisdn' => '32470123456',
    'details' => [
      'donorContractType' => 'postpaid',
      'donorIccid' => '8932030478002000352',
      'donorAccountNumber' => '123456789'
    ]
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "msisdn": "32470123456",
  "details": {
    "donorContractType": "postpaid",
    "donorIccid": "8932030478002000352",
    "donorAccountNumber": "123456789"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	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' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "msisdn": "32470123456",
  "details": {
    "donorContractType": "postpaid",
    "donorIccid": "8932030478002000352",
    "donorAccountNumber": "123456789"
  }
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    msisdn: '32470123456',
    details: {
      donorContractType: 'postpaid',
      donorIccid: '8932030478002000352',
      donorAccountNumber: '123456789'
    }
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "msisdn": "32470123456",
      "details": {
        "donorContractType": "postpaid",
        "donorIccid": "8932030478002000352",
        "donorAccountNumber": "123456789"
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'msisdn' => '32470123456',
    'details' => [
      'donorContractType' => 'postpaid',
      'donorIccid' => '8932030478002000352',
      'donorAccountNumber' => '123456789'
    ]
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "msisdn": "32470123456",
  "details": {
    "donorContractType": "postpaid",
    "donorIccid": "8932030478002000352",
    "donorAccountNumber": "123456789"
  }
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	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/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "eSIM not found"
}

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

{
  "type": "https://developers.firsty.app/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "eSIM not found"
}