Operations

An operation is one command for one eUICC, addressed by its EID: enable, disable or delete a profile, download a profile, query the card's data, manage its eIM entries, or a package of several of these. eimHub queues it; the card's IPA collects it at its next poll, and the result comes back later. Operations therefore complete asynchronously.

Creating an operation

curl -s -X POST https://app.eimhub.example/api/v1/euiccs/89049032123451234512345678901234/operations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action": "ENABLE", "parameters": {"iccid": "8988247000000000012"}, "client_reference": "erp-4711"}'

The 201 answer is the operation, ACTIVE / NOT_STARTED. It may carry warnings[]: things eimHub's view of the card suggests may fail (for example PROFILE_ALREADY_ENABLED). Warnings never block the create — the card decides. Add ?dry_run=true to see the checks and warnings without creating anything.

The two statuses

Each operation has an operation_status (its lifecycle) and a command_status (where the command is):

`operation_status`	`command_status`	Meaning
`ACTIVE`	`NOT_STARTED`	queued; the card has not collected it yet
`ACTIVE`	`IN_PROGRESS`	the card's IPA has collected it; the result is awaited
`ACTIVE`	`AWAITING_CONFIRMATION`	delivered, and eimHub waits for the card's signed notification as evidence (below)
`COMPLETED`	`SEND_SUCCESS`	done; `outcome[]` holds the card's results
`COMPLETED`	`SEND_FAILURE`	the card or the procedure reported an error; `error_code` names it
`EXPIRED`	`CANCELLED`	the card did not collect it within its validity period
`CANCELLED`	`CANCELLED`	cancelled before delivery, superseded by a retry, or its eUICC was deleted

An operation is finished when operation_status is no longer ACTIVE.

`AWAITING_CONFIRMATION`

Some cards answer an enable or disable without result data; then the card's eUICC-signed notification is the evidence that the command took effect, and the operation waits in AWAITING_CONFIRMATION until it arrives. An indirect profile download waits there too, for its Profile Installation Result, once the profile package has been delivered. The operation is not delivered again while it waits. If the evidence never comes, cancel or retry it (POST /api/v1/operations/{operation_id}:retry); a retry builds a new command.

Following an operation

Webhooks (recommended): operation.completed, operation.failed, operation.expired, operation.cancelled and operation.awaiting_confirmation tell you when the status changes; see Webhooks.
Polling: GET /api/v1/operations/{operation_id}, or the list GET /api/v1/operations?filter[client_reference]=erp-4711. Poll sparingly: a card may poll eimHub only every few minutes or hours.

Validity and cancellation

An operation that the card does not collect within its validity period expires. Cancel an operation that has not been delivered with POST /api/v1/operations/{operation_id}:cancel.