Telkor API

This document describes the Telkor API: what it is, who it is for, and what it can do. It is intended for MVNOs, enterprise IoT teams, and M2M integrators as public documentation.

---

1. What is Telkor?

Telkor is a multi-tenant API platform for managing SIM inventory, coverage zones, data plans, and links (active service endpoints). Partners integrate via a REST API to:

• Define coverages — groups of mobile operators available for your plans
• Browse and monitor SIMs — physical SIMs and eSIMs in your organisation
• Create and configure plans — data packages with throttle, validity, and usage notifications
• Manage links — provision, activate, suspend, and configure service endpoints bound to SIMs
• Run bulk operations — async jobs for mass link/SIM management, tracked via tasks
• View organisation profile, balance, and monthly cost snapshots
• Retrieve eSIM installation details (LPA profile, QR code, deep links)

The platform handles authentication, upstream synchronisation, and exposes a unified, provider-agnostic API. All data is scoped to your organisation (tenant).

Base URL: https://api.omaxtelecom.com/telkor

---

2. Who is it for?

• MVNOs — Manage SIM inventory, coverage, and plan catalogues programmatically.
• Enterprise IoT — Monitor fleets of SIMs, refresh upstream data, and configure data plans.
• M2M integrators — Automate coverage and plan management with machine-to-machine tokens.

Each partner is an organisation (tenant). All coverages, SIMs, and plans are scoped to that organisation. Access is controlled via OmaxTelecom ID: OAuth 2.0 Client Credentials.

---

3. Core concepts

3.1 Coverages

A coverage is a named group of mobile operators that defines where a plan can be used. Coverages are the foundation for plan configuration.

Property	Description
id	UUID — internal coverage identifier
name	Display name (e.g. "EU + UK") — not required to be unique
operators	List of operators included in this coverage
compatibility_zones	Provider ecosystems spanned by the operators (e.g. magenta, cyan)

All operators in a coverage must belong to the same compatibility zone family. Mixed-provider coverages are rejected.

3.2 Operators

Operators are mobile network operators available in your catalogue. They are referenced when building coverages and filtered when listing plans.

Property	Description
id	UUID — operator identifier
name	Operator display name
country	ISO 3166-1 alpha-3 country code
tadig	TADIG code
compatibility_zone	Zone identifier (magenta, cyan, brown, amber, violet, coral, teal, slate, ivory)
network_types	Supported RAT types (2g, 3g, 4g, 5g)

Use GET /coverages/operators to browse operators available for coverage configuration.

3.3 SIMs

A SIM represents a physical SIM or eSIM in your organisation's inventory.

Property	Description
id	UUID — internal SIM identifier
iccid	ICCID — the SIM's printed serial number
msisdn	Phone number assigned to the SIM, if any
status	available, active, suspended, or inventory
sim_type	physical or esim
link	The Link this SIM is bound to (see below), if any
esim_profile_status	eSIM profile state (available, installed, disabled, deleted) — null for physical SIMs

3.4 Links

A Link is the central service endpoint — the binding between a SIM and an active data plan in the upstream system. Links support full lifecycle management: create, update, suspend, resume, delete, and bulk operations.

Property	Description
id	UUID — Link identifier
name	Customer-assigned name (optional)
status	active, suspended, hold, or removed
sim	Bound SIM (ICCID, status, type)
network_status	Live connectivity: operator, country, RAT (2g_3g, 4g, 5g), policy status
activations	Data plans currently attached to the link

Activations are plan instances on a link. Each activation tracks usage, expiry, and status. Add activations via POST /links/{link_id}/activations or bulk endpoints.

Link controls:

• Network bars — restrict connectivity to specific networks
• IMEI lock — bind the link to a specific device IMEI
• SMS — send SMS to the link's MSISDN

3.5 Plans

A plan is a data package configuration that references a coverage and defines usage rules.

Property	Description
name	Customer-assigned plan name
coverage	Coverage this plan applies to
included_data_mb	Bundled data in MB
validity_days	Plan validity from activation, in days
base_throttle	Max speed (unlimited, 128kbps … 20mbps)
data_cap	Optional in-plan soft cap with threshold and throttle action
activation_type	immediate or on_first_data_usage
reactivation_trigger	Renewal trigger (e.g. on_expiration)
notifications	Usage alert SMS notifications

3.6 Plan notifications

Notifications are SMS alerts sent to the Link when usage thresholds are reached or lifecycle events occur.

Type	Description
plan_activation	Sent when the plan activates
plan_expiration	Sent when the plan expires
data_consumption_absolute	Sent when data usage reaches a threshold in MB
data_consumption_relative	Sent when data usage reaches a percentage (50–100%)

Notifications are managed via the /plans/{plan_id}/notifications sub-resource.

3.7 Bulk tasks

Bulk operations (mass link provisioning, suspend, delete, etc.) run asynchronously. Each bulk request returns a task with status counters. Poll task progress via:

• GET /tasks — list all bulk tasks
• GET /tasks/{task_id} — task header (status, success/failure counts)
• GET /tasks/{task_id}/items — per-item results

3.8 Organization

Your organisation (tenant) is resolved from the JWT. Customer-facing org endpoints:

Endpoint	Description
GET /org	Organisation profile (id, name)
GET /org/balance	Latest main-account balance snapshot
GET /org/cost?year=&month=	Latest monthly cost snapshot with usage breakdown

Balance and cost data are collected by background workers (~every 3 hours). Returns 404 until the first snapshot exists.

---

4. Platform capabilities

4.1 Coverages

• List coverages — GET /coverages with pagination, sorting, and filters (operator_ids, countries, compatibility_zones, search).
• Create coverage — POST /coverages with name and operator_ids.
• List operators — GET /coverages/operators to browse operators for coverage configuration.
• Get coverage — GET /coverages/{coverage_id}.
• Rename coverage — PATCH /coverages/{coverage_id} with a new name.
• Delete coverage — DELETE /coverages/{coverage_id} (soft-delete, returns 204).
• Add operators — POST /coverages/{coverage_id}/operators (idempotent).
• Remove operators — POST /coverages/{coverage_id}/operators/remove (idempotent).

4.2 SIMs

• List SIMs — GET /sims with pagination, sorting, and filters (status, sim_type, compatibility_zones, search, is_attached, etc.).
• Bulk provision — POST /sims/bulk-provision creates links for multiple SIMs asynchronously (returns a task).
• Get SIM — GET /sims/{sim_id} returns full SIM details including Link summary.
• eSIM installation — GET /sims/{sim_id}/installation returns LPA activation code, Apple/Android deep links, and QR SVG.
• Refresh SIM — POST /sims/{sim_id}/refresh pulls the latest data from the upstream system.

4.3 Plans

• List plans — GET /plans with extensive filters (coverage, operators, compatibility zones, data/validity ranges, throttle, search, for_link_id).
• Create plan — POST /plans with coverage, data allowance, validity, throttle, and optional caps/notifications.
• Get plan — GET /plans/{plan_id}.
• Update plan — PATCH /plans/{plan_id} (partial update).
• Delete plan — DELETE /plans/{plan_id} (soft-delete, returns 204).
• Add notification — POST /plans/{plan_id}/notifications.
• Update notification — PATCH /plans/{plan_id}/notifications/{notification_id}.
• Remove notification — DELETE /plans/{plan_id}/notifications/{notification_id} (returns 204).

4.4 Links

• List links — GET /links with filters (status, compatibility_zones, countries, search).
• Create link — POST /links provisions a new link (optionally bound to a SIM and plan).
• Get link — GET /links/{link_id} (refreshes live network status for active links).
• Update link — PATCH /links/{link_id} (rename, etc.).
• Delete link — DELETE /links/{link_id} (soft-delete, returns 204).
• Bind SIM — POST /links/{link_id}/sim / POST /links/{link_id}/sim/remove.
• Network bars — POST /links/{link_id}/network-bars / POST .../network-bars/remove.
• IMEI lock — POST /links/{link_id}/imei-lock / POST .../imei-lock/remove.
• SMS — GET /links/{link_id}/sms (list), POST /links/{link_id}/sms (send).
• Suspend / resume — POST /links/{link_id}/suspend, POST /links/{link_id}/resume.
• Activations — GET /links/{link_id}/activations, POST /links/{link_id}/activations, DELETE /links/{link_id}/activations/{activation_id}.

Bulk link operations (all return a task id):

Endpoint	Action
POST /links/bulk-delink-sim	Detach SIM from multiple links
POST /links/bulk-delete	Soft-delete multiple links
POST /links/bulk-suspend	Suspend multiple links
POST /links/bulk-resume	Resume multiple links
POST /links/bulk-add-activation	Add plan activation to multiple links
POST /links/bulk-delete-activation	Remove activation from multiple links

4.5 Tasks

• List tasks — GET /tasks with filters (type, status).
• Get task — GET /tasks/{task_id} (status + counters).
• List task items — GET /tasks/{task_id}/items (per-item success/failure details).

4.6 Organization

• Profile — GET /org returns your organisation id and name.
• Balance — GET /org/balance returns the latest collected balance snapshot.
• Cost — GET /org/cost?year=2026&month=6 returns the latest monthly cost breakdown.

---

5. Technical specifications

5.1 API

• Style: REST, JSON request/response.
• Base URL: https://api.omaxtelecom.com/telkor
• Authentication: OAuth 2.0 Client Credentials via OmaxTelecom ID. Send Authorization: Bearer <access_token>.

5.2 Authentication

Obtain a token from the OmaxTelecom ID token endpoint:

Code
 
POST https://id.omaxtelecom.com/realms/platform/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Get your client_id and client_secret from OmaxTelecom Console. The token has a limited lifetime — request a new one when it expires. There are no refresh tokens in the Client Credentials flow.

5.3 Pagination

List endpoints (/coverages, /coverages/operators, /sims, /plans, /links, /tasks) return paginated results:

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

Query parameters: page (1-based, default 1), page_size (default 25, max 500).

5.4 Filtering and sorting

• Filters combine with AND semantics.
• Repeatable filters (operator_ids, countries, compatibility_zones) match any of the provided values.
• search performs a case-insensitive substring match.
• Use sort_by and sort_order (asc / desc) on list endpoints.

5.5 Error format

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

5.6 Error codes

Code	HTTP	Meaning
unauthorized	401	Missing or invalid Bearer token
forbidden	403	Authenticated but lacks required role
entity_not_found	404	Resource not found
entity_deleted	410	Resource has been soft-deleted
duplicate_entity	409	Entity already exists
validation_error	422	Business rule violation
request_validation_error	422	Request input failed schema validation
upstream_unavailable	502	Upstream dependency error

5.7 Multi-tenancy

Every authenticated request is bound to an organisation derived from the token. All coverages, SIMs, plans, links, and tasks are scoped to that organisation. No cross-tenant access.

---

6. Getting started

1. Obtain credentials — Get client_id and client_secret from OmaxTelecom Console.
2. Get a token — Call the OmaxTelecom ID token endpoint with Client Credentials grant. Use the returned access_token as Authorization: Bearer <access_token>.
3. Confirm tenant — GET /org to verify which organisation your token is bound to.
4. Browse operators — GET /coverages/operators to see available operators.
5. Create a coverage — POST /coverages with a name and operator IDs.
6. Create a plan — POST /plans referencing your coverage, with data allowance and validity.
7. List SIMs — GET /sims to view your SIM inventory.
8. Create a link — POST /links to provision a service endpoint, or POST /sims/bulk-provision for multiple SIMs.
9. Monitor bulk jobs — GET /tasks/{task_id} to track async bulk operation progress.
10. Optional: Configure plan notifications, check balance (GET /org/balance), and refresh SIM data.

---

7. Summary table

Area	Capability
Coverages	Define operator groups for plan coverage
Operators	Browse mobile operators in your catalogue
SIMs	List, view, bulk-provision, refresh SIM inventory
eSIM install	LPA profile, QR code, Apple/Android deep links
Plans	Create and manage data plans with throttle and caps
Notifications	SMS usage alerts on plans
Links	Full lifecycle: create, activate, suspend, SMS, network bars, IMEI lock
Bulk ops	Mass link/SIM operations via async tasks
Tasks	Track bulk job progress and per-item results
Organization	Profile, balance snapshot, monthly cost breakdown
Auth	OmaxTelecom ID (Client Credentials), Bearer token

---

API Documentation

Need Help?

If you have any questions or need assistance with the Telkor API, please contact our support team at [email protected].