> 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/integration-flow.md).

# Integration Flow

Use this sequence to synchronize the catalog, provision eSIMs, and monitor each package assignment.

### Catalog synchronization

```http
GET /api/v1/packages?page=1&perPage=100
Authorization: Bearer <TOKEN>
Accept: application/json
```

Iterate through all pages using the returned pagination metadata. Store the catalog identifiers, allowance, duration, availability, coverage when returned, and your client-specific prices.

### Provisioning

Follow **Provision an eSIM** to create a B2C client, select unallocated inventory, find compatible packages, assign the package, and retrieve activation data for the end user. Store `ICCID -> esimId` when selecting or assigning the eSIM.

The `POST /api/v1/esims/assign-package` response also provides the assigned eSIM ID and ICCID.

### Assignment synchronization

```http
GET /api/v1/esims?scopeBy=package&allocated=true&page=1&perPage=100
Authorization: Bearer <TOKEN>
Accept: application/json
```

Iterate through all pages. For every assignment, store the parent ICCID, `esimId`, and `packageEsimId` from `packageEsims[].id`. Keep multiple assignments per eSIM rather than replacing them with the first array entry.

### Customer usage display

Display total allowance, used data, remaining data, activation date, expiration date, and usage and technical assignment statuses. Use the mappings in **Usage Fields**.

For actual validity on an eSIM, use `usageStartAt` / `usageExpireAt`. Catalog `package.start` / `package.end` describe product availability.

### Refresh usage

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

```json
{
  "packageEsimId": "e693b396-3507-4f32-8604-4352418ddc15"
}
```

Select the relevant assignment using its ID, `status`, `queuePosition`, and usage fields. Calculate remaining traffic as `rate_group_allowance - rate_group_usage` in the reported unit. Usage is near real-time and may have a short mobile-network reporting delay.

### Ongoing management

Use **Top Up an eSIM** for additional packages, **Remove a Package** to remove a specific assignment, and **Release an eSIM** to unassign the eSIM from its client. Keep activation data and credentials private.
