Telkor API

The Telkor API manages your SIM inventory, coverages, data plans and links — the active service on a SIM — including bulk jobs for thousands of SIMs at once. It is built for MVNOs, enterprise IoT teams and M2M integrators.


Base URL	`https://api.omaxtelecom.com/telkor`
Authentication	Bearer access token — how to get one
Postman	Collection · Environment
AI assistants	Open in ChatGPT · Open in Claude · Markdown · MCP server

[!TIP] Try it here: enter your Client ID and Client Secret in the Authentication box, click Authorize, then use Test Request on any endpoint.

Who it is for:

MVNOs — manage SIM inventory, coverage and plan catalogues from your own systems.
Enterprise IoT — monitor fleets of SIMs, refresh their data and configure data plans.
M2M integrators — automate coverage and plan management.

What you can do

Task	Endpoint	Description
Coverages	`/coverages`	Group operators into the areas your plans cover
Operators	`GET /coverages/operators`	Operators you can put in a coverage
SIMs	`/sims`	Your SIM inventory, eSIM install details, refresh
Plans	`/plans`	Data plans with throttle, caps and usage alerts
Links	`/links`	Create, suspend, resume and configure the service on a SIM
Bulk jobs	`/links/bulk-*`, `/sims/bulk-provision`	Run one action on many links or SIMs
Tasks	`/tasks`	Progress and results of bulk jobs
Organization	`/org`	Profile, balance and monthly cost

Quick start

Get credentials and a token — see Getting started.
Check your organization: GET /org shows which organization your token belongs to.
Pick operators: GET /coverages/operators.
Create a coverage: POST /coverages with a name and operator_ids.
Create a plan: POST /plans with the coverage, data allowance and validity.
Find your SIMs: GET /sims.
Activate service: POST /links for one SIM, or POST /sims/bulk-provision for many.
Follow bulk jobs: GET /tasks/{task_id}.

Authentication

Send an access token on every request:

Authorization: Bearer <access_token>

Get the token from POST https://api.omaxtelecom.com/auth/token with your Console client_id and client_secret. Getting started shows how, with code samples. When the token expires, request a new one — this flow has no refresh tokens.

Your organization (tenant) comes from the token. All coverages, SIMs, plans, links and tasks belong to your organization only.

Key concepts

Coverages and operators

A coverage is a named group of mobile operators: it defines where a plan works.

Property	Description
`id`	Coverage UUID
`name`	Display name, for example "EU + UK". Does not have to be unique
`operators`	The operators in this coverage
`compatibility_zones`	The provider ecosystems of these operators, for example `magenta` or `cyan`

All operators in one coverage must belong to the same compatibility zone family; mixed coverages are rejected.

Operators are the mobile networks in your catalog:

Property	Description
`id`	Operator UUID
`name`	Operator name
`country`	ISO 3166-1 alpha-3 country code
`tadig`	TADIG code
`compatibility_zone`	`magenta`, `cyan`, `brown`, `amber`, `violet`, `coral`, `teal`, `slate` or `ivory`
`network_types`	Supported networks: `2g`, `3g`, `4g`, `5g`

SIMs

A SIM is a physical SIM or eSIM in your inventory.

Property	Description
`id`	SIM UUID
`iccid`	The SIM's printed serial number
`msisdn`	The phone number of the SIM, if any
`status`	`available`, `active`, `suspended` or `inventory`
`sim_type`	`physical` or `esim`
`link`	The link this SIM belongs to, if any
`esim_profile_status`	`available`, `installed`, `disabled` or `deleted`; `null` for physical SIMs

Links and activations

A link is the service on a SIM: it binds a SIM to data plans in the network.

Property	Description
`id`	Link UUID
`name`	Your own name for the link (optional)
`status`	`active`, `suspended`, `hold` or `removed`
`sim`	The SIM on this link (ICCID, status, type)
`network_status`	Live connection: operator, country, network (`2g_3g`, `4g`, `5g`), policy status
`activations`	The plans currently on the link

An activation is one plan on a link, with its own usage, expiry and status. Add one with POST /links/{link_id}/activations or in bulk.

A link can also have:

Network bars — limit which networks it may use,
an IMEI lock — tie it to one device,
SMS — messages sent to the link's number.

Plans and notifications

A plan is a data package for one coverage.

Property	Description
`name`	Your plan name
`coverage`	The coverage the plan works in
`included_data_mb`	Included data, in MB
`validity_days`	Days the plan is valid after activation
`base_throttle`	Maximum speed: `unlimited`, `128kbps` … `20mbps`
`data_cap`	Optional soft cap: a threshold and the throttle to apply after it
`activation_type`	`immediate` or `on_first_data_usage`
`reactivation_trigger`	When the plan renews, for example `on_expiration`
`notifications`	SMS alerts about usage

Notifications are SMS sent to the link when a plan event happens. Manage them under /plans/{plan_id}/notifications.

Type	Sent when
`plan_activation`	The plan is activated
`plan_expiration`	The plan expires
`data_consumption_absolute`	Usage reaches a number of MB
`data_consumption_relative`	Usage reaches a percentage (50–100%)

Bulk jobs and tasks

Bulk actions run in the background and return a task. Follow it with:

GET /tasks — all tasks, filtered by type or status,
GET /tasks/{task_id} — status and success/failure counts,
GET /tasks/{task_id}/items — the result for every item.

Endpoints by area

Coverages

GET /coverages — list, with sorting and filters (operator_ids, countries, compatibility_zones, search).
POST /coverages — create, with name and operator_ids.
GET /coverages/{coverage_id} — details.
PATCH /coverages/{coverage_id} — rename.
DELETE /coverages/{coverage_id} — delete (soft delete, 204).
POST /coverages/{coverage_id}/operators — add operators (safe to repeat).
POST /coverages/{coverage_id}/operators/remove — remove operators (safe to repeat).

SIMs

GET /sims — list, with sorting and filters (status, sim_type, compatibility_zones, search, is_attached, …).
GET /sims/{sim_id} — details, including the link.
GET /sims/{sim_id}/installation — eSIM install details: LPA code, Apple and Android links, QR code (SVG).
POST /sims/{sim_id}/refresh — fetch the latest data from the network.
POST /sims/bulk-provision — create links for many SIMs (returns a task).

Plans

GET /plans — list, with filters (coverage, operators, compatibility zones, data and validity ranges, throttle, search, for_link_id).
POST /plans — create, with coverage, data, validity, throttle and optional caps and notifications.
GET /plans/{plan_id} — details.
PATCH /plans/{plan_id} — change some fields.
DELETE /plans/{plan_id} — delete (soft delete, 204).
POST /plans/{plan_id}/notifications, PATCH / DELETE /plans/{plan_id}/notifications/{notification_id} — manage alerts.

Links

GET /links — list, filtered by status, compatibility_zones, countries, search.
POST /links — create, optionally with a SIM and a plan.
GET /links/{link_id} — details; refreshes the live network status of active links.
PATCH /links/{link_id} — rename and other changes.
DELETE /links/{link_id} — delete (soft delete, 204).
POST /links/{link_id}/sim, POST /links/{link_id}/sim/remove — attach or detach the SIM.
POST /links/{link_id}/network-bars, .../network-bars/remove — network bars.
POST /links/{link_id}/imei-lock, .../imei-lock/remove — IMEI lock.
GET / POST /links/{link_id}/sms — list or send SMS.
POST /links/{link_id}/suspend, POST /links/{link_id}/resume — suspend or resume.
GET / POST /links/{link_id}/activations, DELETE /links/{link_id}/activations/{activation_id} — manage plans on the link.

Bulk link actions — each returns a task:

Endpoint	Action
`POST /links/bulk-delink-sim`	Detach the SIM from many links
`POST /links/bulk-delete`	Delete many links
`POST /links/bulk-suspend`	Suspend many links
`POST /links/bulk-resume`	Resume many links
`POST /links/bulk-add-activation`	Add a plan to many links
`POST /links/bulk-delete-activation`	Remove a plan from many links

Organization

Endpoint	Description
`GET /org`	Organization profile (id, name)
`GET /org/balance`	Latest balance of the main account
`GET /org/cost?year=2026&month=6`	Latest monthly cost, with a usage breakdown

Balance and cost are collected about every 3 hours. Until the first snapshot exists, these endpoints answer 404.

Lists, filters and sorting

List endpoints (/coverages, /coverages/operators, /sims, /plans, /links, /tasks) are paged:

{
  "items": [...],
  "total": 42,
  "page": 1,
  "page_size": 25,
  "total_pages": 2
}

page starts at 1; page_size defaults to 25, maximum 500.
Different filters combine with AND.
Repeatable filters (operator_ids, countries, compatibility_zones) match any of the values you send.
search is a case-insensitive "contains" match.
Sort with sort_by and sort_order (asc or desc).

Errors

Errors have this shape:

{
  "message": "Entity not found: id=...",
  "code": "entity_not_found",
  "details": { ... }
}

Error code	HTTP status	What it means
`unauthorized`	401	The token is missing or invalid — get a new one
`forbidden`	403	You are signed in but not allowed to do this
`entity_not_found`	404	The resource does not exist
`duplicate_entity`	409	It already exists
`entity_deleted`	410	The resource was deleted
`validation_error`	422	A business rule was broken
`request_validation_error`	422	The request does not match the schema
`upstream_unavailable`	502	A service behind the API is unavailable — retry later

Need help?

Email support@omaxtelecom.com. Tell us which endpoint you called, when, and what the response was — including its request_id if it has one. Never send your Client Secret or access token.