eSIM

Order an eSIM

Orders an eSIM and creates a new profile in a single operation.

Returns the eSIM details including the activation code (LPA string) for device installation, along with the newly created profile reference for future API calls.

To port an existing number onto the new eSIM, include the optional portIn block — the eSIM then stays pre-active (installable, but no service) until the port completes. See the Porting tag for the full workflow.

post/esims

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

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

externalProfileIdstring

Optional client-provided external ID to associate with this eSIM. Must be unique per client.

esimVariantstring

The eSIM variant to draw from the pool (e.g. 'travel'). Draws from the client's assigned variants of this type. Optional — falls back to the client's default variant when omitted.

portInobject

Optional port-in of an existing number onto the ordered eSIM. When present, the eSIM stays pre-active until the port completes and the response contains a portIn object.

Show properties

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

201Profile created and eSIM successfully orderedapplication/json

Show response body

dataobject

Show properties

profileReferencestring

The eSIM's profile reference for API access (16-digit numeric)

externalProfileIdstring | null

The client's external profile ID if provided

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

The eSIM's ICCID (needed for device installation)

activationCodestring

LPA activation code for device installation

pin1string

PIN1 for the eSIM profile, as personalised by the manufacturer. Required to unlock the profile when SIM PIN is enabled on the device.

puk1string

PUK1 for the eSIM profile. Resets PIN1 after it has been entered incorrectly three times.

pin2string

PIN2 for the eSIM profile, guarding SIM service settings.

puk2string

PUK2 for the eSIM profile. Resets PIN2.

esimVariantstring | null

The eSIM's variant (e.g. 'travel'), or null if it has none.

statusstring

SM-DP+ profile state on the device.

released: Profile is available for download (QR code ready)
downloaded: Profile has been downloaded to the device
installed: Profile is installed on the eSIM chip
enabled: Profile is active on the device
disabled: Profile is installed but disabled on the device
deleted: Profile has been removed from the device
faulted: Profile encountered a provisioning or operational failure

Optionsreleaseddownloadedinstalledenableddisableddeletedfaulted

lifecycleStatusstring | null

IMSI connectivity lifecycle status. Null when the eSIM has not yet been assigned to a profile.

preactive: IMSI is provisioned but not yet active on the network
active: IMSI is active and connected to the network
suspended: IMSI is temporarily suspended from the network
terminated: IMSI has been permanently terminated
faulted: IMSI encountered a provisioning failure
stale: IMSI has a configuration mismatch (e.g., wrong base plan)

Optionspreactiveactivesuspendedterminatedfaultedstalenull

msisdnsarray of object

Phone numbers (MSISDNs) attached to the eSIM. Only available for eSIM variants that include a phone number; empty for variants without one, and until a number is assigned during provisioning.

Show properties

msisdnstringrequired

Phone number in E.164 format without the leading +

primarybooleanrequired

Whether this is the eSIM's primary phone number

createdAtstring · date-time

portInobject | null

Present when the order included a portIn block.

Show properties

portInRequestReferencestringrequired

Public opaque port-in request reference (8-char uppercase base36)

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

404No available eSIM foundapplication/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

409Conflict - Request with this idempotency key is still being processed, or a profile with this externalProfileId already existsapplication/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 422Idempotency key was previously used with a different request body 429Rate limit exceeded 500Internal server error

Request

curl https://connect.firsty.app/api/v3/esims \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "externalProfileId": "my-customer-123",
  "esimVariant": "travel",
  "portIn": {
    "msisdn": "32470123456",
    "details": {
      "donorContractType": "postpaid",
      "donorIccid": "8932030478002000352",
      "donorAccountNumber": "123456789"
    }
  }
}'

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

requests.post("https://connect.firsty.app/api/v3/esims",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "externalProfileId": "my-customer-123",
      "esimVariant": "travel",
      "portIn": {
        "msisdn": "32470123456",
        "details": {
          "donorContractType": "postpaid",
          "donorIccid": "8932030478002000352",
          "donorAccountNumber": "123456789"
        }
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/esims', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'externalProfileId' => 'my-customer-123',
    'esimVariant' => 'travel',
    'portIn' => [
      '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/esims"

	payload := strings.NewReader(`{
  "externalProfileId": "my-customer-123",
  "esimVariant": "travel",
  "portIn": {
    "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/esims \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "externalProfileId": "my-customer-123",
  "esimVariant": "travel",
  "portIn": {
    "msisdn": "32470123456",
    "details": {
      "donorContractType": "postpaid",
      "donorIccid": "8932030478002000352",
      "donorAccountNumber": "123456789"
    }
  }
}'

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

requests.post(
    "https://connect.test.firsty.app/api/v3/esims",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "externalProfileId": "my-customer-123",
      "esimVariant": "travel",
      "portIn": {
        "msisdn": "32470123456",
        "details": {
          "donorContractType": "postpaid",
          "donorIccid": "8932030478002000352",
          "donorAccountNumber": "123456789"
        }
      }
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/esims', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'externalProfileId' => 'my-customer-123',
    'esimVariant' => 'travel',
    'portIn' => [
      '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/esims"

	payload := strings.NewReader(`{
  "externalProfileId": "my-customer-123",
  "esimVariant": "travel",
  "portIn": {
    "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": {
    "profileReference": "1234567890123456",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "activationCode": "LPA:1$provider.example.com$ACTIVATION_CODE_HERE",
    "pin1": "1234",
    "puk1": "12345678",
    "pin2": "5678",
    "puk2": "87654321",
    "esimVariant": "travel",
    "status": "released",
    "lifecycleStatus": "preactive",
    "msisdns": [
      {
        "msisdn": "32123456789",
        "primary": true
      }
    ],
    "createdAt": "2026-01-15T09:30:00Z",
    "portIn": {
      "portInRequestReference": "K7Q2M9XA",
      "status": "requested"
    }
  }
}

{
  "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": "No available eSIM found"
}

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A request with this idempotency key is already being processed. Please retry later."
}