---
title: "Get eSIM install credentials"
method: GET
path: "/v1/esim/sims/{esim_id}/credentials"
tags: ["esims"]
---

# Get eSIM install credentials

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

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.

## Path parameters

- `esim_id` string, required

## Headers

- `Accept-Language` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The install credentials.

- EsimCredentials: Installation details for an eSIM. Keep activation codes, installation links, QR images, and manual setup credentials private because they can grant access to the profile. Use fields with a value and follow the returned device instructions.
  - `esim_id` string, required
  - `ios_install_url` string, 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_url` string, uri, nullable, required: Android installation link. Currently unavailable; returns null. Use the returned Android instructions for manual setup.
  - `qr_code_url` string, 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_code` string, required: Raw activation string for manual entry in device settings.
  - `smdp_address` string, required: SM-DP+ server address, for building a custom install flow.
  - `matching_id` string, required: Matching ID component of the activation code, for building a custom install flow.
  - `confirmation_code` string, nullable: Confirmation code requested during installation, when available. Null means the requirement is unknown; it does not confirm that a code is unnecessary.
  - `apn` string, 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_required` boolean, nullable, required: Whether data roaming must be enabled. Null means the requirement is unknown. When true, `instructions` includes a step to enable roaming.
  - `instructions` EsimInstallationInstructions, required: Device installation steps based on the available credentials. Follow the list for the recipient’s device.
    - `language` string, required: A language tag in BCP-47 form, for example `en` or `pt-BR`.
    - `ios` string[], required: Ordered steps for iOS devices.
    - `android` string[], required: Ordered steps for Android devices.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)