Telkor API

Schemas

ActivationCreateRequest

Request body for `POST /links/{link_id}/activations`.

plan_id

string · uuid · required

ID of the plan to activate on the link.

ActivationDataUsageSummaryResponse-Output

Data usage summary for a single activation.

allocated_mib

string · pattern: ^(?!^[-+.]*$)[+-]?0*… · required

Total MiB allocated to the activation when it started.

remaining_mib

string · pattern: ^(?!^[-+.]*$)[+-]?0*… · required

MiB still available on the activation.

used_mib

string · pattern: ^(?!^[-+.]*$)[+-]?0*… · required

MiB consumed so far (allocated - remaining).

ActivationPlanSummary

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).

id

string · uuid · required

Internal Plan identifier.

name

string · required

Customer-assigned Plan name.

included_data_mb

integer · min: 0 · required

Bundled data, in MB.

validity_days

integer · min: 1 · required

Validity, in days.

ActivationResponse

A plan activation on a link, as visible to the caller's organisation. Hides internal correlation/sync fields (`provider_id`, `synced_at`). `usage` is zero-valued until the background usage-collection worker takes its first snapshot for the activation.

id

string · uuid · required

Internal Activation identifier.

object · required

The plan this activation is an instance of.

Example: {"id":"b14d2a91-1111-2222-3333-444455556666","included_data_mb":1024,"name":"Roaming Pilot 1 GB / 30d","validity_days":30}

status

string · enum · required

Runtime status of the activation.

Enum values:

active

expired

exhausted

removed

source

string · enum · required

How the activation was created: manual (customer-initiated) or resubscription (automatic).

Enum values:

manual

resubscription

object · required

Aggregated data usage for the activation.

Example: {"allocated_mib":"1024.00","remaining_mib":"812.55","used_mib":"211.45"}

created_at

string · date-time · required

UTC timestamp when the activation was created.

updated_at

string · date-time · required

UTC 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.

ActivationSortField

string · enum

Enum values:

created_at

updated_at

status

activated_at

expires_at

Customer-visible sort fields for the activation list endpoint.

Mirrors the domain enum 1:1 — no internal sync timestamps to hide on this entity.

ActivationSource

string · enum

Enum values:

manual

resubscription

How the activation was created.

ActivationStatus

string · enum

Enum values:

active

expired

exhausted

removed

Runtime status of a plan activation on a link.

ActivationType

string · enum

Enum values:

immediate

on_first_data_usage

When the plan activates after being assigned to a link.

BulkTaskItemResponse

A single item within a bulk task — one input/outcome pair. `reference_id` is the per-action target identifier the worker used (e.g. a SIM iccid, a link UUID-as-string), letting the customer correlate items back to their input list. `payload` is the input the worker received for this item; `result` and `error` are the outcome side — exactly one is populated for terminal items (`success` → `result`, `failed` → `error`).

id

string · uuid · required

Internal identifier for this item.

reference_id

string · required

The per-action target identifier the worker used for this item (SIM iccid, link id, etc.). Lets you correlate failures back to your input list.

status

string · enum · required

Per-item lifecycle status.

Enum values:

pending

running

success

failed

object · required

The input the worker received for this item.

created_at

string · date-time · required

UTC timestamp when the item was created.

updated_at

string · date-time · required

UTC timestamp of the last update.

Worker output for successful items. Null for non-success statuses.

Failure reason for failed items. Null otherwise.

BulkTaskItemSortField

string · enum

Enum values:

created_at

updated_at

status

Customer-visible sort fields for the items list endpoint.

BulkTaskItemStatus

string · enum

Enum values:

pending

running

success

failed

Status of a single item within a bulk task.

BulkTaskResponse

A bulk task header as visible to the caller's organisation. `pending_items` is derived (`total - completed - failed`) so the customer can poll a single counter to know when work is finished. Items are NOT included here — fetch via `GET /tasks/{id}/items`.

id

string · uuid · required

Internal bulk-task identifier.

type

string · enum · required

What bulk operation this task represents.

Enum values:

sim_provisioning

link_delink_sim

link_delete

link_suspend

link_resume

link_add_activation

link_delete_activation

status

string · enum · required

Lifecycle status of the task itself: pending (queued), running (worker picked it up), completed (all items processed — some may still have failed; check counters), failed (worker job crashed).

Enum values:

pending

running

completed

failed

total_items

integer · min: 0 · required

Total number of items the task was created with.

completed_items

integer · min: 0 · required

Items processed successfully.

failed_items

integer · min: 0 · required

Items that the worker could not process.

pending_items

integer · min: 0 · required

Items still waiting to be processed (total - completed - failed).

created_at

string · date-time · required

UTC timestamp when the task was created.

updated_at

string · date-time · required

UTC timestamp of the last update.

BulkTaskSortField

string · enum

Enum values:

created_at

updated_at

status

Customer-visible sort fields for the task list endpoint.

BulkTaskStatus

string · enum

Enum values:

pending

running

completed

failed

Status of a bulk task.

BulkTaskType

string · enum

Enum values:

sim_provisioning

link_delink_sim

link_delete

link_suspend

link_resume

link_add_activation

link_delete_activation

Type of bulk operation.

CallerOrganizationResponse

Customer-visible view of the caller's own organisation. Returned by `GET /org`. Trimmed down from the superadmin `OrganizationResponse`: `keycloak_org_id` and the `settings` block (provider integration config) are hidden — neither is actionable from the customer side.

id

string · uuid · required

Internal identifier for your organisation. Useful when contacting support.

Example: 8a4b6df0-aaaa-bbbb-cccc-ddddeeeeffff

name

string · required

Human-readable display name.

Example: Speakeasy

created_at

string · date-time · required

UTC timestamp the organisation was created.

Example: 2026-01-15 08:30:00+00:00

updated_at

string · date-time · required

UTC timestamp the organisation was last updated.

Example: 2026-04-20 11:42:00+00:00

CompatibilityZone

string · enum

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

User-friendly compatibility zone identifiers.

ConnectedRAT

string · enum

Enum values:

2g_3g

unknown

RAT type reported in live network connectivity status.

CostServiceName

string · enum

Enum values:

DATA

SMS-MO

SMS-MT

IOT

Service categories that usage is billed against.

CostUsageLineResponse-Output

A single usage line from a monthly cost snapshot. `usage` is a physical quantity (MB for `DATA`, count for `SMS-MO` / `SMS-MT` / `IOT`). `amount` is always in the snapshot's `currency` (€ today). `operators` is the set of our operators this usage was attributed to at collection time — may be empty if the collector could not map the provider's keys to any of the org's operators.

Service category (DATA / SMS-MO / SMS-MT / IOT). May be null for lines the provider didn't categorise.

Physical quantity (MB for DATA, count for SMS/IOT).

Example: 1024.50

Money in the snapshot's currency.

Example: 12.34

object[]

Operators this usage was attributed to. Empty when no mapping was possible.

CoverageCreateRequest

Create a new coverage by naming a set of operators. All operators must belong to the same compatibility zone family (i.e. resolve to the same provider) — mixed-provider coverages are rejected with 422. Operators must already exist in the caller's catalogue; unknown ids return 404. Names are not constrained to be unique — pick any label that helps you identify the coverage.

name

string · minLength: 1 · required

Display name for the coverage. Not required to be unique.

Example: EU + UK

operator_ids

string[] · minItems: 1 · required

Operator ids to include in the coverage. Must be non-empty.

CoverageOperatorsRequest

Add or remove operators from an existing coverage. Shared by `POST /coverages/{id}/operators` and `DELETE /coverages/{id}/operators` — same wire shape, different semantics. Both endpoints are **idempotent**: ids already present (on add) or already absent (on remove) are silently skipped. Operators must already exist in the caller's catalogue; unknown ids return 404. Adding operators from a different compatibility-zone family than the coverage already spans is rejected with 422. Removing all operators is rejected with 422.

operator_ids

string[] · minItems: 1 · required

Operator ids to add or remove. Must be non-empty.

CoverageRenameRequest

Rename an existing coverage (local-only change). The coverage's `name` is stored in our DB and used everywhere the customer sees it. The provider's synthesized id is unaffected. Names are not constrained to be unique — pick any label that helps you identify the coverage in your UI.

name

string · minLength: 1 · required

New display name for the coverage. Not required to be unique.

Example: EU + UK (renamed)

CoverageResponse

A coverage zone as visible to the caller's organisation. `compatibility_zones` is computed from the embedded operators (not stored) — it tells the caller which provider ecosystems this coverage spans. `provider_id` is intentionally hidden: it's an internal correlation id and the user-facing `name` is what the customer assigned.

id

string · uuid · required

Internal coverage identifier.

name

string · required

Coverage display name.

Example: EU + UK

created_at

string · date-time · required

UTC timestamp when the coverage was created.

updated_at

string · date-time · required

UTC timestamp of the last update.

compatibility_zones

string[]

Compatibility zones spanned by the operators in this coverage.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

object[]

Operators included in this coverage.

CoverageSortField

string · enum

Enum values:

name

created_at

updated_at

Customer-visible sort fields for the coverage list endpoint.

Subset of the domain sort fields — only fields actually surfaced on CoverageResponse are sortable. Sorting by hidden fields would confuse clients that can't see the resulting order. status is excluded because customer-facing responses are always active (removed coverages are filtered from list and 410 from get).

CoverageSummary

Minimal coverage info embedded on other resources' responses. Enough to identify a coverage without bloating the host payload with the full operator list. Used on `PlanResponse` so a customer can see which coverage a plan applies to without a second request.

id

string · uuid · required

Internal coverage identifier.

name

string · required

Coverage display name.

Example: EU + UK

compatibility_zones

string[]

Compatibility zones spanned by the coverage.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

DataCapSchema

Wire shape for a plan's data cap. A cap fires when usage hits `threshold_mb` within the period defined by `period` * `period_multiplier` (e.g. period=monthly, period_multiplier=1 = once a month). `action` is what happens at threshold — currently always a throttle-down to a fixed speed.

threshold_mb

integer · min: 0 · required

Usage threshold in MB.

period

string · enum · required

Base period (daily or monthly).

Enum values:

daily

monthly

period_multiplier

integer · min: 1 · required

Number of base periods between resets.

action

string · enum · required

Action applied at threshold.

Enum values:

throttle_256kbps

throttle_384kbps

throttle_512kbps

throttle_1mbps

throttle_2mbps

throttle_5mbps

throttle_10mbps

throttle_20mbps

ESimProfileStatus

string · enum

Enum values:

installed

downloaded

enabled

disabled

deleted

error

eSIM profile status.

ErrorResponse

Standard error response body. Three fields with clear, non-overlapping roles: - `message` — human-readable description (read by humans skimming logs / UIs). - `code` — machine-readable identifier for the failure class (e.g. `entity_not_found`, `upstream_unavailable`). Clients branch on this. - `details` — optional structured machine-readable context (e.g. the entity name and identifiers for a 404), so clients don't have to regex-parse `message` to act on it.

message

string · required

Human-readable description. For 5xx errors this is a generic message; the real cause is in our server logs.

code

string · required

Stable machine-readable identifier for the failure class (e.g. entity_not_found, validation_error, upstream_unavailable).

Structured context for the error, when available (e.g. {entity, identifiers} for not-found / duplicate cases). Absent for 5xx responses.

Default: null

LimitAction

string · enum

Enum values:

throttle_256kbps

throttle_384kbps

throttle_512kbps

throttle_1mbps

throttle_2mbps

throttle_5mbps

throttle_10mbps

throttle_20mbps

Action when data cap threshold is exceeded.

LimitPeriod

string · enum

Enum values:

daily

monthly

Base time window for data cap reset.

LinkAttachSIMRequest

Request body for `POST /links/{id}/sim` — attach a SIM to a link.

sim_id

string · uuid · required

ID of the SIM to bind to the link.

LinkBulkActivationRequest

Shared payload for the activation-targeted bulk-link actions. Used by `bulk-add-activation` (activate plan X on each link) and `bulk-delete-activation` (remove all active activations of plan X from each link). The bulk delete-activation deliberately targets activations by **plan**, not by activation id — in bulk you typically know "drop plan X from these N links", not the per-link activation UUIDs.

link_ids

string[] · minItems: 1 · maxItems: 5000 · required

Links to act on. Must be non-empty; duplicates are rejected.

plan_id

string · uuid · required

Plan to activate (or whose activations to remove) on each link.

LinkBulkRequest

Shared payload for the simpler bulk-link actions. Used by `bulk-delink-sim`, `bulk-delete`, `bulk-suspend`, and `bulk-resume` — all four operate on a flat list of link ids with no per-item parameters. Per-item failures (state mismatch, missing SIM, upstream rejection) are recorded against the offending item only and the task keeps processing the rest.

link_ids

string[] · minItems: 1 · maxItems: 5000 · required

Links to act on. Must be non-empty; duplicates are rejected.

LinkCreateRequest

Request body for `POST /links`. A SIM is required at creation — it determines the provider the Link belongs to and binds the two together in one call. `plan_ids`, when supplied, activates the Link immediately with those plans; omitting them creates a Link in `pre_active` waiting for first activation.

name

string · minLength: 1 · maxLength: 100 · required

Customer-assigned name for the Link.

sim_id

string · uuid · required

ID of the SIM to bind to the Link.

Plans to activate on the Link at creation. Omit to create a pre-active Link.

LinkDataUsageSummaryResponse-Output

Aggregated data usage across all activations on a link.

total_used_mib

string · pattern: ^(?!^[-+.]*$)[+-]?0*… · required

Total MiB used across all activations on the link.

activation_count

integer · min: 0 · required

Number of activations contributing to the total.

LinkNetworkBarsRequest

Request body for `POST /links/{id}/network-bars` and `POST /links/{id}/network-bars/remove`. The same shape covers both add and remove — symmetrical with the coverage operators convention (`CoverageOperatorsRequest` reused by add + remove).

network_types

string[] · minItems: 1 · required

Network types to bar (or unbar). Must be non-empty.

Enum values:

LTE-M

NB-IOT

LinkResponse

A Link as visible to the caller's organisation. Hides internal correlation/sync fields (`provider`, `provider_id`, `synced_at`, `last_usage_collected_at`). The bound SIM is exposed as a slim `LinkSIMSummary`; full SIM detail is reachable via the SIM router. `usage` is the aggregated data-usage summary across the link's activations — refreshed by the background usage-collection worker, not on every read.

id

string · uuid · required

Internal Link identifier.

status

string · enum · required

Lifecycle status of the Link.

Enum values:

active

suspended

hold

removed

object · required

Aggregated data usage across the Link's activations.

Example: {"activation_count":3,"total_used_mib":"1234.56"}

created_at

string · date-time · required

UTC timestamp when the Link was created.

updated_at

string · date-time · required

UTC timestamp of the last update.

Customer-assigned Link name (optional).

compatibility_zones

string[]

Compatibility zones this Link can operate in (derived from the bound SIM when present).

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

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_types

string[]

Network types currently barred on this Link.

Enum values:

LTE-M

NB-IOT

IMEI this Link is locked to. Null when no IMEI lock is in effect.

object

Free-form customer metadata. Max 10 root-level keys, max nesting depth 3 (the root dict counts as depth 1).

LinkSIMSummary

Minimal SIM info embedded on `LinkResponse`. Mirrors the `LinkSummary` shape on `SIMResponse` — just enough to identify the bound SIM without forcing a follow-up request.

id

string · uuid · required

Internal SIM identifier.

iccid

string · required

ICCID — the SIM's printed serial number.

status

string · enum · required

Lifecycle status of the SIM.

Enum values:

available

active

suspended

inventory

sim_type

string · enum · required

Physical SIM or eSIM.

Enum values:

physical

esim

MSISDN (phone number) assigned to the SIM, if any.

LinkSendSMSRequest

Request body for `POST /links/{id}/sms` — send an SMS to the link's SIM. Length cap of 80 chars matches what the upstream system accepts in a single SMS payload; the service enforces the same limit and a longer / empty message is rejected at parse time.

message

string · minLength: 1 · maxLength: 80 · required

Message body. 1-80 characters.

LinkSortField

string · enum

Enum values:

name

status

created_at

updated_at

Customer-visible sort fields for the link list endpoint.

Subset of the domain sort fields — drops synced_at and last_usage_collected_at (internal sync timestamps).

LinkStatus

string · enum

Enum values:

active

suspended

hold

removed

Domain-level Link (endpoint) status.

LinkSummary-Output

Minimal Link info embedded on `SIMResponse`. Enough to identify the Link a SIM is bound to without bloating the SIM payload. Customers can fetch full Link detail via the Link router once that's built.

id

string · uuid · required

Internal Link identifier.

status

string · enum · required

Lifecycle status of the Link.

Enum values:

active

suspended

hold

removed

Customer-assigned Link name (optional).

Last-known network connectivity for this Link. Null if never observed.

LinkUpdateRequest

Request body for `PATCH /links/{id}` (partial update). Currently covers two local-only fields: - `name` — rename the Link. Whitespace-trimmed; non-null when present. - `meta` — replace the meta object wholesale. Must satisfy the same shape constraints as the domain validator (≤10 root keys, max depth 3). Sending `{}` clears the meta. Fields omitted entirely are left unchanged. Explicit `null` is rejected on both — `meta` cannot be unset (use `{}`), and `name` cannot be cleared via this endpoint.

New customer-assigned name for the Link.

Replacement meta object. Pass {} to clear; omit to leave unchanged.

NetworkStatusResponse

Last-known network connectivity status for a Link. Cached on the Link by the refresh worker; null while a Link has never been observed connected. `country` is the alpha-3 code so it matches the rest of the wire format.

Operator the Link is currently attached to.

ISO 3166-1 alpha-3 country code of the operator.

Example: DEU

Radio access technology the Link is currently using.

Policy state applied to the Link by the network.

NetworkType

string · enum

Enum values:

LTE-M

NB-IOT

Supported network technology types.

OperatorResponse

A telecom network operator as visible to the caller's organisation. `tadig` is the standardised carrier code used across providers; `compatibility_zone` indicates which provider ecosystem this operator belongs to.

id

string · uuid · required

Internal operator identifier.

name

string · required

Operator display name.

Example: Vodafone DE

tadig

string · required

Standardised TADIG operator code.

Example: DEUD2

country

string · required

ISO 3166-1 alpha-3 country code.

Example: DEU

compatibility_zone

string · enum · required

Compatibility zone the operator belongs to.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

network_types

string[]

Network technologies supported by this operator.

Enum values:

LTE-M

NB-IOT

OperatorSortField

string · enum

Enum values:

name

tadig

country

compatibility_zone

Customer-visible sort fields for the operator list endpoint.

Subset of the internal OperatorSortField — only fields actually surfaced on OperatorResponse are sortable. Sorting by fields the response doesn't carry (created_at, is_barred, etc.) would be confusing for clients that can't see the resulting order.

OperatorSummary

Minimal operator info embedded in cost usage attributions. Just enough to display "which operator did this usage come from" without bloating the cost payload with full Operator objects (network types, bar status, country sub-fields, …). Fetch the full operator via the operators endpoint if needed.

id

string · uuid · required

Internal operator identifier.

name

string · required

Operator display name.

tadig

string · required

Standardised TADIG operator code.

country

string · required

ISO 3166-1 alpha-3 country code.

Example: DEU

compatibility_zone

string · enum · required

Compatibility zone the operator belongs to.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

OrganizationBalanceResponse

Latest balance snapshot for an organisation. Reads the most recently collected `BalanceSnapshot` from the ledger (populated periodically by the `collect_balances` worker, ~every 3h). `amount` is in whole EUR — BICS reports `maBalance` in centi-EUR and we normalise at the BICS boundary, so consumers see real currency units here.

organization_id

string · uuid · required

Internal identifier of the organisation this balance belongs to.

Example: 8a4b6df0-aaaa-bbbb-cccc-ddddeeeeffff

amount

string · pattern: ^(?!^[-+.]*$)[+-]?0*… · required

Current main-account balance in whole currency units (EUR for all current deployments). May carry sub-cent precision.

Example: 1099.9548

currency

string · required

ISO 4217 currency code reported by the provider.

Example: EUR

collected_at

string · date-time · required

UTC timestamp the snapshot was observed. Snapshots are append-only and skip-unchanged — gaps between timestamps indicate stretches where the balance didn't move.

Example: 2026-05-25 08:00:00+00:00

OrganizationCostResponse

Latest monthly cost snapshot for an organisation. Snapshots are append-only — the collector runs every 3h and may write multiple snapshots per `(year, month)` as the month progresses. This response is always the most recent one collected for the given `(year, month)`. Flat fees are org-wide totals; per-operator attribution lives in `usage_lines`.

organization_id

string · uuid · required

Identifier of the organisation this snapshot belongs to.

year

integer · required

Year the snapshot covers.

Example: 2026

month

integer · min: 1 · max: 12 · required

Month the snapshot covers (1-12).

Example: 5

collected_at

string · date-time · required

UTC timestamp the snapshot was observed at the provider.

ISO 4217 currency code for all amounts. Typically EUR.

Example: EUR

object[]

Per-service usage breakdown with operator attribution.

PagedResponse_ActivationResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_BulkTaskItemResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_BulkTaskResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_CoverageResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_LinkResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_OperatorResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_PlanResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_SIMResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PagedResponse_SentSMSResponse_

object[] · required

Items on the current page.

total

integer · required

Total number of items across all pages.

Example: 42

page

integer · required

Current page number (1-based).

Example: 1

page_size

integer · required

Items per page used to compute this response.

Example: 25

pages

integer · required

Total number of pages at the current page_size.

Example: 2

PlanCreateRequest

Request body for `POST /plans`. Coverage must already exist in the caller's catalogue; unknown `coverage_id` returns 404. Names are not constrained to be unique — pick any label that helps you identify the plan in your UI. `reactivation_trigger` presence is immutable post-create: a plan created without a trigger cannot have one added later, and vice versa. The trigger *type* (between two non-null values) can change via `PATCH` once that endpoint lands.

name

string · minLength: 1 · required

Display name for the plan. Not required to be unique.

coverage_id

string · uuid · required

Coverage this plan applies to.

included_data_mb

integer · min: 0 · required

Bundled data in MB.

validity_days

integer · min: 1 · required

Plan validity from activation, in days.

activation_type

string · enum · required

When the plan activates after being assigned to a link.

Enum values:

immediate

on_first_data_usage

base_throttle

string · enum · required

Max speed the plan can ever provide. Use unlimited for no throttle — null is not accepted (use the explicit unlimited value instead, so the field always has a meaningful answer).

Enum values:

unlimited

128kbps

256kbps

384kbps

512kbps

1250kbps

1mbps

2mbps

Free-text description.

In-plan soft cap — speed action applied at threshold.

object[]

Initial set of plan notifications. At most one per type.

What triggers plan renewal. Presence is immutable post-create.

Cap on automatic reactivations. -1 means unlimited.

PlanNotificationCreateRequest

Create-side shape for a plan notification. Reused inline in `PlanCreateRequest.notifications` and as the body of `POST /plans/{plan_id}/notifications`. Only one notification per `type` per plan is allowed — duplicates return 409. `threshold` is required for the data-consumption types and forbidden for the lifecycle types; the upstream system enforces the rule, so a violation surfaces as a 502 with `upstream_error` rather than 422.

type

string · enum · required

Notification trigger type.

Enum values:

plan_activation

data_consumption_absolute

data_consumption_relative

plan_expiration

message

string · minLength: 1 · maxLength: 85 · required

SMS body sent to the link (max 85 chars).

Threshold value — MB for data_consumption_absolute, percentage 1-100 for data_consumption_relative, null for activation/expiration.

PlanNotificationResponse

A plan notification as it appears on `PlanResponse.notifications`. `threshold` semantics depend on `type`: MB for `data_consumption_absolute`, percentage (1-100) for `data_consumption_relative`, null for the lifecycle types (`plan_activation`, `plan_expiration`).

id

integer · required

Notification identifier (assigned on create).

type

string · enum · required

Notification trigger type.

Enum values:

plan_activation

data_consumption_absolute

data_consumption_relative

plan_expiration

message

string · required

SMS body sent to the link.

Threshold value — MB for data_consumption_absolute, percentage for data_consumption_relative, null for activation/expiration.

PlanNotificationType

string · enum

Enum values:

plan_activation

data_consumption_absolute

data_consumption_relative

plan_expiration

Types of plan notifications sent via SMS to the link.

PlanNotificationUpdateRequest

Replace the `message` and `threshold` of an existing notification. `type` is fixed at creation and cannot be changed — to change the type, delete and re-add. `message` is required because the upstream system implements notification update as a remove + re-add operation atomically. `threshold` rules follow the type (see `PlanNotificationResponse.threshold`): - lifecycle types (`plan_activation`, `plan_expiration`): must be omitted or `null` - `data_consumption_absolute`: required, positive integer (MB) - `data_consumption_relative`: required, percentage in [50, 100] Type-mismatched thresholds are rejected as 422 `validation_error` by the service.

message

string · minLength: 1 · maxLength: 85 · required

New SMS body (max 85 chars).

New threshold (semantics depend on the notification's type).

PlanResponse

A plan as visible to the caller's organisation. Embeds a slim `CoverageSummary` so the caller can identify the plan's coverage without an extra request. Notifications are embedded read-only — managed via the `/plans/{plan_id}/notifications` sub-resource. Internal fields (`provider_id`, `synced_at`, lifecycle `status`) are hidden.

id

string · uuid · required

Internal plan identifier.

name

string · required

Customer-assigned plan name.

object · required

Coverage this plan applies to.

Example: {"compatibility_zones":["magenta"],"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","name":"EU + UK"}

included_data_mb

integer · required

Bundled data in MB.

validity_days

integer · required

Plan validity from activation, in days.

base_throttle

string · enum · required

Base throttle speed. unlimited means no throttle. Always present — historical rows with no throttle set surface as unlimited rather than null.

Enum values:

unlimited

128kbps

256kbps

384kbps

512kbps

1250kbps

1mbps

2mbps

activation_type

string · enum · required

When the plan activates after assignment.

Enum values:

immediate

on_first_data_usage

created_at

string · date-time · required

UTC timestamp when the plan was created.

updated_at

string · date-time · required

UTC timestamp of the last update.

Free-text description.

In-plan soft cap.

Renewal trigger, if any.

Max reactivations (-1 = unlimited).

object[]

SMS notifications configured for this plan.

compatibility_zones

string[]

Compatibility zones derived from the coverage.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

PlanSortField

string · enum

Enum values:

name

created_at

updated_at

validity_days

included_data_mb

base_throttle

Customer-visible sort fields for the plan list endpoint.

Subset of the domain sort fields. status is excluded (binary, hidden from responses). coverage_id is excluded (UUID, not user- meaningful for ordering — customers filter by coverage instead).

PlanUpdateRequest

Request body for `PATCH /plans/{plan_id}`. Patch-style — only fields **explicitly present** in the payload are forwarded. Omitting a field leaves it unchanged; sending `null` for a nullable field clears it. (The router distinguishes the two via `model_fields_set`; `null` is rejected for non-nullable fields by schema typing.) Constraints inherited from the service: - `reactivation_trigger` presence is immutable: cannot be added to a plan that lacks one, nor removed from one that has it. Changing between two non-null values is allowed. - `data_cap.threshold_mb` cannot exceed the plan's effective `included_data_mb` (current value if `included_data_mb` isn't being changed, new value if it is). Caught at the service as a 422 `validation_error`. - `base_throttle` does not accept `null` here either — use the explicit `unlimited` value (matches the create endpoint). `name` changes are local-only; the upstream system stores a synthesized id and is never told about renames.

New plan name.

New description; pass null to clear.

New coverage id.

New bundled data in MB.

New validity in days.

New base throttle. Use unlimited for no throttle. Omit the field to leave the current value unchanged — null here would canonicalize to unlimited on read, so use the explicit value instead to keep intent obvious.

New data cap; pass null to clear.

New activation type.

New reactivation trigger type. Presence cannot be toggled — to change between two non-null values, send the new value.

New max reactivations (-1 = unlimited); pass null to clear.

PolicyStatus

string · enum

Enum values:

default

blocked

throttle

Policy status for a connected link.

ReactivationTrigger

string · enum

Enum values:

on_expiration

on_expiration_or_exhaustion

What triggers plan renewal.

SIMBulkProvisionRequest

Request body for `POST /sims/bulk-provision`. Provisions a Link for each SIM in `sim_ids`. The Link is named `{name_prefix}_{counter}` where `counter` starts at `counter_start` (default 1) and advances per item — so a call with `name_prefix="DC1"`, three SIMs, and `counter_start=10` produces links named `DC1_10`, `DC1_11`, `DC1_12`. If `plan_ids` is supplied, those plans are activated on each new link at creation; otherwise the link stays pre-active. Duplicate ids in `sim_ids` are rejected at parse time (422) — silent deduplication would mask user input bugs that double-provision the same SIM with different names.

name_prefix

string · minLength: 1 · maxLength: 50 · required

Prefix for each provisioned link's name; the per-item suffix is _{counter}.

sim_ids

string[] · minItems: 1 · maxItems: 5000 · required

SIMs to provision. Must be non-empty; duplicates are rejected.

Plans to activate on every new link. Omit to leave each link pre-active.

counter_start

integer · min: 0

First value used for the _{counter} suffix; subsequent items get +1 each.

Default: 1

SIMInstallationResponse

eSIM installation view for a SIM. All fields are derived from the SIM's `activation_code`. Physical SIMs (no activation code) return all-null — that's a normal state, not an error.

Raw LPA activation string for the eSIM. Null for physical SIMs.

Android deeplink that opens the system eSIM installer prefilled with this code.

iOS deeplink that opens the system eSIM installer prefilled with this code.

Inline SVG markup of the LPA QR code, ready to embed in HTML.

SIMResponse

A SIM as visible to the caller's organisation. Hides internal correlation/sync fields (`provider_id`, `synced_at`) and the raw `activation_code` (the install view surfaces it properly). `is_attached` is the provider-reported attach state; `link` is the local DB view of the SIM's bound Link — these can diverge briefly (sync lag), which is why both are exposed.

id

string · uuid · required

Internal SIM identifier.

iccid

string · required

ICCID — the SIM's printed serial number.

status

string · enum · required

Lifecycle status of the SIM.

Enum values:

available

active

suspended

inventory

sim_type

string · enum · required

Physical SIM or eSIM.

Enum values:

physical

esim

is_attached

boolean · required

Whether the upstream system reports the SIM as currently attached. Distinct from link: this reflects upstream-reported attach state, while link reflects our local binding.

created_at

string · date-time · required

UTC timestamp when the SIM was first synced into our system.

updated_at

string · date-time · required

UTC timestamp of the last update from sync.

MSISDN (phone number) assigned to the SIM, if any.

IMSI on the SIM profile.

IMEI of the device the SIM was last seen in, if known.

eUICC identifier — only present for eSIMs.

compatibility_zones

string[]

Compatibility zones this SIM can operate in.

Enum values:

magenta

cyan

brown

amber

violet

coral

teal

slate

eSIM profile state. Null for physical SIMs.

The Link this SIM is bound to in our system. Null if not bound.

SIMSortField

string · enum

Enum values:

iccid

status

sim_type

created_at

updated_at

Customer-visible sort fields for the SIM list endpoint.

Subset of the domain sort fields — covers identifiers + lifecycle timestamps, both useful to customers. synced_at is hidden (internal sync timestamp).

SIMStatus

string · enum

Enum values:

available

active

suspended

inventory

Domain-level SIM status.

SIMType

string · enum

Enum values:

physical

esim

SIM form factor type.

SentSMSResponse

A single SMS send attempt on a link. One row per attempt — successes and failures both surface here. `failure_reason` is populated only when `status` is `failed`.

id

string · uuid · required

Internal identifier for this send attempt.

message

string · required

Message body that was submitted.

status

string · enum · required

Outcome of the send attempt.

Enum values:

sent

failed

sent_at

string · date-time · required

UTC timestamp when the attempt was made.

Reason for the failure when status is failed. Null when status is sent.

SentSMSSortField

string · enum

Enum values:

sent_at

status

Customer-visible sort fields for the SMS history endpoint.

Mirrors the domain enum 1:1; included here so the wire surface stays decoupled from the domain layer.

SentSMSStatus

string · enum

Enum values:

sent

failed

Outcome of an SMS send attempt.

SortOrder

string · enum

Enum values:

asc

desc

ThrottleSpeed

string · enum

Enum values:

unlimited

128kbps

256kbps

384kbps

512kbps

1250kbps

1mbps

2mbps

Baseline throttle speed — max speed the plan can ever provide.