Number

Allocate a number to a service

Allocates a new phone number to a service (eSIM).

post/number/{profileReference}/allocate

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)

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

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

countryCodestringrequired

ISO country code (2-6 letters to support regional codes like GLOBAL)

typestring

local: Local/landline number
mobile: Mobile number
tollfree: Toll-free number

Optionslocalmobiletollfree

isPrimaryboolean

Whether this should be the primary number for the profile

Defaulttrue

customerInfoobjectrequired

Show properties

firstNamestringrequired

Customer's first name

lastNamestringrequired

Customer's last name

companyNamestring

(Optional) Company name for business accounts

emailstring · email

(Optional) Customer's email address

phonestring

(Optional) Customer's contact phone number

addressobjectrequired

Show properties

streetstringrequired

Street name

streetNumberstring

(Optional) House/building number. Required for NL porting.

streetNumberAdditionstring

(Optional) Number addition (apartment, floor, etc.)

streetLine2string

(Optional) Additional address line (apartment, suite, etc.)

citystringrequired

City name

statestring

(Optional) State or province

postalCodestringrequired

Postal/ZIP code

countryCodestringrequired

ISO 3166-1 alpha-2 country code

Responses

200Number allocated successfullyapplication/json

Show response body

dataobject

Show properties

assignmentIdinteger

Unique identifier for the number assignment

profileReferencestring

The profile reference this number is allocated to

esimReferencestring

The eSIM reference this number is associated with

iccidstring

ICCID of the eSIM this number is associated with

msisdnstring

The phone number (MSISDN)

countryCodestring

ISO country code

typestring

local: Local/landline number
mobile: Mobile number
tollfree: Toll-free number

Optionslocalmobiletollfree

statusstring

active: Number is active and operational
suspended: Number is temporarily suspended
released: Number has been released

Optionsactivesuspendedreleased

isPrimaryboolean

Whether this is the primary number for the profile

customerInfoobject

Show properties

firstNamestringrequired

Customer's first name

lastNamestringrequired

Customer's last name

companyNamestring

(Optional) Company name for business accounts

emailstring · email

(Optional) Customer's email address

phonestring

(Optional) Customer's contact phone number

addressobject

Show properties

streetstringrequired

Street name

streetNumberstring

(Optional) House/building number. Required for NL porting.

streetNumberAdditionstring

(Optional) Number addition (apartment, floor, etc.)

streetLine2string

(Optional) Additional address line (apartment, suite, etc.)

citystringrequired

City name

statestring

(Optional) State or province

postalCodestringrequired

Postal/ZIP code

countryCodestringrequired

ISO 3166-1 alpha-2 country code

createdAtstring · date-time

updatedAtstring · date-time

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 409Request with this idempotency key is still being processed 422Idempotency key was previously used with a different request body 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/number/{profileReference}/allocate' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "esimReference": "123456000000000001",
  "countryCode": "US",
  "type": "local",
  "isPrimary": true,
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "email": "john.doe@example.com",
    "phone": "+31612345678"
  },
  "address": {
    "street": "Keizersgracht",
    "streetNumber": "123",
    "streetNumberAddition": "2A",
    "streetLine2": "Unit 4B",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "postalCode": "1015 CJ",
    "countryCode": "NL"
  }
}'

fetch('https://connect.firsty.app/api/v3/number/{profileReference}/allocate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    esimReference: '123456000000000001',
    countryCode: 'US',
    type: 'local',
    isPrimary: true,
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      companyName: 'Acme Corp',
      email: 'john.doe@example.com',
      phone: '+31612345678'
    },
    address: {
      street: 'Keizersgracht',
      streetNumber: '123',
      streetNumberAddition: '2A',
      streetLine2: 'Unit 4B',
      city: 'Amsterdam',
      state: 'Noord-Holland',
      postalCode: '1015 CJ',
      countryCode: 'NL'
    }
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/number/{profileReference}/allocate",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "esimReference": "123456000000000001",
      "countryCode": "US",
      "type": "local",
      "isPrimary": True,
      "customerInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Acme Corp",
        "email": "john.doe@example.com",
        "phone": "+31612345678"
      },
      "address": {
        "street": "Keizersgracht",
        "streetNumber": "123",
        "streetNumberAddition": "2A",
        "streetLine2": "Unit 4B",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "postalCode": "1015 CJ",
        "countryCode": "NL"
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/number/{profileReference}/allocate', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'esimReference' => '123456000000000001',
    'countryCode' => 'US',
    'type' => 'local',
    'isPrimary' => true,
    'customerInfo' => [
      'firstName' => 'John',
      'lastName' => 'Doe',
      'companyName' => 'Acme Corp',
      'email' => 'john.doe@example.com',
      'phone' => '+31612345678'
    ],
    'address' => [
      'street' => 'Keizersgracht',
      'streetNumber' => '123',
      'streetNumberAddition' => '2A',
      'streetLine2' => 'Unit 4B',
      'city' => 'Amsterdam',
      'state' => 'Noord-Holland',
      'postalCode' => '1015 CJ',
      'countryCode' => 'NL'
    ]
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/number/%7BprofileReference%7D/allocate"

	payload := strings.NewReader(`{
  "esimReference": "123456000000000001",
  "countryCode": "US",
  "type": "local",
  "isPrimary": true,
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "email": "john.doe@example.com",
    "phone": "+31612345678"
  },
  "address": {
    "street": "Keizersgracht",
    "streetNumber": "123",
    "streetNumberAddition": "2A",
    "streetLine2": "Unit 4B",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "postalCode": "1015 CJ",
    "countryCode": "NL"
  }
}`)

	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/number/{profileReference}/allocate' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "esimReference": "123456000000000001",
  "countryCode": "US",
  "type": "local",
  "isPrimary": true,
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "email": "john.doe@example.com",
    "phone": "+31612345678"
  },
  "address": {
    "street": "Keizersgracht",
    "streetNumber": "123",
    "streetNumberAddition": "2A",
    "streetLine2": "Unit 4B",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "postalCode": "1015 CJ",
    "countryCode": "NL"
  }
}'

fetch('https://connect.test.firsty.app/api/v3/number/{profileReference}/allocate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    esimReference: '123456000000000001',
    countryCode: 'US',
    type: 'local',
    isPrimary: true,
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      companyName: 'Acme Corp',
      email: 'john.doe@example.com',
      phone: '+31612345678'
    },
    address: {
      street: 'Keizersgracht',
      streetNumber: '123',
      streetNumberAddition: '2A',
      streetLine2: 'Unit 4B',
      city: 'Amsterdam',
      state: 'Noord-Holland',
      postalCode: '1015 CJ',
      countryCode: 'NL'
    }
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/number/{profileReference}/allocate",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "esimReference": "123456000000000001",
      "countryCode": "US",
      "type": "local",
      "isPrimary": True,
      "customerInfo": {
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Acme Corp",
        "email": "john.doe@example.com",
        "phone": "+31612345678"
      },
      "address": {
        "street": "Keizersgracht",
        "streetNumber": "123",
        "streetNumberAddition": "2A",
        "streetLine2": "Unit 4B",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "postalCode": "1015 CJ",
        "countryCode": "NL"
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/number/{profileReference}/allocate', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'esimReference' => '123456000000000001',
    'countryCode' => 'US',
    'type' => 'local',
    'isPrimary' => true,
    'customerInfo' => [
      'firstName' => 'John',
      'lastName' => 'Doe',
      'companyName' => 'Acme Corp',
      'email' => 'john.doe@example.com',
      'phone' => '+31612345678'
    ],
    'address' => [
      'street' => 'Keizersgracht',
      'streetNumber' => '123',
      'streetNumberAddition' => '2A',
      'streetLine2' => 'Unit 4B',
      'city' => 'Amsterdam',
      'state' => 'Noord-Holland',
      'postalCode' => '1015 CJ',
      'countryCode' => 'NL'
    ]
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/number/%7BprofileReference%7D/allocate"

	payload := strings.NewReader(`{
  "esimReference": "123456000000000001",
  "countryCode": "US",
  "type": "local",
  "isPrimary": true,
  "customerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "email": "john.doe@example.com",
    "phone": "+31612345678"
  },
  "address": {
    "street": "Keizersgracht",
    "streetNumber": "123",
    "streetNumberAddition": "2A",
    "streetLine2": "Unit 4B",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "postalCode": "1015 CJ",
    "countryCode": "NL"
  }
}`)

	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": {
    "assignmentId": 12345,
    "profileReference": "1234567890123456",
    "esimReference": "123456789012345678",
    "iccid": "89012345678901234567",
    "msisdn": "+14155551234",
    "countryCode": "US",
    "type": "local",
    "status": "active",
    "isPrimary": true,
    "customerInfo": {
      "firstName": "John",
      "lastName": "Doe",
      "companyName": "Acme Corp",
      "email": "john.doe@example.com",
      "phone": "+31612345678"
    },
    "address": {
      "street": "Keizersgracht",
      "streetNumber": "123",
      "streetNumberAddition": "2A",
      "streetLine2": "Unit 4B",
      "city": "Amsterdam",
      "state": "Noord-Holland",
      "postalCode": "1015 CJ",
      "countryCode": "NL"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

{
  "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"
    }
  ]
}