Number Registration

Create or replace the number registration

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

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

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.

firstNamestring

lastNamestringrequired

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

Responses

200The existing registration was replacedapplication/json

Show response body

dataobjectrequired

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

numberRegistrationReferencestringrequired

registrystringrequired

The registry the number was registered with.

msisdnstringrequired

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

statusstringrequired

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, present when the registration ended in error

Show properties

codestringrequired

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

dataobjectrequired

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

numberRegistrationReferencestringrequired

registrystringrequired

The registry the number was registered with.

msisdnstringrequired

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

statusstringrequired

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, present when the registration ended in error

Show properties

codestringrequired

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 · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

422The registration cannot be applied to this number: its country has no registry we submit to, the country does not match the number, or the eSIM has no phone number available to registerapplication/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

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 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",
  "firstName": "Jane",
  "lastName": "Doe",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  }
}'

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',
    firstName: 'Jane',
    lastName: 'Doe',
    languageCode: 'nl',
    address: {
      streetName: 'Grote Markt',
      houseNumber: '1',
      unit: 'A',
      postalCode: '1000',
      city: 'Brussel'
    }
  })
})

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",
      "firstName": "Jane",
      "lastName": "Doe",
      "languageCode": "nl",
      "address": {
        "streetName": "Grote Markt",
        "houseNumber": "1",
        "unit": "A",
        "postalCode": "1000",
        "city": "Brussel"
      }
    }
)

$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',
    'firstName' => 'Jane',
    'lastName' => 'Doe',
    'languageCode' => 'nl',
    'address' => [
      'streetName' => 'Grote Markt',
      'houseNumber' => '1',
      'unit' => 'A',
      'postalCode' => '1000',
      'city' => 'Brussel'
    ]
  ]
]);

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",
  "firstName": "Jane",
  "lastName": "Doe",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  }
}`)

	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  \"firstName\": \"Jane\",\n  \"lastName\": \"Doe\",\n  \"languageCode\": \"nl\",\n  \"address\": {\n    \"streetName\": \"Grote Markt\",\n    \"houseNumber\": \"1\",\n    \"unit\": \"A\",\n    \"postalCode\": \"1000\",\n    \"city\": \"Brussel\"\n  }\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",
  "firstName": "Jane",
  "lastName": "Doe",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  }
}'

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',
    firstName: 'Jane',
    lastName: 'Doe',
    languageCode: 'nl',
    address: {
      streetName: 'Grote Markt',
      houseNumber: '1',
      unit: 'A',
      postalCode: '1000',
      city: 'Brussel'
    }
  })
})

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",
      "firstName": "Jane",
      "lastName": "Doe",
      "languageCode": "nl",
      "address": {
        "streetName": "Grote Markt",
        "houseNumber": "1",
        "unit": "A",
        "postalCode": "1000",
        "city": "Brussel"
      }
    }
)

$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',
    'firstName' => 'Jane',
    'lastName' => 'Doe',
    'languageCode' => 'nl',
    'address' => [
      'streetName' => 'Grote Markt',
      'houseNumber' => '1',
      'unit' => 'A',
      'postalCode' => '1000',
      'city' => 'Brussel'
    ]
  ]
]);

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",
  "firstName": "Jane",
  "lastName": "Doe",
  "languageCode": "nl",
  "address": {
    "streetName": "Grote Markt",
    "houseNumber": "1",
    "unit": "A",
    "postalCode": "1000",
    "city": "Brussel"
  }
}`)

	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  \"firstName\": \"Jane\",\n  \"lastName\": \"Doe\",\n  \"languageCode\": \"nl\",\n  \"address\": {\n    \"streetName\": \"Grote Markt\",\n    \"houseNumber\": \"1\",\n    \"unit\": \"A\",\n    \"postalCode\": \"1000\",\n    \"city\": \"Brussel\"\n  }\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",
  "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/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A registration for this number is currently being processed by the registry"
}

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