Number RegistrationExperimental

Create or replace the number registration

Registers the number this eSIM is on or porting to, replacing whatever was registered before. The body is the same numberRegistration block the eSIM order accepts, and it replaces the record in full — the registry stores exactly what is sent, so omitting a field clears it.

Use it to correct a registration the registry rejected, or to keep a subscriber's details current after they move or change name.

Responds 201 when it creates a registration and 200 when it replaces one that has not been sent yet. A registration already sent and awaiting the registry's result cannot be changed: that is 409. Repeat the write once the outcome arrives, under a new X-Idempotency-Key — reusing the rejected request's key replays its cached 409.

The registration is sent once the number is live, so the status is processing immediately after a successful write.

post/profiles/{profileReference}/esims/{esimReference}/number-registration

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 requests that change state. 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 method, path and request body → returns cached response (prevents duplicate operations)
Same key + different method, path or request body → returns 422 error
Same key + in-flight request → returns 423 error
Keys are held for at least 48 hours; use a fresh key for every new request

Request Body Matching: Request bodies are compared by their JSON content. Object key order, including in nested objects, and whitespace do not affect matching. This means:

{"a":1,"b":2} and {"b":2,"a":1} are treated as identical ✓
Whitespace differences are ignored ✓
The method and the full path, query included, must match as well; headers are not compared

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

Personobject

What a person's and an organization's registration have in common.

Show properties

countryCodestringrequired

The number's country as a two-character uppercase ISO 3166-1 alpha-2 code (malformed: 400). A country whose registry is not supported is rejected with a 422.

languageCodestringrequired

Subscriber's communication language as a two-character lowercase ISO 639-1 code. A language a registry does not accept is rejected with a descriptive error.

addressobjectrequired

Show properties

streetNamestringrequired

houseNumberstringrequired

unitstring

Bus/box/apartment, when present.

postalCodestringrequired

citystringrequired

firstNamestring

lastNamestringrequired

organizationNameany

legalFormany

vatNumberany

Organizationobject

What a person's and an organization's registration have in common.

Show properties

countryCodestringrequired

The number's country as a two-character uppercase ISO 3166-1 alpha-2 code (malformed: 400). A country whose registry is not supported is rejected with a 422.

languageCodestringrequired

Subscriber's communication language as a two-character lowercase ISO 639-1 code. A language a registry does not accept is rejected with a descriptive error.

addressobjectrequired

Show properties

streetNamestringrequired

houseNumberstringrequired

unitstring

Bus/box/apartment, when present.

postalCodestringrequired

citystringrequired

organizationNamestringrequired

legalFormstring

The organization's legal form, for example NV or BV.

vatNumberstring

The organization's VAT number.

firstNameany

lastNameany

Responses

200The existing registration was replacedapplication/json

Show response body

dataobject

The registration of the number the eSIM is on or porting to, in its country's number registry. The field is absent when that number has no registration.

Show properties

numberRegistrationReferencestring

registrystring

The registry the number was registered with.

msisdnstring

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

statusstring

processing while the registration is on its way to the registry, completed once the registry accepted it, error when it was rejected (see reason).

Optionsprocessingcompletederror

reasonobject | null

Rejection detail; null unless the registration ended in error

Show properties

codestring

The registry's own rejection code, or one of ours when the registration never reached it

messagestring | null

Human-readable detail when available

201A registration was createdapplication/json

Show response body

dataobject

The registration of the number the eSIM is on or porting to, in its country's number registry. The field is absent when that number has no registration.

Show properties

numberRegistrationReferencestring

registrystring

The registry the number was registered with.

msisdnstring

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

statusstring

processing while the registration is on its way to the registry, completed once the registry accepted it, error when it was rejected (see reason).

Optionsprocessingcompletederror

reasonobject | null

Rejection detail; null unless the registration ended in error

Show properties

codestring

The registry's own rejection code, or one of ours when the registration never reached it

messagestring | null

Human-readable detail when available

409A registration for this number is currently being processed by the registryapplication/problem+json

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundport_in_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancenumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable

422The registration cannot be applied to this number: its country has no registry we submit to, or the eSIM has no phone number available to registerapplication/problem+json

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

400Bad request - invalid parameters 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}/number-registration' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "countryCode": "BE",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  },
  "firstName": "Jane",
  "lastName": "Doe"
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    countryCode: 'BE',
    languageCode: 'nl',
    address: {
      streetName: 'Grote Markt',
      houseNumber: '1',
      unit: 'A',
      postalCode: '1000',
      city: 'Brussel'
    },
    firstName: 'Jane',
    lastName: 'Doe'
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "countryCode": "BE",
      "languageCode": "nl",
      "address": {
        "streetName": "Grote Markt",
        "houseNumber": "1",
        "unit": "A",
        "postalCode": "1000",
        "city": "Brussel"
      },
      "firstName": "Jane",
      "lastName": "Doe"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'countryCode' => 'BE',
    'languageCode' => 'nl',
    'address' => [
      'streetName' => 'Grote Markt',
      'houseNumber' => '1',
      'unit' => 'A',
      'postalCode' => '1000',
      'city' => 'Brussel'
    ],
    'firstName' => 'Jane',
    'lastName' => 'Doe'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration"

	payload := strings.NewReader(`{
  "countryCode": "BE",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  },
  "firstName": "Jane",
  "lastName": "Doe"
}`)

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

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"countryCode\": \"BE\",\n  \"languageCode\": \"nl\",\n  \"address\": {\n    \"streetName\": \"Grote Markt\",\n    \"houseNumber\": \"1\",\n    \"unit\": \"A\",\n    \"postalCode\": \"1000\",\n    \"city\": \"Brussel\"\n  },\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Doe\"\n}"))
    .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}/number-registration' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "countryCode": "BE",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  },
  "firstName": "Jane",
  "lastName": "Doe"
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    countryCode: 'BE',
    languageCode: 'nl',
    address: {
      streetName: 'Grote Markt',
      houseNumber: '1',
      unit: 'A',
      postalCode: '1000',
      city: 'Brussel'
    },
    firstName: 'Jane',
    lastName: 'Doe'
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "countryCode": "BE",
      "languageCode": "nl",
      "address": {
        "streetName": "Grote Markt",
        "houseNumber": "1",
        "unit": "A",
        "postalCode": "1000",
        "city": "Brussel"
      },
      "firstName": "Jane",
      "lastName": "Doe"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'countryCode' => 'BE',
    'languageCode' => 'nl',
    'address' => [
      'streetName' => 'Grote Markt',
      'houseNumber' => '1',
      'unit' => 'A',
      'postalCode' => '1000',
      'city' => 'Brussel'
    ],
    'firstName' => 'Jane',
    'lastName' => 'Doe'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration"

	payload := strings.NewReader(`{
  "countryCode": "BE",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  },
  "firstName": "Jane",
  "lastName": "Doe"
}`)

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

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"countryCode\": \"BE\",\n  \"languageCode\": \"nl\",\n  \"address\": {\n    \"streetName\": \"Grote Markt\",\n    \"houseNumber\": \"1\",\n    \"unit\": \"A\",\n    \"postalCode\": \"1000\",\n    \"city\": \"Brussel\"\n  },\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Doe\"\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "numberRegistrationReference": "A1B2C3D4",
    "registry": "be_cndb",
    "msisdn": "32470123456",
    "status": "processing",
    "reason": {
      "code": "5130",
      "message": "CustomerAliasLastName is missing"
    }
  }
}

{
  "data": {
    "numberRegistrationReference": "A1B2C3D4",
    "registry": "be_cndb",
    "msisdn": "32470123456",
    "status": "processing",
    "reason": {
      "code": "5130",
      "message": "CustomerAliasLastName is missing"
    }
  }
}

{
  "type": "https://developers.firsty.app/errors/validation_failed",
  "code": "validation_failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}

{
  "type": "https://developers.firsty.app/errors/number_registration_pending",
  "code": "number_registration_pending",
  "title": "Conflict",
  "status": 409,
  "detail": "A registration for this number is currently being processed by the registry"
}

{
  "type": "https://developers.firsty.app/errors/number_registration_not_supported",
  "code": "number_registration_not_supported",
  "title": "Unprocessable entity",
  "status": 422,
  "detail": "Number registration is not supported for country 'US'"
}