esims

Get eSIM install credentials

Returns installation details for an eSIM, including an iOS installation link, an activation code, and manual setup components. Android installation links and hosted QR image URLs are currently unavailable and return null. Read instructions for device-specific steps in the returned language.

Keep installation details private: they can grant access to the profile. A null apn, confirmation_code, or data_roaming_required means the requirement is unknown; it does not mean the setting is unnecessary. Returns 409 when the profile cannot be installed and 503 when credentials are temporarily unavailable.

get/v1/esim/sims/{esim_id}/credentials

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/sims/{esim_id}/credentials
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

esim_idstring required
Example:esm_01krdgeqcxet5s7t44vh8rt9mg

eSIM ID.

Headers

Accept-Languagestring

Preferred languages for the instructions field, as a standard weighted Accept-Language list. Bird serves the first one it stocks, then a variant sharing a requested base language, then English.

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The install credentials.

esim_idstring required
ios_install_urlstring uri nullable required

One-tap install link for iOS 17.4 and later, derived from the activation code. Null when a valid link cannot be derived for this eSIM.

android_install_urlstring uri nullable required

Android installation link. Currently unavailable; returns null. Use the returned Android instructions for manual setup.

qr_code_urlstring uri nullable required

Hosted QR image URL. Currently unavailable; returns null. Use the activation code in your own installation flow or provide a hosted installation page.

activation_codestring required

Raw activation string for manual entry in device settings.

smdp_addressstring required

SM-DP+ server address, for building a custom install flow.

matching_idstring required

Matching ID component of the activation code, for building a custom install flow.

confirmation_codestring nullable

Confirmation code requested during installation, when available. Null means the requirement is unknown; it does not confirm that a code is unnecessary.

apnstring nullable required

Access point name for mobile data, when available. Null means no APN information is available; it does not confirm automatic configuration.

data_roaming_requiredboolean nullable required

Whether data roaming must be enabled. Null means the requirement is unknown. When true, instructions includes a step to enable roaming.

Example response

{
  "esim_id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
  "activation_code": "LPA:1$smdp.example.com$K2-1AbCdE-2FgHiJ",
  "smdp_address": "smdp.example.com",
  "apn": "internet",
  "instructions": {
    "language": "pt-BR"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.