Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.telegent.com/llms.txt

Use this file to discover all available pages before exploring further.

Each section follows the same shape: what the resource is, why it exists, the happy-path call, the parameters that matter, and the gotchas to plan around. For full schemas and additional optional fields, check docs.telegent.com.

​
1. Authentication

Every Telegent API call needs a Bearer token. You get one by posting your AccountKey and AccountSecret to the OAuth2 token endpoint. Tokens are short-lived and scoped to a specific ApiEndpoint URL, so generate a fresh one for each endpoint you call (or refresh on expiry). Endpoint: POST /v1.0/oauth2/tokens 
{
  "AccountKey": "YOUR_ACCOUNT_KEY",
  "AccountSecret": "YOUR_ACCOUNT_SECRET",
  "ApiEndpoint": "https://api.telegent.com/v1.0/numbers/provision"
}
Once you have a token, add this header to every subsequent request: 
Authorization: Bearer YOUR_TOKEN
Cache the token in memory for the life of its expiry. Don’t request a new token for every call — that’s wasteful. Do regenerate when ApiEndpoint changes, since scope is per-URL.

​
2. Account

​
Where an Account sits in the hierarchy

Telegent’s org chart has four tiers. At the top is the Aggregator — the platform owner. Beneath it sit one or more Distributors (carriers, MVNEs, resellers). Each Distributor owns one or more Accounts, and each Account is the unit you’ll actually work with day to day.

​
What an Account is

Think of an Account as a family or a business. It holds one Manager — the steward who can administer the Account — and any number of Subscribers, who are the people actually using the service. A Subscriber, in turn, can hold one or many phone Numbers. Every Number that goes live on the platform is bound to exactly one Account and exactly one Subscriber. There is no orphan number on Telegent. Endpoint: POST /v1.0/account/create 
{
  "AccountName": "Acme MVNO",
  "AccountAdmin": "ops@acmemobile.com",
  "BillingAddress": {
    "Street1": "100 Main St",
    "Street2": "Suite 200",
    "City": "Lehi",
    "State": "Utah",
    "Zip": "84043",
    "Country": "USA"
  },
  "MailingAddress": {
    "Street1": null,
    "City": null,
    "State": null,
    "Zip": null
  }
}

​
Parameters worth knowing

FieldTypeDescription
AccountNamestringDisplay name — the name of the family or business. Visible on invoices and reports.
AccountAdminstringEmail of the Manager. They receive billing and system notices for the whole Account.
BillingAddressobjectRequired for invoicing. Set Country = USA unless you’re an international Distributor.
MailingAddressobjectOptional. Leave fields null if same as Billing.
Save the AccountId (AID). Every Subscriber you create and every Number you provision needs an AID. For Distributors managing more than one Account, AID becomes required on most downstream calls. Persist it the moment you create the Account.
The one rule to remember: Every Number must have both an Account (AID) and a Subscriber (TSUID) assigned to it. Never provision or port a number without deciding who it belongs to first.

​
3. Subscribers and Roles

A Subscriber is a real person (or service identity) that lives under an Account. A Subscriber can hold one phone Number or many — a parent on a family plan might have a single line; a business operations lead might own a dozen IoT lines. Either way, every Number a Subscriber owns is bound to the same Account.

​
The three roles

Each Subscriber record carries a Role. The Role determines what that person can do inside the Account.
RoleDescription
SubscriberEnd user. Holds one or more Numbers, a Subscription, and (optionally) Guardian filters. Cannot administer the Account.
ManagerThe steward of the Account — typically one per Account. Manages Subscribers, Subscriptions, Guardian filters, and data limits within their Account.
Account AdminAdministrative role at the Account level. Can configure routes, manage Packages, update billing info. Use sparingly; Distributors usually hold this.
Manager = One per Account. Telegent’s product convention is one Manager per Account — the head of the family or the operations lead at the business. You can technically create multiple Subscribers with the Manager role, but the cleanest model (and the one MVNO billing assumes) is a single Manager who owns the Account-level decisions.
Endpoint: POST /v1.0/subscribers/create 
{
  "Name": "Jane Doe",
  "Email": "jane@example.com",
  "PhoneNumbers": ["+18015551234"],
  "Role": "Subscriber",
  "Password": "set-a-secure-default",
  "AccountId": "AID-…"
}

​
Parameters worth knowing

FieldTypeDescription
NamestringRequired. Free-text display name.
EmailstringRequired. Must be unique across the entire platform.
PhoneNumbersstring[]Required. E.164 format. Can be empty array on create, then assigned later.
RoleenumSubscriber | Manager | Account Admin
PasswordstringRequired at create. Issue a temp value and force a reset on first login.
AccountIdstringRequired. The AID this subscriber belongs to.
Save the SubscriberId (TSUID). TSUID is the join key for everything subscriber-specific: number assignment, subscriptions, AI Guardian filters, data usage settings. Without it, you can’t tie a phone number to a person.

​
4. Routes — Message and Voice

Routes tell Telegent where to send inbound traffic and where to receive your callbacks. A Message Route is required before you can provision any number. A Voice Route is required only if the number will handle calls.

​
4.1 Message Route (MRID)

Endpoint: POST /v1.0/message/routes
Request
{
  "RouteName": "Main SMS Webhook",
  "MessageUrl": "https://yourapi.example.com/inbound-sms",
  "MessageUrlMethod": "POST",
  "MessageRouteEnabled": true,
  "MessageAuthenticationType": "Basic",
  "MessageUsername": "admin",
  "MessagePasswordToken": "passwordOrBearer",
  "CallbackMessageUrl": "https://yourapi.example.com/sms-status",
  "CallbackMessageUrlMethod": "POST",
  "CallbackMessageAuthenticationType": "Basic",
  "CallbackMessageUsername": "admin",
  "CallbackMessagePasswordToken": "password",
  "InboundBypass": false,
  "OutboundBypass": false,
  "IntelligentRouteEnabled": true,
  "AccountId": "AID-…"
}
Save the MessageRouteId (MRID) — you will need it on every number provision call.

​
4.2 Voice Route (CRID)

Endpoint: POST /v1.0/voice/routes Voice Routes support three RouteType values: "Trunk" (SIP trunk to your softswitch / PBX), "URL" (webhook for VoIP-style apps), or "Forward" (PSTN forward). Most MVNO setups use Trunk.
Request
{
  "RouteName": "Main SIP Trunk",
  "RouteType": "Trunk",
  "TrunkIp1": "20.87.87.87",
  "TrunkPort1": "5061",
  "TrunkTransport1": "UDP",
  "TrunkUri1": "https://pstn.yourcarrier.com",
  "TrunkEnabled1": true,
  "Trunk1Priortiy": 10,
  "Trunk1Weight": 10,
  "CallbackVoiceUrl": "https://yourapi.example.com/voice-events",
  "CallbackVoiceUrlMethod": "POST",
  "IntelligentRouteEnabled": true,
  "RouteEnabled": true,
  "AccountId": "AID-…"
}
Save the CallRouteId (CRID) for voice-enabled provisioning.

​
Parameters worth knowing

FieldTypeDescription
MessageUrlstringWhere inbound SMS/MMS payloads are delivered.
CallbackMessageUrlstringWhere delivery receipts and status callbacks are delivered.
TrunkIp1 / Uri1stringPrimary SIP endpoint. Configure two trunks (1 + 2) for failover.
IntelligentRouteEnabledboolTurn this on to enable AI Guardian + intelligent routing on the route.
AccountIdstringConditional: required when a Distributor manages multiple Accounts.
Authentication on your webhook. Telegent supports Basic and Bearer on both the inbound URL and the callback URL. Use HTTPS endpoints. If you are running behind a CDN or load balancer, whitelist Telegent IPs separately — IpWhitelist on the Voice Route only applies to trunk traffic.

​
5. ICCID — When to Use It

ICCID is the unique serial of a SIM card or eSIM profile. Telegent treats ICCID as optional on both provision and port-in calls. Whether you should send one depends on the lifecycle moment.
Two places ICCID shows up: ICCID is accepted on both /numbers/provision (when you want to pair on create) and /numbers/portin (when you are porting a number onto an existing SIM). On a Subscription, ICCID also identifies the SIM tied to that billing relationship.

Use ICCID when…

  • Activating a physical SIM that the subscriber already has in hand — pair the ICCID at provision so the line is live the moment you respond to the API
  • Issuing an eSIM and have the profile ICCID generated — pair it at provision so the QR / activation code maps to a real number on first scan
  • Migrating a subscriber from another platform and need to preserve their SIM

Skip ICCID when…

  • Reserving numbers in bulk before SIMs are mailed — provision without ICCID, then bind ICCID later via Numbers Update
  • Provisioning data-only numbers that will be assigned by ProductType (no SIM in the loop)
  • Running test / sandbox flows

​
6. Products and Packages

Products are the smallest billable unit in Telegent (an eSIM, a GB of data, an SMS bucket, a feature add-on). Packages bundle Products into something you actually sell to a subscriber. Then a Subscription ties one Package to one Subscriber.

​
6.1 Products

Endpoint: POST /v1.0/products
Request
{
  "SKU": "eSim",
  "Description": "Telegent eSim",
  "Type": "esim",
  "SubType": "esim",
  "Cost": 12.34,
  "BillingFrequency": "MRC"
}
FieldTypeDescription
SKUstringYour internal stock-keeping code. Keep it stable; reports key off this.
Type / SubTypestringProduct family (esim, data, sms, feature, etc.). See docs.telegent.com for the current enum.
CostnumberWholesale cost to you. Pricing to the subscriber lives on the Package.
BillingFrequencystringMRC (monthly), NRC (one-time), or usage-based. Drives invoicing cadence.
Telegent can pre-load common Products. If you don’t want to define eSIM, base SMS, and data-tier Products from scratch, ask your Telegent rep to pre-load the standard catalog onto your Account. You can then bundle them into Packages without ever calling /products yourself.

​
6.2 Packages

Endpoint: POST /v1.0/packages A Package has a name, a price the subscriber pays, and one or more Package Items — each Item references a ProductId.
Request
{
  "PackageName": "Family 10GB",
  "Description": "10GB data + unlimited SMS",
  "Type": "sip",
  "Price": 39.99,
  "Monthly": true,
  "PackageItems": [
    { "ProductId": "PID-…esim",      "Price": "0.00",  "Monthly": false, "Type": "esim" },
    { "ProductId": "PID-…data-10gb", "Price": "30.00", "Monthly": true,  "Type": "data" },
    { "ProductId": "PID-…sms-unl",   "Price": "9.99",  "Monthly": true,  "Type": "sms"  }
  ]
}

​
Adding items after the fact

If you need to add an item to an existing Package without rebuilding it:
POST /v1.0/packages/items/add
{
  "PackageId": "PKID-…",
  "ProductId": "PID-…",
  "Price": "1.12",
  "Monthly": false,
  "Type": "addon"
}
Start with a small starter set. Build three Packages: an entry tier, a mid tier, and a premium. Build them once, then create variants by cloning. Avoid creating a unique Package per subscriber — Subscriptions are how you customize per-subscriber pricing.

​
7. Subscriptions

A Subscription is the billing relationship: one Subscriber, one Package, one number (TN), and — optionally — one ICCID. This is what kicks off recurring charges. Endpoint: POST /v1.0/subscriptions
Request
{
  "SubscriberId": "TSUID-…",
  "TNID":  "NID-…",
  "ICCID": "8901240397190002080",
  "PackageId": "PKID-…",
  "Type": "Voip"
}

​
Parameters worth knowing

FieldTypeDescription
SubscriberIdstringTSUID from Section 3.
TNIDstringThe number identifier issued by /numbers/provision or /numbers/portin.
ICCIDstringOptional. Bind the SIM to this Subscription.
PackageIdstringPKID from Section 6.2.
TypestringVoip, Mvno, Iot — must match the kind of number the Subscription is on.
One Subscription per number, not per subscriber. A Subscriber with two lines has two Subscriptions. Keep them separate — it makes cancellation, plan changes, and refunds clean.

​
8. Provisioning or Porting

Every number must have an Account and a Subscriber. Before you call /numbers/provision or /numbers/portin, decide which Account (AccountId) and which Subscriber (AssignedSubscriberId) the new Number will belong to. The API will let you provision without a Subscriber, but you’ll have to bind one later via Numbers Update — and you’ll have an orphan in your inventory in the meantime.

​
8.1 Provision a brand-new number

Step 1 — Check availability:
POST /v1.0/numbers/availability
{
  "NumberType": "mobile",
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": true,
  "PageNumber": 1,
  "AreaCode": "201",
  "ZipCode": ""
}
Step 2 — Provision:
POST /v1.0/numbers/provision
{
  "NumberType": "mvno",        // "mvno", "iot", or "voip"
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": true,
  "DataEnabled": true,
  "MessageRouteId": "MRID-…",
  "VoiceRouteId": "CRID-…",
  "AreaCode": "201",
  "ICCID": "8901240397190195850",          // optional
  "ProductType": "sms+data+voice",         // sms-only | data-only | sms+data | sms+data+voice
  "AssignedSubscriberId": "TSUID-…",
  "AccountId": "AID-…"
}
NumberType rules to remember: iot numbers are p2p only — never a2p. voip numbers are a2p only. For a2p messaging on a mobile-style line, use NumberType = "mvno".

​
8.2 Port a number in — the full lifecycle

Port-ins are not one-shot. A request can be open for days while the losing carrier responds, and during that window you may need to correct details, push out the activation date, or pull the request entirely. Plan for all five steps below — eligibility, submit, update, cancel, and monitor — as a single workflow. Step 1 — Check eligibility before you collect anything from the subscriber:
POST /v1.0/numbers/portin/eligibility
{
  "PhoneNumber": "+13136398786",
  "TargetClassification": "mvno"   // "mvno" or "iot"
}
If eligibility comes back positive, get the subscriber’s signed LOA and current carrier account details, then submit. If it’s negative, stop here — you can’t port that number into your classification. Step 2 — Submit the port-in:
POST /v1.0/numbers/portin
{
  "PortInNumber": "+15555551234",
  "ICCID": "8901240397190195850",          // optional
  "CurrentCarrierName": "Verizon",
  "CurrentAccountNumber": "46512222",
  "CurrentAccountPassword": "0000",
  "TargetPortinClassification": "mvno",    // "mvno" or "iot"
  "SubscriberName": "Jane Doe",
  "CurrentBillingAddress": {
    "Street1": "2701 N Thanksgiving Way",
    "Street2": "Suite 202",
    "City": "Lehi",
    "State": "UT",
    "Zip": "84043"
  }
}
The response includes an OrderId (JNUOID-…). Save it — every later call in the lifecycle (update, cancel, status) keys off this OrderId. Step 3 — Update an open port-in if details change: If the losing carrier rejects the request because of a name mismatch, wrong account number, or a missing port-in date, fix the record without cancelling and resubmitting. PortInDate is required for wirelines (5–10 business day windows) and conditional otherwise.
POST /v1.0/numbers/portin/update
{
  "OrderId": "JNUOID-6c058364-66a7-485b-93e1-7a2aa75e4fed",
  "CurrentCarrierName": "Sinch",
  "SubscriberName": "Jane Doe",
  "CurrentAccountNumber": "7617",
  "CurrentAccountPassword": "0813",
  "PortInDate": "04/23/2026",        // conditional — required for wirelines
  "CurrentBillingAddress": {
    "Street1": "2701 N Thanksgiving Way",
    "Street2": "",
    "City": "Lehi",
    "State": "UT",
    "Zip": "84043"
  }
}
Step 4 — Cancel a port-in that should not proceed: Subscriber changed their mind. The losing carrier disputed past the resolution window. The eligibility was right but the LOA never came back signed. Whatever the reason, you cancel by OrderId — never by phone number.
POST /v1.0/numbers/portin/cancel
{
  "OrderId": "JNUOID-6e3eb213-baf1-47bb-9db0-5d7d09d4b7b4"
}
Cancel is final. If the subscriber later wants to port the same number again, run eligibility and submit a fresh request — you can’t un-cancel.
Step 5 — Monitor the order: Between submit and activation, poll the order to see where it stands (Submitted, Pending Carrier Approval, Scheduled, Completed, Rejected, Cancelled). 
GET /v1.0/numbers/order?OrderId=JNUOID-19b3d376-2440-477f-a3dc-c91a36989316
Port-in best practice: Always run eligibility first — it tells you whether the number is portable to your classification before you spend the port fee or commit the subscriber to a date. Submit only after the LOA is signed and the current-carrier account details are verified. Poll the order daily until you see Completed, and notify the subscriber the moment status flips.

​
8.3 Port a number out

When a subscriber leaves your MVNO for another carrier, the gaining carrier initiates the port-out on their side, but they’ll need a PIN from you (and the subscriber will need to authorize the release). Issue the PIN through:
POST /v1.0/numbers/portout
{
  "PortOutNumber": "+17746996223",
  "PortOutPIN": "1234"
}
Port-out is a courtesy, not an obstacle. FCC rules require carriers to release numbers on subscriber request. Issue the PIN promptly. Don’t suspend service before the port-out completes — that breaks the gaining carrier’s validation and creates a support escalation.

​
9. Data Usage Limits and Thresholds

Telegent gives you three knobs per number: a Notify threshold (lets the subscriber know they’re getting close), a Throttle threshold (slows them down past a point), and a Limit (hard cap). Set all three in one call. Endpoint: POST /v1.0/numbers/data-usage
Request
{
  "ValueUnit": "MB",
  "NotifyValue": 8,
  "ThrottleValue": 10,
  "ThrottleSpeed": "1-mbps",
  "LimitValue": 15,
  "PhoneNumbers": [
    { "Number": "+12016093801" },
    { "Number": "+12232233180" }
  ]
}

​
Parameters worth knowing

FieldTypeDescription
ValueUnitenumMB. Applies to all three thresholds.
NotifyValuenumberSubscriber is notified when usage hits this value.
ThrottleValuenumberSpeed is throttled to ThrottleSpeed once usage hits this value.
ThrottleSpeedenum64-kbps | 128-kbps | 256-kbps | 512-kbps | 1-mbps | 5-mbps | 20-mbps | 50-mbps | 100-mbps
LimitValuenumberHard cap. Data is cut off (or charged overage, depending on plan) past this.
PhoneNumbersarrayOne or many numbers. The same thresholds apply to every number in the array.
Use POST /v1.0/numbers/data-usage/settings to read the configured thresholds for a number, and POST /v1.0/numbers/data-usage/info to read the current usage against those thresholds.

​
10. AI Guardian — Allow / Block + Filter Levels

AI Guardian is per-subscriber. Two surfaces: voice (Call Filter) and SMS (Message Filter). For both, MVNOs should ship the allow-list and block-list controls. SMS additionally supports age-based Filter Levels (CHILD, ADOLESCENT, TEENAGER). Voice Filter Levels are a future release for SIP.

​
10.1 Turn the feature on

Endpoint: POST /v1.0/subscribers/guardian-features
Request
{
  "SubscriberId": "TSUID-…",
  "EnableIntelligentGuardianCalls": true,
  "EnableIntelligentGuardianMessages": true
}
GET /v1.0/subscribers/guardian-features?SubscriberId=TSUID-… returns the current flags so your UI can render checkbox state.

​
10.2 Voice — Allow / Block only

Endpoint: POST /v1.0/subscribers/call-filter
Request
{
  "SubscriberId": "TSUID-…",
  "Phone": "+18015551234",
  "AllowedNumbers": ["+18015550001", "+18015550002"],
  "BlockedNumbers": ["+18015559999"]
}
Manage entries incrementally:
POST /v1.0/subscribers/call-filter/allowed-numbers/add
{
  "SubscriberId": "TSUID-…",
  "CallFilterId": "CFID-…",
  "Numbers": ["+15555555555"]
}
POST /v1.0/subscribers/call-filter/blocked-numbers/add
{
  "SubscriberId": "TSUID-…",
  "CallFilterId": "CFID-…",
  "Numbers": ["+15555556666"]
}
Voice Filter Levels — future release for SIP. The Call Filter API can accept CHILD / ADOLESCENT / TEENAGER as FilterMode values, but voice-level filtering for these modes is not enabled for MVNOs today. For now, voice = allow + block only.

​
10.3 SMS — Allow / Block + Filter Levels

Endpoint: POST /v1.0/subscribers/message-filter For SMS, in addition to allow/block, MVNOs can apply a Filter Level: CHILD, ADOLESCENT, or TEENAGER. These set a graded sensitivity baseline that Telegent applies on top of your custom allow/block lists.
Request
{
  "SubscriberId": "TSUID-…",
  "Phone": "+18015551234",
  "FilterMode": "ACTIVE",
  "AllowedContacts": ["+18015550001"],
  "BlockedContacts": ["+18015559999"],
  "ApplyToInbound": true,
  "ApplyToOutbound": true,
  "BlockLinks": true,
  "BlockMedia": true
}
Manage lists incrementally:
POST /v1.0/subscribers/message-filter/allowed-contacts/add
{
  "SubscriberId": "TSUID-…",
  "MessageFilterId": "MFID-…",
  "Contacts": ["+15555555555"]
}
POST /v1.0/subscribers/message-filter/blocked-contacts/add
{
  "SubscriberId": "TSUID-…",
  "MessageFilterId": "MFID-…",
  "Contacts": ["+15555556666"]
}

​
SMS Filter Levels

LevelDescription
CHILDMost restrictive. Strong blocking on adult content, links, and unknown senders.
ADOLESCENTModerate. Blocks the worst categories but allows most everyday messaging.
TEENAGERLightest of the three. Filters extreme content; otherwise hands-off.
This document is a living guide. When in doubt, the OpenAPI spec at docs.telegent.com is the source of truth. The Postman collection “Telegent Core APIs.json” is a great companion — every endpoint above is in there.