> For the complete documentation index, see [llms.txt](https://en-api.decisiontele.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en-api.decisiontele.com/esim-api/esims/provision-an-esim.md).

# Provision an eSIM

Step-by-step guide to create a client, allocate an eSIM, assign a data package, and retrieve the activation QR code.

Follow these steps to provision an eSIM for an end user. All credentials and identifiers below are placeholders.

### 1. Create a B2C Client

Create a client of type `b2c`. B2C clients do not have platform access and cannot create packages.

#### Request

```bash
curl --request POST "https://esim-api.it-decision.com/api/v1/clients" \
  --header "Authorization: Bearer <TOKEN>" \
  --form "name=My B2C Client" \
  --form "email=b2c-client@example.com" \
  --form "type=b2c" \
  --form "identifier=my_b2c_client_001" \
  --form "platformAccess=false" \
  --form "packageCreation=false"
```

#### Result

The response contains the new `clientId`. Save it for assignment.

### 2. Get an Available eSIM

Retrieve unallocated eSIMs.

#### Request

```http
GET /api/v1/esims?allocated=false
Authorization: Bearer <TOKEN>
Accept: application/json
```

#### Result

Select `data[].id` as `esimId` and store the mapping `ICCID -> esimId` using the same item’s `iccid`.

### 3. Find Compatible Packages

Retrieve packages compatible with the selected eSIM.

#### Request

```http
POST /api/v1/esims/find-packages
Authorization: Bearer <TOKEN>
Content-Type: application/json
Accept: application/json
```

```json
{
  "esims": ["<ESIM_ID>"]
}
```

#### Result

Select and save the required `packageId` from the compatible packages returned by the API.

### 4. Assign eSIM, Package, and Client

Assign the selected eSIM and compatible data package to the B2C client.

#### Request

```http
POST /api/v1/esims/assign-package
Authorization: Bearer <TOKEN>
Content-Type: application/json
Accept: application/json
```

```json
{
  "esims": ["<ESIM_ID>"],
  "packages": ["<PACKAGE_ID>"],
  "client": "<CLIENT_ID>"
}
```

| Body field | Description                              |
| ---------- | ---------------------------------------- |
| `esims`    | Selected eSIM identifiers.               |
| `packages` | Compatible package identifiers.          |
| `client`   | B2C client identifier created in step 1. |

#### Result

The eSIM becomes allocated to the client and the selected package is assigned. Save the eSIM ID and ICCID returned by the assignment response. For actual package activation and expiration, use `usageStartAt` and `usageExpireAt`.

Retrieve the eSIM with assigned packages and store `packageEsims[].id` as `packageEsimId` for usage monitoring.

### 5. Retrieve the QR Code

Retrieve activation data for the allocated eSIM.

#### Request

```http
GET /api/v1/esims?allocated=true&ids=<ESIM_ID>
Authorization: Bearer <TOKEN>
Accept: application/json
```

#### Result

The response returns the QR code or activation data. Provide it securely to the intended end user so they can install and activate the eSIM. Do not include actual activation data in public examples.
