RESTful CMP API Integration for Automated eSIM Remote Provisioning Workflows
Definition: A RESTful CMP API for eSIM provisioning is an HTTP interface that lets enterprise systems order, track and switch eSIM profiles on IoT devices as asynchronous jobs, instead of operators handling each change by hand in a portal.
The short answer for integration teams: treat every eSIM profile change as a long-running job, not as a single API call. A profile download involves the operator, the SM-DP+ profile server, the eSIM IoT remote Manager (eIM) and a device that may be asleep for hours. An API that returns “success” the moment it receives a request hides exactly the failures you need to see. Design around job resources, idempotent retries and explicit state, and lean on HTTP semantics as defined in RFC 9110 rather than inventing your own.
What actually happens behind one “switch profile” request
In the GSMA eSIM architecture, the operator prepares a profile on the SM-DP+ through the ES2+ interface, using functions such as DownloadOrder and ConfirmOrder. Under SGP.32, the eIM then sends the device’s IoT Profile Assistant an eIM Package that triggers the download. The device fetches the Bound Profile Package from the SM-DP+, installs it, and reports back through notifications. Only after the new profile is enabled and attached to a network do you know the change worked.
A CMP sits above these interfaces and gives your ERP, device platform or service desk one place to start and observe the process. The stages it should expose look roughly like this:
| Stage | Who acts | What the API should expose | Typical failure to surface |
|---|---|---|---|
| Order accepted | CMP | A job ID and its status URL | Invalid EID, unknown device, missing entitlement |
| Profile reserved | Operator and SM-DP+ (ES2+) | Profile reference such as ICCID once assigned | No profile stock or no agreement for that operator |
| Download triggered | eIM to IPA (ESipa) | Queued or delivered state of the eIM Package | Device offline, package expired |
| Profile installed | Device eUICC | Install result and timestamp from notifications | Download interrupted, eUICC memory full |
| Profile enabled and attached | Device and network | First attach or first data session evidence | Attach rejected, fallback to previous profile |
| Job closed | CMP | Final state plus audit trail | Partial success that needs manual review |
The exact stage names differ between platforms. What matters is that your integration can distinguish “queued” from “installed” from “working”, because each one triggers a different operational response.
Using HTTP semantics instead of fighting them
Return 202, not 200, for work that is not finished
RFC 9110 defines 202 Accepted for a request that has been accepted for processing but not completed. That fits a profile order exactly. The response should point to a job resource the client can poll with GET, or the CMP can push status changes to a webhook. Polling a job resource is safe by definition, since GET is a safe method.
Make retries harmless
Under RFC 9110, PUT and DELETE are idempotent and POST is not. Mobile networks, gateways and batch scripts all retry, so a duplicated POST that orders two profiles for one device is a real risk. Two common designs avoid it: model the desired state with PUT on a device-scoped resource, or accept a client-generated idempotency key on POST. The Idempotency-Key header is still an IETF draft rather than a finished RFC, so check whether the platform you integrate with supports it.
Protect against conflicting updates
When two systems can change the same device, use conditional requests. An ETag on the device or subscription resource, combined with If-Match on the update, lets the server answer 412 Precondition Failed instead of silently overwriting a newer change. 409 Conflict is the right answer when the request clashes with the current state, for example a switch requested while another switch is still running.
Respect back-pressure
Bulk rollouts hit rate limits. RFC 9110 defines 503 Service Unavailable and the Retry-After header; 429 Too Many Requests comes from RFC 6585. Clients should honor Retry-After and use backoff with jitter rather than hammering the API in a loop.
Security and responsibility boundaries
An API that can change which network a device uses is a high-value target. Separate credentials by function so a reporting integration cannot order or delete profiles. Scope keys or OAuth clients to the smallest set of devices and actions they need, and rotate them on a schedule. Log every state-changing call with the caller identity, the device identifiers and the job ID. Those logs matter in a dispute with an operator and in your own incident reviews.
Be clear about where each party’s responsibility ends. The CMP can confirm that it sent an order and what the network reported back. It does not guarantee that a particular operator will accept the order, that coverage exists at the device location, or that the device firmware handles the profile correctly. Operator authorization, coverage and any SLA have to be agreed commercially and confirmed during project validation.
Designing for devices you cannot visit
The reason to automate eSIM provisioning is usually to avoid a truck roll. That only works if the workflow can recover on its own. Three habits help. First, never disable the last known working profile until the new one has proven traffic. Second, rely on the fallback behavior of the eUICC when a new profile fails to attach, and record when it fires. Third, roll out in batches with a stop condition, such as halting when more than a set share of jobs end in fallback. A remote recovery that works for 99 devices and strands one in a pump station still costs a field visit, so build the failure path before the happy path.
Integration checklist
- Every state-changing call returns a job ID; job status can be fetched with GET and, ideally, pushed to a webhook.
- Retries cannot create duplicate orders.
- Device and subscription resources carry ETags, and updates use If-Match.
- Error responses carry machine-readable codes that separate client errors, operator rejections and device-side failures.
- Rate limits and Retry-After are documented and tested with your largest planned batch.
- Credentials are split by role and every change is auditable.
- A sandbox or test fleet exists for rehearsing switches before production.
How this maps to Quanqiu IoT
Before writing integration code, buyers should confirm what the connectivity provider’s CMP exposes for their specific SIM and eSIM type, because API coverage differs between products and operators. Our guide to IoT SIM API integration for lifecycle automation covers the non-eSIM side, such as activation, suspension and usage alerts, and how CMP platforms manage global IoT SIM deployments explains the portal and reporting layer. For the device-side architecture, read our explainer on SGP.32 remote provisioning for constrained devices.
Small Global IoT SIM pilots rarely need custom API work, and catalog plans are fine for them. Automated eSIM provisioning across several countries is a project decision: device count, eUICC type, operator mix and the API scope you need all affect the commercial model. Send those details through the contact page to request a project quote and we will confirm what can be integrated before you commit engineering time.
FAQ
Why not make the profile switch a synchronous API call?
Because the device may be asleep, out of coverage or mid-download when you send the request. A synchronous call either times out or reports success too early. An accepted job with trackable states reflects what is really happening.
Should we poll job status or use webhooks?
Use webhooks for timely updates and keep polling as a fallback for reconciliation. Webhook deliveries can be lost or duplicated, so the receiving side should be idempotent and check the job resource when in doubt.
What identifiers should the API use for eSIM devices?
The EID identifies the eUICC and stays constant, while each installed profile has its own ICCID. Key device-level operations on the EID and profile-level operations on the ICCID, and keep both in your asset records.
Is REST the only option for CMP integration?
No. Some platforms also offer SOAP, bulk file exchange or message queues. REST over HTTPS is the most common choice for new integrations, but the interface has to match what the provider actually supports.
How do we test a provisioning workflow without risking production devices?
Ask for a sandbox or a small set of test eUICCs, and rehearse the full sequence including a forced failure and fallback. Only promote the workflow to production batches after the failure path has been observed working.