---
title: "Create a hosted install link"
method: POST
path: "/v1/esim/sims/{esim_id}/install-links"
tags: ["esims"]
---

# Create a hosted install link

`POST /v1/esim/sims/{esim_id}/install-links`

## Request

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

Creates a link to a hosted installation page for one eSIM. The recipient can open the page without a Bird account. The returned `url` grants access to installation details: share it privately and retain it securely if needed, because later reads do not return it.

The link expires after seven days. Creating another link leaves earlier links valid. Use [Revoke a hosted install link](/docs/api/reference/delete-esim-install-link) to disable a link before expiry. A matching retry with the same `Idempotency-Key` returns the original response while it is retained; after that, a retry creates a new link.

The eSIM must be installable. Returns `409` when the profile cannot be installed, `503` when credentials are temporarily unavailable, or `501` when new hosted links are unavailable. A retained successful response can still be replayed while new links are unavailable.

## Path parameters

- `esim_id` string, required

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `201`

The link was minted. Its url appears here and in no later read.

- EsimInstallLink: A hosted installation page for one eSIM. The recipient does not need a Bird account. The secret URL is returned at creation and cannot be retrieved through later reads.
  - `id` string, required
  - `esim_id` string, required
  - `url` string, uri, required: Private installation URL. Anyone holding it can access installation details until expiry or revocation. Store or share it securely when created; later reads do not return it.
  - `expires_at` string, date-time, required: When the link stops granting access to installation details.
  - `created_at` string, date-time, required: When the link was created.

## 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
- `501`: The operation is not supported
- `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/3e2a50466454?raw)