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

dataobject

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

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

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 during provisioning.

Show properties

msisdnstringrequired

Phone number in E.164 format without the leading +

primarybooleanrequired

Whether this is the eSIM's primary phone number

staticIpAddressesarray of string

Static IP addresses allocated to the eSIM. Optional: absent from the response entirely for eSIM variants that carry no static IP, and an empty array for a variant that carries one when no address is allocated to this eSIM.

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 429Rate limit exceeded 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/%7BprofileReference%7D/esims/%7BesimReference%7D"

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

}

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/%7BprofileReference%7D/esims/%7BesimReference%7D"

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

}

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