Link lifecycle management — create and manage service endpoints bound to SIMs. Includes activations, suspend/resume, SMS, network bars, IMEI lock, and bulk operations.
List links
Paginated list of links in your organisation.
Filters combine with AND semantics; repeatable filters
(compatibility_zones, countries) match any of the provided
values. search does a case-insensitive substring match across
link name, id (as text), and the bound SIM's iccid.
Removed links are excluded from the default listing — once deleted they only surface via the detail endpoint (which returns 410).
query Parameters
pagePage number (1-based).
Page number (1-based).
page_sizeItems per page.
Items per page.
sort_byField to sort by. Omit for default ordering (most recently updated first).
Field to sort by. Omit for default ordering (most recently updated first).
sort_orderSort direction.
Sort direction.
statusFilter by link status.
Filter by link status.
has_simFilter to links with (true) or without (false) a bound SIM.
Filter to links with (true) or without (false) a bound SIM.
has_activationsFilter to links that currently have (true) or don't have (false) active activations.
Filter to links that currently have (true) or don't have (false) active activations.
sim_typeFilter by the bound SIM's physical type (physical / eSIM).
Filter by the bound SIM's physical type (physical / eSIM).
compatibility_zonesFilter by compatibility zone (derived from the bound SIM). Repeatable.
Filter by compatibility zone (derived from the bound SIM). Repeatable.
plan_idFilter to links with an active activation on this plan.
Filter to links with an active activation on this plan.
coverage_idFilter to links with an active activation on a plan tied to this coverage.
Filter to links with an active activation on a plan tied to this coverage.
countriesFilter by the bound SIM's compatible countries (alpha-3 codes). Repeatable.
Filter by the bound SIM's compatible countries (alpha-3 codes). Repeatable.
network_countryFilter by last-known network country (alpha-3).
Filter by last-known network country (alpha-3).
network_connectedFilter to links currently observed as connected to a network.
Filter to links currently observed as connected to a network.
searchFree-text match against link name, id, or the bound SIM's iccid.
Free-text match against link name, id, or the bound SIM's iccid.
List links › Responses
Successful Response
Items on the current page.
totalTotal number of items across all pages.
pageCurrent page number (1-based).
page_sizeItems per page used to compute this response.
pagesTotal number of pages at the current page_size.
Create a link
Create a link bound to a SIM, optionally activating plans on it.
The SIM determines which provider the link belongs to. Supplying
plan_ids activates those plans at creation; omit them to create a
pre-active link that's waiting for its first activation.
Create a link › Request Body
nameCustomer-assigned name for the Link.
sim_idID of the SIM to bind to the Link.
Plans to activate on the Link at creation. Omit to create a pre-active Link.
Create a link › Responses
Link created.
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Detach the bound SIM from multiple links
Delink the SIM from each of the supplied links, asynchronously.
Detach the bound SIM from multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
Detach the bound SIM from multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Delete multiple links
Soft-delete each of the supplied links, asynchronously.
Mirrors DELETE /links/{id} per item — links with a SIM still
attached fail in-item with the same validation_error as the
singular endpoint (delink first).
Delete multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
Delete multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Suspend multiple links
Suspend each of the supplied links, asynchronously.
Mirrors POST /links/{id}/suspend per item — already-suspended or
non-active links fail in-item without affecting the rest.
Suspend multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
Suspend multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Resume multiple links
Resume each of the supplied suspended links, asynchronously.
Resume multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
Resume multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Activate a plan on multiple links
Activate the given plan on each of the supplied links, asynchronously.
Mirrors POST /links/{id}/activations per item — per-link
failures (link not active, no SIM, plan/SIM zone mismatch) are
recorded individually without stopping the rest.
Activate a plan on multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
plan_idPlan to activate (or whose activations to remove) on each link.
Activate a plan on multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Remove a plan's activations from multiple links
Remove the supplied plan's active activations from each link, asynchronously.
Differs from the singular endpoint (DELETE /links/{id}/activations/{activation_id}):
in bulk, activations are identified by plan, not by activation
id — for each link, all active activations of the plan are
removed. Per-link absence of the plan fails that item only.
Remove a plan's activations from multiple links › Request Body
link_idsLinks to act on. Must be non-empty; duplicates are rejected.
plan_idPlan to activate (or whose activations to remove) on each link.
Remove a plan's activations from multiple links › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Get a link
Fetch a single link by id.
For active links the network connectivity status is refreshed
from the upstream system before the response is returned — so the
network_status field reflects the current attach state, not the
last sync.
path Parameters
link_idGet a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Delete a link
Soft-delete a link.
Deletes the upstream resource and marks the link REMOVED locally —
subsequent reads return 410. Active activations on the link are
cascaded to REMOVED. A link that still has a SIM attached cannot
be deleted (422 validation_error); delink first.
Returns 204 No Content — same reasoning as DELETE /plans/{id}
and DELETE /coverages/{id}.
path Parameters
link_idDelete a link › Responses
Link deleted.
Update a link
Patch a link's local-only fields.
name and meta are independent — each is applied only when
explicitly present in the payload. Both are local-only edits (no
upstream calls). meta is a full replace; {} clears it.
Meta validation rules (422 validation_error):
- max 10 root-level keys;
- max nesting depth 3 (root dict counts as depth 1).
path Parameters
link_idUpdate a link › Request Body
New customer-assigned name for the Link.
Replacement meta object. Pass {} to clear; omit to leave unchanged.
Update a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Attach a SIM to a link
Bind a SIM to an existing link.
The link must not already have a SIM, and the SIM must not be
bound to another link. The SIM's compatibility zones must
intersect the link's — otherwise the operation is rejected (422).
On success the link moves to active.
path Parameters
link_idAttach a SIM to a link › Request Body
sim_idID of the SIM to bind to the link.
Attach a SIM to a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Detach the SIM from a link
Detach the SIM currently bound to the link.
The link moves to hold and the SIM becomes free to bind to a
different link. No body — the SIM to remove is determined by the
link itself.
path Parameters
link_idDetach the SIM from a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Bar network types on a link
Bar one or more network types on a link.
Idempotent on a per-type basis: types already barred are filtered out before the upstream call. If every supplied type is already barred, the call is rejected (422) — nothing to do.
path Parameters
link_idBar network types on a link › Request Body
network_typesNetwork types to bar (or unbar). Must be non-empty.
Bar network types on a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Unbar network types on a link
Remove the bar on one or more network types.
Idempotent on a per-type basis: types that aren't currently barred are filtered out before the upstream call. If none of the supplied types are barred, the call is rejected (422) — nothing to do.
path Parameters
link_idUnbar network types on a link › Request Body
network_typesNetwork types to bar (or unbar). Must be non-empty.
Unbar network types on a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Lock a link to its SIM's IMEI
Lock the link to the IMEI of the device its SIM is currently in.
The IMEI is read from the bound SIM — there's no body. After the lock the link only accepts traffic from that specific device; if the SIM is moved to a different device the network rejects it. Requires an attached SIM whose IMEI we've observed.
path Parameters
link_idLock a link to its SIM's IMEI › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Remove the IMEI lock from a link
Remove the IMEI lock from the link.
After this the SIM can move between devices freely.
path Parameters
link_idRemove the IMEI lock from a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
List SMS sent through this link
Paginated history of SMS attempts on this link.
Includes both successful sends and failed attempts. Default order is most recently sent first.
path Parameters
link_idquery Parameters
pagePage number (1-based).
Page number (1-based).
page_sizeItems per page.
Items per page.
sort_byField to sort by. Omit for default ordering (most recently sent first).
Field to sort by. Omit for default ordering (most recently sent first).
sort_orderSort direction.
Sort direction.
List SMS sent through this link › Responses
Successful Response
Items on the current page.
totalTotal number of items across all pages.
pageCurrent page number (1-based).
page_sizeItems per page used to compute this response.
pagesTotal number of pages at the current page_size.
Send an SMS to the link
Send an SMS to the SIM bound to this link.
The message is delivered to the SIM's MSISDN. Every attempt is
persisted — successes return 201 with the sent record; upstream
failures still create a failed history row but bubble up as a
502 to surface the problem to the caller. The link must be
active and have a SIM with an MSISDN.
path Parameters
link_idSend an SMS to the link › Request Body
messageMessage body. 1-80 characters.
Send an SMS to the link › Responses
SMS sent.
idInternal identifier for this send attempt.
messageMessage body that was submitted.
statusOutcome of an SMS send attempt.
sent_atUTC timestamp when the attempt was made.
Reason for the failure when status is failed. Null when status is sent.
Suspend a link
Suspend an active link.
Pauses connectivity on both the upstream system and locally — the
link moves from active to suspended. Only active links can be
suspended (422 otherwise). Resume via POST /links/{id}/resume.
path Parameters
link_idSuspend a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
Resume a link
Resume a suspended link.
Restores connectivity on both the upstream system and locally — the
link moves from suspended back to active. Only suspended links
can be resumed (422 otherwise).
path Parameters
link_idResume a link › Responses
Successful Response
idInternal Link identifier.
statusDomain-level Link (endpoint) status.
Aggregated data usage across all activations on a link.
created_atUTC timestamp when the Link was created.
updated_atUTC timestamp of the last update.
Customer-assigned Link name (optional).
compatibility_zonesCompatibility zones this Link can operate in (derived from the bound SIM when present).
The SIM bound to this Link. Null when no SIM is attached.
Last-known network connectivity for this Link. Refreshed live on the detail endpoint when the Link is active.
barred_network_typesNetwork types currently barred on this Link.
IMEI this Link is locked to. Null when no IMEI lock is in effect.
Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).
List activations on a link
Paginated list of activations on a link.
Removed activations are excluded by default — once an activation has been deleted (or its parent link), it stays in the database but is filtered out of normal listings.
path Parameters
link_idquery Parameters
pagePage number (1-based).
Page number (1-based).
page_sizeItems per page.
Items per page.
sort_byField to sort by. Omit for default ordering (most recently created first).
Field to sort by. Omit for default ordering (most recently created first).
sort_orderSort direction.
Sort direction.
statusFilter by activation status.
Filter by activation status.
plan_idFilter to activations of a specific plan.
Filter to activations of a specific plan.
sourceFilter by origin: manual (customer-initiated) or resubscription (automatic).
Filter by origin: manual (customer-initiated) or resubscription (automatic).
List activations on a link › Responses
Successful Response
Items on the current page.
totalTotal number of items across all pages.
pageCurrent page number (1-based).
page_sizeItems per page used to compute this response.
pagesTotal number of pages at the current page_size.
Activate a plan on a link
Activate a plan on the link.
The link must be active and have a SIM attached; the plan's
compatibility zones must intersect the SIM's. On success the new
activation is returned with usage zero-valued — real numbers
populate once the background usage-collection worker takes its
first snapshot.
path Parameters
link_idActivate a plan on a link › Request Body
plan_idID of the plan to activate on the link.
Activate a plan on a link › Responses
Activation created.
idInternal Activation identifier.
Minimal plan info embedded on ActivationResponse.
Just enough to make sense of the activation without forcing a
follow-up request to /plans/{id} — id, name, and the two
customer-relevant numbers (bundled data, validity).
statusRuntime status of a plan activation on a link.
sourceHow the activation was created.
Data usage summary for a single activation.
created_atUTC timestamp when the activation was created.
updated_atUTC timestamp of the last update.
UTC timestamp when the activation became active. Null until activation completes.
UTC timestamp when the activation is scheduled to expire. Null when no fixed end is set.
Remove an activation from a link
Soft-delete an activation.
Removes the activation upstream and marks it REMOVED locally.
Returns 204 No Content — same convention as the other delete
endpoints in the customer router.
path Parameters
link_idactivation_idRemove an activation from a link › Responses
Activation removed.