eSIM

Get eSIM details

Retrieves detailed information about a specific eSIM.

get/profiles/{profileReference}/esims/{esimReference}

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)

Responses

200eSIM detailsapplication/json

Show response body

dataobjectoptional

Show properties

profileReferencestring

externalProfileIdstring | null

The client's external profile ID if provided

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

eidstring | null

The eUICC Identifier (EID) if available

activationCodestring | null

LPA activation code for device installation; null for a physical SIM, and for an eSIM until its code is issued

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

Profile state on the device, as reported by the SM-DP+. A physical SIM has no download lifecycle and stays released; its service state is lifecycleStatus.

released: Ready for use; an eSIM profile in this state 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 failed to download or install on the device

Optionsreleaseddownloadedinstalledenableddisableddeletedfaulted

lifecycleStatusstring

Network service state of the eSIM.

preactive: not live on the network yet
active: live on the network
suspended: temporarily without network service; can be reactivated
terminated: permanently without network service
faulted, stale: network service could not be set up; contact support

Optionspreactiveactivesuspendedterminatedfaultedstale

provisionedboolean

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.

Show properties

msisdnstring

Phone number in E.164 format without the leading +

primaryboolean

Whether this is the eSIM's primary phone number

staticIpAddressesarray of stringoptional

Static IP addresses allocated to the eSIM. Present only when static IPs are enabled for your account; an empty array when no address is allocated to this eSIM.

numberRegistrationobjectoptional

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

createdAtstring · date-time

When the eSIM was assigned to the profile

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 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}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

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

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	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}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

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

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	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}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "profileReference": "1234567890123456",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "eid": "89049032000000000000000000000001",
    "activationCode": "LPA:1$provider.example.com$ACTIVATION_CODE_HERE",
    "pin1": "1234",
    "puk1": "12345678",
    "pin2": "5678",
    "puk2": "87654321",
    "esimVariant": "travel",
    "status": "released",
    "lifecycleStatus": "preactive",
    "provisioned": true,
    "msisdns": [
      {
        "msisdn": "32123456789",
        "primary": true
      }
    ],
    "staticIpAddresses": [
      "192.0.2.10"
    ],
    "numberRegistration": {
      "numberRegistrationReference": "A1B2C3D4",
      "registry": "be_cndb",
      "msisdn": "32470123456",
      "status": "processing",
      "reason": {
        "code": "5130",
        "message": "CustomerAliasLastName is missing"
      }
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

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