Porting

Cancel a port-in request

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

Requests cancellation of a pending port-in. Cancellation is asynchronous: the status moves to cancelling and becomes cancelled once the provider confirms. After a confirmed cancellation the eSIM stays pre-active — submit a corrected request or abandon to activate with the temporary number.

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

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)

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

Responses

200Cancellation requestedapplication/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

409Attempt is not cancellable in its current statusapplication/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/{portInRequestReference}/cancel' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.post(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ]
]);

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/cancel"

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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/{portInRequestReference}/cancel' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}/cancel', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ]
]);

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/cancel"

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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/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"
}