---
title: "Create a hosted install link"
canonical: "https://bird.com/docs/api/reference/create-esim-install-link"
---

# Create a hosted install link

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

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.

## Code samples

**CLI**

```sh
bird esim install-links create <esim-id>
```

Examples: [CLI](/docs/api/reference/create-esim-install-link.cli.md) · [MCP](/docs/api/reference/create-esim-install-link.mcp.md) · [cURL](/docs/api/reference/create-esim-install-link.curl.md)

## Example response `201`

```json
{
  "id": "eil_01krdgeqcxet5s7t44vh8rt9mg",
  "esim_id": "esm_01krdgeqcxet5s7t44vh8rt9mg"
}
```

## Path parameters

- `esim_id` (string): eSIM ID.

## Response body

- `id` (string, required)
- `esim_id` (string, required)
- `url` (string, 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, required): When the link stops granting access to installation details.
- `created_at` (string, required): When the link was created.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)