# Create New Account
Source: https://docs.telegent.com/api-reference/accounts/create-new-account

/api-reference/openapi.json post /v1.0/account/create
Create a new account with administrator email, billing, and mailing address information. Returns the newly created account details.

**What this does:** Returns the new account's `AccountId` (`AID-`) and confirmation of the created details. Store the `AID-` — it is required when creating subscribers and subscriptions under this account.

**Next steps:**
- Create a subscriber under this account — `POST /v1.0/subscribers/create`
- Assign packages — `POST /v1.0/subscriptions`



# Get Account Details
Source: https://docs.telegent.com/api-reference/accounts/get-account-details

/api-reference/openapi.json get /v1.0/account
Retrieve details for a specific account. Accounts sit below a distributor in the hierarchy and contain subscribers along with their associated phone numbers and services. Returns the account name, total subscriber count, address details, and the parent distributor reference.

**What this does:** Returns the account's name, contact info, billing and mailing addresses, and status. Use this to confirm account configuration or retrieve the `AID-` needed for subscriber and subscription calls.

**Next steps:**
- Update account details — `POST /v1.0/account/update`
- View account's numbers — `GET /v1.0/numbers/inventory`



# Get Account Schedules
Source: https://docs.telegent.com/api-reference/accounts/get-account-schedules

/api-reference/openapi.json get /v1.0/account/schedules
Retrieve a list of all schedules configured for your account.

**What this does:** Returns a list of schedule IDs and names configured on the account. Schedules control business-hours routing for workgroups. Use this to look up a `SCH-` ID before attaching it to a workgroup.

**Next steps:**
- Get full schedule details — `GET /v1.0/schedules`
- Create a schedule — `POST /v1.0/schedules`



# Get Account Webhooks
Source: https://docs.telegent.com/api-reference/accounts/get-account-webhooks

/api-reference/openapi.json get /v1.0/account/webhooks
Retrieves all webhooks configured on the specified account, including their target URLs, HTTP methods, authentication settings, subscribed event types, and active status. Use this to audit webhook configuration or to locate a specific `WebhookId` for updates or deletion.



# Get Account's Workgroups
Source: https://docs.telegent.com/api-reference/accounts/get-accounts-workgroups

/api-reference/openapi.json get /v1.0/account/workgroups
Retrieve all workgroups associated with the authenticated account. Returns a list of workgroups with their IDs, names, and configuration status.

**What this does:** Returns a list of workgroups configured on the account including their IDs, names, types, and active status. Use this to look up a `WG-` ID before attaching it to a voice route or schedule.

**Next steps:**
- Get full workgroup details — `GET /v1.0/workgroups`
- Create a workgroup — `POST /v1.0/workgroups`



# Get Packages
Source: https://docs.telegent.com/api-reference/accounts/get-packages

/api-reference/openapi.json get /v1.0/account/packages
Retrieve a list of all packages available in your account. Use the optional Filter parameter to filter by package status (e.g., Active, Inactive).

**What this does:** Returns a list of packages available on the account with their IDs, names, and pricing. Use this to look up a `PID-` before creating a subscription.

**Next steps:**
- Get package details — `GET /v1.0/packages`
- Create a subscription — `POST /v1.0/subscriptions`



# Get Products
Source: https://docs.telegent.com/api-reference/accounts/get-products

/api-reference/openapi.json get /v1.0/account/products
Retrieve a list of all products available in your account. Use the optional Filter parameter to filter by product status (e.g., Active, All).

**What this does:** Returns a list of products available on the account. Products define the base service capabilities that are bundled into packages.

**Next steps:**
- Get product details — `GET /v1.0/products`
- Create a product — `POST /v1.0/products`



# Get Services
Source: https://docs.telegent.com/api-reference/accounts/get-services

/api-reference/openapi.json get /v1.0/account/services
Retrieve a list of all services available in your account. Use the optional Filter parameter to filter by service status (e.g., Active, Inactive).

**What this does:** Returns a list of services available on the account. Services are the billable components that make up products and packages.

**Next steps:**
- Get service details — `GET /v1.0/services`
- Create a service — `POST /v1.0/services`



# Get Subscriptions
Source: https://docs.telegent.com/api-reference/accounts/get-subscriptions

/api-reference/openapi.json get /v1.0/account/subscriptions
Retrieve a list of all subscriptions associated with your account. Use the optional Filter parameter to filter by subscription status (e.g., Active, Inactive).

**What this does:** Returns a list of subscriptions on the account with their IDs, package associations, and status. Useful for auditing which subscribers have active plans.

**Next steps:**
- Get subscription details — `GET /v1.0/subscriptions`
- Create a subscription — `POST /v1.0/subscriptions`



# List Message Routes
Source: https://docs.telegent.com/api-reference/accounts/list-message-routes

/api-reference/openapi.json get /v1.0/account/message/routes
Retrieve a list of all message routes configured in your account. Returns basic information about each route including MRID, name, and webhook configuration.

**What this does:** Returns a list of message routes (`MRID-` IDs) configured on the account. Use this to find an existing route ID before provisioning a new number or updating a number's message configuration.

**Next steps:**
- Get full route details — `GET /v1.0/message/routes`
- Create a new route — `POST /v1.0/message/routes`



# List Voice Routes
Source: https://docs.telegent.com/api-reference/accounts/list-voice-routes

/api-reference/openapi.json get /v1.0/account/voice/routes
Retrieve a list of all voice routes configured in your account. Returns basic information about each route including CRID, name, and routing configuration.

**What this does:** Returns a list of voice routes (`CRID-` IDs) configured on the account. Use this to find an existing route ID before provisioning a number with voice enabled or updating call routing.

**Next steps:**
- Get full route details — `GET /v1.0/voice/routes`
- Create a new route — `POST /v1.0/voice/routes`



# Update Account
Source: https://docs.telegent.com/api-reference/accounts/update-account

/api-reference/openapi.json post /v1.0/account/update
Update an existing account's information including name and address details.

**What this does:** Returns the updated account record. Only the fields you send are changed; omitted fields retain their current values.

**Next steps:**
- Confirm the update — `GET /v1.0/account`



# Create Distributor
Source: https://docs.telegent.com/api-reference/distributors/create-distributor

/api-reference/openapi.json post /v1.0/distributor/create
Create a new distributor with billing and mailing address information. Returns the newly created distributor details including account key and secret.

**What this does:** Returns the new distributor's `DistributorId` (`DID-`) and created record. The `DID-` is the root identifier for all accounts, packages, and products under this distributor.

**Next steps:**
- Create an account under this distributor — `POST /v1.0/account/create`



# Get Accounts
Source: https://docs.telegent.com/api-reference/distributors/get-accounts

/api-reference/openapi.json get /v1.0/distributor/accounts
Retrieve a list of all accounts associated with the distributor. Returns account information including name, total subscribers, and address details.

**What this does:** Returns a list of all accounts under this distributor including their `AID-` IDs, names, and status. Use this to enumerate accounts before making account-specific calls.

**Next steps:**
- Get account details — `GET /v1.0/account`
- Create an account — `POST /v1.0/account/create`



# Get Distributor Details
Source: https://docs.telegent.com/api-reference/distributors/get-distributor-details

/api-reference/openapi.json get /v1.0/distributor
Retrieve details for a distributor account. Distributors sit at the top of the account hierarchy and can create and manage multiple sub-accounts (AID-) and their subscribers. Returns the distributor's account key (DID-), secret, total accounts managed, and address information.

**What this does:** Returns the distributor's name, contact info, billing and mailing addresses, and status. The `DID-` from this response is the top-level identifier used throughout the account hierarchy.

**Next steps:**
- View accounts under this distributor — `GET /v1.0/distributor/accounts`
- Update distributor — `POST /v1.0/distributor/update`



# Get Distributor Package List
Source: https://docs.telegent.com/api-reference/distributors/get-distributor-package-list

/api-reference/openapi.json get /v1.0/distributor/packages
Retrieve the list of packages associated with the distributor. Filter by status (All, Active, Inactive).

**What this does:** Returns the list of packages configured at the distributor level with their IDs, names, and pricing. Packages group products for subscription assignment.

**Next steps:**
- Get package details — `GET /v1.0/packages`
- Create a subscription — `POST /v1.0/subscriptions`



# Get Distributor Product List
Source: https://docs.telegent.com/api-reference/distributors/get-distributor-product-list

/api-reference/openapi.json get /v1.0/distributor/products
Retrieve the list of products associated with the distributor. Filter by status (All, Active, Inactive).

**What this does:** Returns the list of products configured at the distributor level. Products defined here can be included in packages offered to accounts.

**Next steps:**
- Get product details — `GET /v1.0/products`
- Create a product — `POST /v1.0/products`



# Get Distributor Subscription List
Source: https://docs.telegent.com/api-reference/distributors/get-distributor-subscription-list

/api-reference/openapi.json get /v1.0/distributor/subscriptions
Retrieve the list of subscriptions associated with the distributor. Filter by status (All, Active, Inactive).

**What this does:** Returns a list of all subscriptions under the distributor filtered by the optional `Filter` value. Use this for a distributor-wide view of active plans.

**Next steps:**
- Get subscription details — `GET /v1.0/subscriptions`



# Get Subscribers
Source: https://docs.telegent.com/api-reference/distributors/get-subscribers

/api-reference/openapi.json get /v1.0/distributor/subscribers
Retrieve a paginated list of all subscribers under the distributor. Returns subscriber details including ID, name, email, phone numbers, role, and associated account information.

**What this does:** Returns a paginated list of all subscribers across all accounts under the distributor. Use `PageNumber` and `TotalPerPage` to page through large result sets. Each record includes the subscriber's `TSUID-` and account association.

**Next steps:**
- Get individual subscriber details — `GET /v1.0/subscribers/get`



# Update Distributor
Source: https://docs.telegent.com/api-reference/distributors/update-distributor

/api-reference/openapi.json post /v1.0/distributor/update
Update an existing distributor's information including name and address details.

**What this does:** Returns the updated distributor record. Only fields you send are changed; omitted fields retain their current values.

**Next steps:**
- Confirm the update — `GET /v1.0/distributor`



# Health Status
Source: https://docs.telegent.com/api-reference/health-status/health-status

/api-reference/openapi.json post /v1.0/health-status
Check that the Telegent platform and its upstream dependencies are reachable. Use this as a pre-flight check before a batch of provisioning calls, or as the target for an uptime monitor.

**What this checks:**
- **`Database`** — the Telegent platform database connection.
- **`TMobile_Api`** — reachability of the upstream T-Mobile API, verified with a live available-products call.

Each check reports its own `Status`, how long it took in `Duration_Ms`, and an `Error` string that is `null` while the dependency is healthy. The top-level `Status` summarises both, and `Checked_On_UTC` is the UTC timestamp the checks ran.

**Reading the response:** A dependency being unreachable does not fail the request — this endpoint returns HTTP `200` and reports the problem in the payload. Always read `Status` rather than relying on the HTTP status code alone, and check each dependency's `Error` for the underlying cause.

**Note on `Duration_Ms`:** these are live round-trip times against the dependency, not cached values, so a slow-but-healthy upstream shows up as a large `Duration_Ms` with `Status: "Ok"`.



# API Reference
Source: https://docs.telegent.com/api-reference/introduction



## Overview

The Telegent mPaaS API gives you programmatic control over the full mobile communications
lifecycle — from provisioning and porting phone numbers, to routing voice calls
and sending messages, to managing subscribers, accounts, packages, and AI-powered filtering.

All requests are made over HTTPS to the base URL:

```text theme={null}
https://api.telegent.com/v1.0
```

Responses are JSON and always include a `Successful` field:

```json theme={null}
{
  "Successful": true,
  "Data": { ... }
}
```

***

## Rate Limits

Each distributor is limited to **120 requests per minute**, counted across all endpoints.
The limit applies API-wide, so requests to any combination of endpoints draw from the
same per-minute allowance.

When the limit is exceeded, the API responds with HTTP `429 Too Many Requests`:

```json theme={null}
{
  "Successful": false,
  "Message": "Too many requests. Please contact support."
}
```

In addition to the API-wide limit, the **Number Provision** (`POST /v1.0/numbers/provision`)
and **Port-In** (`POST /v1.0/numbers/portin`) endpoints are each limited to **1 request per second**.
This per-endpoint limit applies separately from the 120 requests/minute allowance and also returns
HTTP `429` when exceeded.

If you consistently reach either limit, [contact support](https://support.telegent.com/support/home)
to discuss your usage requirements.

***

## Quick Start

<Steps>
  <Step title="Get Your Credentials">
    Obtain your `AccountKey` and `AccountSecret` from your Telegent representative or
    the [API Portal](https://api.telegent.com).
  </Step>

  <Step title="Authenticate">
    Exchange your credentials for a Bearer token via `POST /v1.0/oauth2/tokens`.
    See the [OAuth2 endpoint](/api-reference/oauth2/generate-api-token) for details.
  </Step>

  <Step title="Make Your First Call">
    Include the token in the `Authorization` header on every request:

    ```http theme={null}
        Authorization: Bearer YOUR_TOKEN_HERE
    ```
  </Step>
</Steps>

***

## API Categories

<CardGroup>
  <Card title="OAuth2" icon="key" href="/api-reference/oauth2/generate-api-token">
    Exchange credentials for a Bearer token
  </Card>

  <Card title="Numbers" icon="phone" href="/api-reference/numbers/search-available-numbers">
    Search availability, provision numbers, manage inventory, and configure data usage
  </Card>

  <Card title="Number Porting" icon="arrows-left-right" href="/api-reference/numbers/numbers-port-in">
    Port numbers in or out, check eligibility, and manage port requests
  </Card>

  <Card title="Message" icon="message" href="/api-reference/message/create-message-route">
    Create message routes, send outbound SMS/MMS, and query message history
  </Card>

  <Card title="Voice" icon="phone-volume" href="/api-reference/voice/create-voice-route">
    Configure voice routes and manage outbound/inbound call handling
  </Card>

  <Card title="Workgroups" icon="microphone" href="/api-reference/workgroups/create-workgroup">
    Manage workgroups, activities, and call handling logic
  </Card>

  <Card title="Products, Packages & Subscriptions" icon="box" href="/api-reference/products/product-details">
    Define services and products, bundle into packages, and manage subscriptions
  </Card>

  <Card title="AI Guardian" icon="shield" href="/api-reference/subscribers/create-message-filter">
    Configure per-subscriber call and message filters, blocked contacts, and
    guardian relationships
  </Card>

  <Card title="Accounts & Subscribers" icon="users" href="/api-reference/subscribers/get-subscriber-details">
    Create and manage accounts, subscribers, aggregators, and distributors
  </Card>
</CardGroup>

***

## Need Help?

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/quick-start-guide">
    Step-by-step authentication and first API call
  </Card>

  <Card title="API Portal" icon="globe" href="https://api.telegent.com">
    Access the API management console
  </Card>

  <Card icon="life-ring" href="https://support.telegent.com/support/home" title="Support">
    Visit our support portal for help and resources
  </Card>
</CardGroup>


# Create Message Route
Source: https://docs.telegent.com/api-reference/message/create-message-route

/api-reference/openapi.json post /v1.0/message/routes
Create a new message route to configure how inbound SMS/MMS messages are handled. Specify webhook URLs for message delivery, fallback URLs, and HTTP methods. Each route is identified by a unique MRID (Message Route ID).

**What this does:** Returns the new route's `MessageRouteId` (`MRID-`). Store this ID — it is required when provisioning numbers and can be assigned to multiple numbers. The webhook URL you configure receives a POST for every inbound message on numbers using this route.

**Next steps:**
- Assign the route to a number at provision time — `POST /v1.0/numbers/provision`
- Update route settings — `POST /v1.0/message/routes/update`



# Delete Message Route
Source: https://docs.telegent.com/api-reference/message/delete-message-route

/api-reference/openapi.json post /v1.0/message/routes/delete
Permanently delete a message route from your account. Phone numbers using this route will need to be reassigned to a different route before deletion. This action cannot be undone.

**What this does:** Returns a confirmation of deletion. Numbers assigned to this route will lose their message routing — reassign them to a different route before deleting to avoid service disruption.

**Next steps:**
- Create a replacement route — `POST /v1.0/message/routes`
- Update affected numbers — `POST /v1.0/numbers/update`



# Filter Messages
Source: https://docs.telegent.com/api-reference/message/filter-messages

/api-reference/openapi.json get /v1.0/message/filter
Retrieve messages filtered by phone number with pagination support. Returns a list of inbound and outbound messages for a specific number.

**What this does:** Returns a paginated list of messages for the given phone number. Returns message IDs, bodies, direction, status, and timestamps. Use this to review message history or confirm delivery for a specific number.

**Next steps:**
- Send a message — `POST /v1.0/message/outbound`



# Message Route Details
Source: https://docs.telegent.com/api-reference/message/message-route-details

/api-reference/openapi.json get /v1.0/message/routes
Retrieve detailed configuration for a specific message route using its MRID. Returns webhook URLs, HTTP methods, timeout settings, and associated phone numbers.

**What this does:** Returns the full route configuration including webhook URL, HTTP method, authentication settings, and callback URL. Use this to confirm route settings before assigning it to a number, or to retrieve the `MRID-` for use in provisioning.

**Next steps:**
- Update route — `POST /v1.0/message/routes/update`
- Provision a number using this route — `POST /v1.0/numbers/provision`



# Report Device Delivery
Source: https://docs.telegent.com/api-reference/message/report-device-delivery

/api-reference/openapi.json post /v1.0/message/device-delivery
Submit a device-level delivery confirmation for an outbound message. This endpoint is used to record whether a specific message was successfully delivered to the recipient's handset, beyond carrier-level delivery receipts. Provide the MessageId returned from the Send Outbound Message endpoint.

**What this does:** Records a device-level delivery receipt against an existing message. Use this when your application receives an on-device delivery confirmation and wants to update the platform's delivery status record for a message.

**Next steps:**
- View the updated message status — `GET /v1.0/message/filter`



# Send Outbound Message
Source: https://docs.telegent.com/api-reference/message/send-outbound-message

/api-reference/openapi.json post /v1.0/message/outbound
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Provisioned phone number with messaging enabled (`From` field) — `POST /v1.0/numbers/provision`

---

Send an outbound SMS or MMS message from your provisioned phone number. Supports single recipient messaging with optional media attachments for MMS. Returns a message ID for delivery tracking. All phone numbers must be in E.164 format.

**What this does:** Sends an SMS or MMS message immediately and returns a `MessageId` for tracking delivery. The message is routed through the `MessageRouteId` associated with the `From` number. Check delivery status using the MessageId.

**Next steps:**
- Check message status — `GET /v1.0/message/filter`



# Update Message Route
Source: https://docs.telegent.com/api-reference/message/update-message-route

/api-reference/openapi.json post /v1.0/message/routes/update
Update an existing message route's configuration including webhook URLs, HTTP methods, and timeout settings. Changes apply immediately to all numbers using this route.

**What this does:** Returns the updated route configuration. Only the fields you send are changed; omitted fields retain their current values. Changes apply immediately to all numbers using this route — no re-provisioning needed.

**Next steps:**
- Confirm the update — `GET /v1.0/message/routes`
- View numbers using this route — `GET /v1.0/numbers/inventory`



# Data Usage Info
Source: https://docs.telegent.com/api-reference/numbers/data-usage-info

/api-reference/openapi.json post /v1.0/numbers/data-usage/info
Retrieve real-time data usage information for one or more phone numbers, including amount used, remaining data, and current behavior (active, throttled, etc.).

**What this does:** Returns current consumed data and remaining data for each number in the batch. Values are in the unit specified by `ValueUnit` (MB). Use this for real-time monitoring dashboards or to decide whether to adjust a number's data limit.

**Next steps:**
- Update data limits — `POST /v1.0/numbers/data-usage`
- View current limit settings — `POST /v1.0/numbers/data-usage/settings`



# Data Usage Limit
Source: https://docs.telegent.com/api-reference/numbers/data-usage-limit

/api-reference/openapi.json post /v1.0/numbers/data-usage
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Provisioned number ID (NID) with `DataEnabled: true` — `POST /v1.0/numbers/provision`

---

Set data usage limits, notification thresholds, and throttling parameters for IoT/MVNO numbers. Configure when subscribers are notified and at what usage level data speeds are throttled. **Important:** NotifyValue, ThrottleValue, and LimitValue must be in ascending increments and cannot be the same value (e.g., NotifyValue < ThrottleValue < LimitValue). Unless a `LimitValue` is specified, the default data limit is **20 MB**.

**What this does:** Returns the updated data usage configuration for each number in the batch. Settings take effect at the next billing cycle or usage event. A `NotifyValue` triggers a notification webhook when usage reaches that threshold; `LimitValue` hard-caps usage; `ThrottleValue` reduces speed instead of cutting off.

**Next steps:**
- Confirm the new settings — `POST /v1.0/numbers/data-usage/settings`
- Check current consumption — `POST /v1.0/numbers/data-usage/info`



# Data Usage Settings
Source: https://docs.telegent.com/api-reference/numbers/data-usage-settings

/api-reference/openapi.json post /v1.0/numbers/data-usage/settings
Retrieve the current data usage settings (notify value, throttle value, limit value) for one or more phone numbers.

**What this does:** Returns the current `NotifyValue`, `LimitValue`, `ThrottleValue`, `ThrottleSpeed`, and `ValueUnit` for each number. Use this to audit a number's data policy before making changes.

**Next steps:**
- Update data usage settings — `POST /v1.0/numbers/data-usage`
- Check current consumption — `POST /v1.0/numbers/data-usage/info`



# Data Usage Update Renewal Info
Source: https://docs.telegent.com/api-reference/numbers/data-usage-update-renewal-info

/api-reference/openapi.json post /v1.0/numbers/data-usage/update-renewal-info
Configure the monthly or weekly data usage renewal cycle for one or more phone numbers. Use this endpoint to set the day usage resets, enable or disable auto-renew, and optionally zero out current usage immediately.

**What this does:** Updates the renewal schedule anchored to each number's individual  — this is not a global calendar reset. Set  to zero out a number's current usage immediately without waiting for the next cycle.

**Next steps:**
- Confirm current usage after a reset — 
- Review configured thresholds — 



# Device Details
Source: https://docs.telegent.com/api-reference/numbers/device-details

/api-reference/openapi.json post /v1.0/numbers/device-details
Retrieve the full device profile for a handset by its `IMEI` — model, manufacturer, TAC, and detailed SIM, technology, capability, network-compatibility, and certification data. `AccountId` is required for Distributors managing multiple accounts.

**What this does:** Looks up a device by `IMEI` and returns its complete specifications. `Sim_Specifications`, `Technology`, `Device_Specifications`, `Device_Capabilities`, `Network_Compatibility`, and `Certification` are returned as JSON-encoded strings (parse them client-side). Number ownership is not required — any IMEI can be queried.

**Next steps:**
- Update the number — `POST /v1.0/numbers/update`
- Check data usage — `POST /v1.0/numbers/data-usage/info`



# Device Unlock Status
Source: https://docs.telegent.com/api-reference/numbers/device-unlock-status

/api-reference/openapi.json post /v1.0/numbers/device/unlock-status
Check the carrier unlock status of a device by IMEI or by phone number. Works for any IMEI, including devices on other carriers that have never been provisioned on the Telegent network.

**Two ways to look up a device:**
- **By `IMEI`** — the general-purpose lookup. Works for any device on any carrier, whether or not it exists in your account. `PhoneNumber` is returned empty.
- **By `PhoneNumber`** — only works for numbers assigned to your own account. The device's `IMEI` is resolved automatically and returned alongside the lock status.

`PhoneNumber` is optional; if it is blank, `IMEI` is required. The response shape is the same either way.

**Reading the response:** This endpoint returns HTTP `200` even when the lookup fails. Always check the `Status` field — `Success` means `UnlockStatus` is populated, `FAILED` means `UnlockStatus` is `null` and `StatusMessage` carries the upstream error (for example `GENS-0020 Invalid IMEI` or `GENS-0013 Invalid MSISDN`).

**Next steps:**
- Retrieve device model, manufacturer and TAC — `POST /v1.0/numbers/device-details`
- Check the number's service status — `POST /v1.0/numbers/status`



# Number Details
Source: https://docs.telegent.com/api-reference/numbers/number-details

/api-reference/openapi.json get /v1.0/numbers
Get comprehensive details for a specific phone number including its capabilities (voice, SMS, MMS, data), message routes, voice routes, classification, and current configuration.

**What this does:** Returns the full configuration for a specific number: capabilities (voice, messaging, data), assigned routes, subscriber ID, ICCID, status, and number type. Use this to confirm provisioning details or look up a number's `NID-` for use in other calls.

**Next steps:**
- Update the number — `POST /v1.0/numbers/update`
- Check data usage — `POST /v1.0/numbers/data-usage/info`



# Number Provision (Purchase/Order)
Source: https://docs.telegent.com/api-reference/numbers/number-provision-purchaseorder

/api-reference/openapi.json post /v1.0/numbers/provision
> **Rate limit:** This endpoint is limited to **1 request per second**, separate from the API-wide 120 requests/minute limit. Exceeding it returns HTTP `429 Too Many Requests`.

**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Message Route ID (MRID) — `POST /v1.0/message/routes`
- **Optional:** Voice Route ID (CRID) — `POST /v1.0/voice/routes` *(only needed if `VoiceEnabled: true`)*
- **Optional:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create` *(to assign the number at provision time)*

---

Purchase and activate a phone number on your account. Before provisioning, ensure you have already created a Message Route (MRID) and Voice Route (CRID) — numbers provisioned without routes will have no call or message handling. Specify the number classification (`mvno` for full messaging and voice, `iot` for data and p2p messaging only), and required capabilities. Returns an OrderId for status tracking.

**What this does:** Purchases and activates the number, returning an `OrderId`, the assigned phone number in E.164 format, a `PhoneNumberId` (`NID-`), and an eSIM QR code (if applicable). The `OrderId` can be used to track provisioning status.

**Next steps:**
- Check order status — `GET /v1.0/numbers/order`
- Send a test message — `POST /v1.0/message/outbound`



# Numbers - Cancel Port In
Source: https://docs.telegent.com/api-reference/numbers/numbers--cancel-port-in

/api-reference/openapi.json post /v1.0/numbers/portin/cancel
Cancel an existing port-in request using the order ID. This endpoint allows you to cancel a pending port-in order before it is completed.

**What this does:** Returns the `OrderId` and a `Cancelled` status confirmation. Only pending port-in orders can be cancelled — orders in final states cannot be reversed.

**Next steps:**
- Submit a new port-in request — `POST /v1.0/numbers/portin`



# Numbers - Get E911 Address
Source: https://docs.telegent.com/api-reference/numbers/numbers--get-e911-address

/api-reference/openapi.json get /v1.0/numbers/e911address
Retrieve the E911 emergency address registered to a specific phone number. Returns the street address on file that will be dispatched to emergency services when a 911 call is placed from this number.

**What this does:** Looks up the E911 address associated with the given phone number on your account.

**Next steps:**
- Update an E911 address — `POST /v1.0/numbers/e911address/update`



# Numbers - Port In
Source: https://docs.telegent.com/api-reference/numbers/numbers--port-in

/api-reference/openapi.json post /v1.0/numbers/portin
> **Rate limit:** This endpoint is limited to **1 request per second**, separate from the API-wide 120 requests/minute limit. Exceeding it returns HTTP `429 Too Many Requests`.

**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Recommended:** Confirm the number is portable first — `POST /v1.0/numbers/portin/eligibility`
- **Required:** Losing carrier name, account number, account password, and subscriber billing address

---

Transfer an existing phone number from another carrier into your Telegent account. Before submitting a port-in, run the Port-In Eligibility check to confirm the number can be ported. You will need the losing carrier name, account number, account password, and the subscriber's billing address for LNP (Local Number Portability) compliance.

**What this does:** Submits the port request to the carrier and returns an `OrderId` with an initial status of `Pending`. Monitor the order using the `OrderId`. Port requests typically take 1-5 business days to complete.

**Next steps:**
- Track the port order status — `GET /v1.0/numbers/order`
- Cancel if needed — `POST /v1.0/numbers/portin/cancel`



# Numbers - Port In Eligibility
Source: https://docs.telegent.com/api-reference/numbers/numbers--port-in-eligibility

/api-reference/openapi.json post /v1.0/numbers/portin/eligibility
Check if a phone number is eligible for port-in before submitting a full port request. Returns the eligibility status for the number.

**What this does:** Returns an `Eligible` boolean, the `TargetClassification`, and a `StatusMessage`. Run this before submitting a port-in to avoid failed orders. If `Eligible` is false, the `StatusMessage` explains why.

**Next steps:**
- If eligible, submit the port-in — `POST /v1.0/numbers/portin`



# Numbers - Port Out
Source: https://docs.telegent.com/api-reference/numbers/numbers--port-out

/api-reference/openapi.json post /v1.0/numbers/portout
Assign a Port Out PIN to a phone number on your Telegent account. The PIN you set here is the PIN you will be required to provide when you later initiate a port-out transfer to another carrier.

**What this does:** Saves the specified PIN against the phone number so it can be used to authorize a future port-out request.

**Next steps:**
- Track the port-out order — `GET /v1.0/numbers/order`



# Numbers - Reactivate
Source: https://docs.telegent.com/api-reference/numbers/numbers--reactivate

/api-reference/openapi.json post /v1.0/numbers/reactivate
> **Reactivation window:** A cancelled number is eligible for reactivation for **24 hours** after cancellation.

Restore a recently cancelled phone number back to active status on your account. Reactivation preserves the original MSISDN ↔ ICCID relationship, so the number and SIM do not need to be reprovisioned. Use this to recover a number that was deactivated in error, provided the 24-hour window has not expired and the number has not been released back to inventory.

**If the window has expired:** the request is rejected with `Number '<MSISDN>' cannot be reactivated as it was cancelled more than 24 hours ago.` A new provision is required instead — `POST /v1.0/numbers/provision`.



# Numbers - Refresh NNID
Source: https://docs.telegent.com/api-reference/numbers/numbers--refresh-nnid

/api-reference/openapi.json post /v1.0/numbers/refresh-nnid
Refresh the Network Number Identifier (NNID) for a phone number. Use this when a number’s NNID becomes stale or needs to be re-synchronized with the carrier network.

**What this does:** Triggers a re-sync of the number's Network Number Identifier with the carrier network and returns the refreshed `NNID` value. Use this when a number's carrier routing appears stale or incorrect after a number transfer.

**Next steps:**
- Confirm number state — `GET /v1.0/numbers`



# Numbers - Update E911 Address
Source: https://docs.telegent.com/api-reference/numbers/numbers--update-e911-address

/api-reference/openapi.json post /v1.0/numbers/e911address/update
Register or update the E911 emergency address for a phone number. This address is provided to emergency services when a 911 call is placed from the specified number. Ensure the address is accurate and matches a valid MSAG (Master Street Address Guide) location.

**What this does:** Sets or updates the E911 service address associated with the given phone number.

**Next steps:**
- Verify the updated address — `GET /v1.0/numbers/e911address`



# Numbers - Update MMS Settings
Source: https://docs.telegent.com/api-reference/numbers/numbers--update-mms-settings

/api-reference/openapi.json post /v1.0/numbers/mms/update
Enable or disable MMS (multimedia messaging) on a provisioned phone number. Use this to turn picture, video and group messaging on for a line, or to disable it while leaving SMS in place.

**What this does:** Sets the MMS feature flag on the line and returns the resulting state. SMS is unaffected either way — disabling MMS does not stop the line sending or receiving text messages.

**Reading the response:** `MMS` reflects the state of the line after the update (`Enabled` or `Disabled`). Check `Status` — `Success` means the change was applied; any other value means it was not, and `StatusMessage` carries the reason.

**Next steps:**
- Confirm the line's current service state — `POST /v1.0/numbers/status`
- Update other number settings (including `MessageEnabled` for SMS) — `POST /v1.0/numbers/update`
- Review the account's message routing — `GET /v1.0/message/routes`



# Numbers - Update Port In
Source: https://docs.telegent.com/api-reference/numbers/numbers--update-port-in

/api-reference/openapi.json post /v1.0/numbers/portin/update
Update an existing port-in order with new information such as carrier details, account credentials, or billing address before the port completes.

**What this does:** Returns confirmation that the port-in order has been updated. Use this before the port completes if the carrier details or billing address provided were incorrect.

**Next steps:**
- Check order status — `GET /v1.0/numbers/order`
- Cancel if needed — `POST /v1.0/numbers/portin/cancel`



# Numbers Inventory
Source: https://docs.telegent.com/api-reference/numbers/numbers-inventory

/api-reference/openapi.json get /v1.0/numbers/inventory
Retrieve a paginated list of all phone numbers currently provisioned in your account. Filter by number type, capabilities, and status. Includes detailed information about each number's configuration and services.

**What this does:** Returns a paginated list of all provisioned numbers on the account. Each record includes the phone number, `NID-`, capabilities, assigned routes, subscriber, and status. Use this to audit your number pool or find a specific number's ID.

**Next steps:**
- Get details for a specific number — `GET /v1.0/numbers`
- Update a number — `POST /v1.0/numbers/update`



# Numbers Inventory Report
Source: https://docs.telegent.com/api-reference/numbers/numbers-inventory-report

/api-reference/openapi.json post /v1.0/numbers/inventory-report
Request a full inventory report for a distributor. Instead of paging through `GET /v1.0/numbers/inventory`, this endpoint runs a single query and delivers the results asynchronously: a CSV of every number on the account — with its number details — is generated and emailed to the distributor's admin email.

**What this does:** Accepts the request and returns `200 OK` immediately with no body. The report is generated in the background and emailed to the `AdminEmail` configured on the distributor (set via `POST /v1.0/distributor/create` or `POST /v1.0/distributor/update`). Use it for bulk exports and reconciliation without hammering the paginated inventory endpoint.

**Next steps:**
- Set or update the recipient — `POST /v1.0/distributor/update`
- Browse inventory interactively — `GET /v1.0/numbers/inventory`



# Numbers Status
Source: https://docs.telegent.com/api-reference/numbers/numbers-status

/api-reference/openapi.json post /v1.0/numbers/status
> **Swap limit:** A number can only be swapped **twice every 120 days**. Additional `Swap` requests for the same number within that rolling window will be rejected.

Check the current status of one or more phone numbers including provisioning state, active services, and any pending changes or issues.

**What this does:** Returns the status result for each number in the batch. Use action codes such as `Cancel`, `Park`, `Swap`, `Replace`, `Swap-Sim`, or `Activate` to change number lifecycle state. Each result includes the number, the action taken, and success or error status.

**Next steps:**
- Confirm new number state — `GET /v1.0/numbers`
- View inventory — `GET /v1.0/numbers/inventory`



# Numbers Update
Source: https://docs.telegent.com/api-reference/numbers/numbers-update

/api-reference/openapi.json post /v1.0/numbers/update
Update configuration settings for one or more phone numbers. Modify message routes, voice routes, capabilities, and other number attributes. Changes take effect immediately.

**What this does:** Returns confirmation of the updated number configuration. Changes apply immediately. You can change the message route, voice route, subscriber assignment, or number settings in a single call.

**Messaging capabilities:** `MessageEnabled` (SMS) and `MmsMessageEnabled` (MMS) are independent — set either in the request to control that channel. MMS can also be changed on its own via `POST /v1.0/numbers/mms/update`. Responses return `MmsMessageEnabled` to report the line's current MMS state.

**Next steps:**
- Confirm the update — `GET /v1.0/numbers`
- Check inventory — `GET /v1.0/numbers/inventory`
- Enable or disable MMS — `POST /v1.0/numbers/mms/update`



# Order ID Details
Source: https://docs.telegent.com/api-reference/numbers/order-id-details

/api-reference/openapi.json get /v1.0/numbers/order
Retrieve detailed information about a number provisioning order using the order ID. Returns order status, requested numbers, provisioning results, and any error messages.

**What this does:** Returns the order status, order type (provision, portin, etc.), associated phone numbers, and any error message codes from the carrier. Multiple example responses are included showing common error states (account number required, number lock). Poll this endpoint after a provision or port-in to confirm completion.

**Next steps:**
- If status is Complete, the number is active — send a test message via `POST /v1.0/message/outbound`
- If status is Error, review the `OrderStatusMessage` and retry the operation



# Search Available Numbers
Source: https://docs.telegent.com/api-reference/numbers/search-available-numbers

/api-reference/openapi.json post /v1.0/numbers/availability
Search for available phone numbers before provisioning. Filter by area code or zip code, required capabilities (voice, SMS/MMS), and message type. Returns a paginated list of matching numbers. Run this step first to confirm number availability in your target area before calling the Number Provision endpoint.

**What this does:** Returns a paginated list of available area code and zip code combinations that have numbers matching your criteria. This tells you which area codes have available inventory before you commit to a provision call. Each result includes an NGP code and area code to use in `POST /v1.0/numbers/provision`.

**Next steps:**
- Provision a number from the results — `POST /v1.0/numbers/provision`



# Update roaming settings of a number
Source: https://docs.telegent.com/api-reference/numbers/update-roaming-settings-of-a-number

/api-reference/openapi.json post /v1.0/numbers/roaming/update
Enable or disable international roaming on a provisioned phone number. Use this to allow a subscriber's device to register on partner networks outside their home country, or to disable roaming to prevent unexpected usage charges.



# Generate API Token
Source: https://docs.telegent.com/api-reference/oauth2/generate-api-token

/api-reference/openapi.json post /v1.0/OAuth2/tokens
Authenticates your account credentials and returns a Bearer token required for all subsequent API requests. Include this token in the `Authorization: Bearer <token>` header on every call. Tokens expire and must be refreshed. Use the optional `ApiEndpoint` field to scope a token to a specific endpoint URL for tighter security.

**What this does:** Returns a `token` string and `tokenExpiry` timestamp. Include the token as `Authorization: Bearer <token>` on every subsequent request. The optional `ApiEndpoint` field scopes the token to a single endpoint URL — a token scoped to `/v1.0/numbers/provision` will be rejected by any other endpoint. Re-authenticate from scratch when a token expires; there is no refresh mechanism.

**Next steps:**
- Use the token on any other endpoint — `POST /v1.0/numbers/provision`, `POST /v1.0/message/outbound`, etc.



# Add Package Item
Source: https://docs.telegent.com/api-reference/packages/add-package-item

/api-reference/openapi.json post /v1.0/packages/items/add
Add a product to an existing package. Specify the package, product, price, and billing frequency for the item.

**What this does:** Returns the new package item ID and confirmation. Adding an item to a package makes that product available to all subscribers with an active subscription to this package.

**Next steps:**
- View all items in the package — `GET /v1.0/packages/items`
- Remove an item — `POST /v1.0/packages/items/delete`



# Create Package
Source: https://docs.telegent.com/api-reference/packages/create-package

/api-reference/openapi.json post /v1.0/packages
Create a new package with name, description, type, price, and billing frequency. Packages bundle products together for subscriber offerings.

**What this does:** Returns the new package's `PackageId` (`PID-`) and full record. Store the `PID-` — it is required when creating subscriptions. Add products to the package using the items endpoints.

**Next steps:**
- Add items to the package — `POST /v1.0/packages/items/add`
- Create a subscription — `POST /v1.0/subscriptions`



# Delete Package
Source: https://docs.telegent.com/api-reference/packages/delete-package

/api-reference/openapi.json post /v1.0/packages/delete
Permanently delete a package by its PackageId. This action cannot be undone.

**What this does:** Returns a deletion confirmation. Packages with active subscriptions cannot be deleted — cancel all subscriptions first.

**Next steps:**
- View current subscriptions — `GET /v1.0/packages/subscriptions`
- Delete individual subscriptions — `POST /v1.0/subscriptions/delete`



# Delete Package Item
Source: https://docs.telegent.com/api-reference/packages/delete-package-item

/api-reference/openapi.json post /v1.0/packages/items/delete
Remove an item from a package. This removes the product association from the package but does not delete the product itself.

**What this does:** Returns a deletion confirmation. Removing an item from a package removes that product from the package's service bundle. Active subscriptions to this package lose access to the product going forward.

**Next steps:**
- View remaining items — `GET /v1.0/packages/items`



# Get Package Details
Source: https://docs.telegent.com/api-reference/packages/get-package-details

/api-reference/openapi.json get /v1.0/packages
Retrieve detailed information about a specific package by its PackageId. Returns package name, type, price, billing frequency, and associated distributor information.

**What this does:** Returns the package details including name, description, price, billing frequency, type, and status. Use this to retrieve the `PID-` needed when creating subscriptions or to audit package configuration.

**Next steps:**
- Create a subscription using this package — `POST /v1.0/subscriptions`
- View items in the package — `GET /v1.0/packages/items`



# Get Package Items
Source: https://docs.telegent.com/api-reference/packages/get-package-items

/api-reference/openapi.json get /v1.0/packages/items
Retrieve all items (products) included in a specific package. Returns product details, pricing, and billing information for each item in the package.

**What this does:** Returns a list of products included in the package with their prices and billing frequency. Use this to audit what services a subscriber will receive when assigned this package.

**Next steps:**
- Add a product to the package — `POST /v1.0/packages/items/add`
- Remove an item — `POST /v1.0/packages/items/delete`



# Get Package Subscriptions
Source: https://docs.telegent.com/api-reference/packages/get-package-subscriptions

/api-reference/openapi.json get /v1.0/packages/subscriptions
Retrieve all subscriptions associated with a specific package. Returns subscriber details and subscription status for each subscription linked to the package.

**What this does:** Returns a list of all active and inactive subscriptions for the package, including subscriber IDs and status. Use this before deleting a package to confirm there are no active subscriptions that would be affected.

**Next steps:**
- Delete a subscription — `POST /v1.0/subscriptions/delete`
- Get subscription details — `GET /v1.0/subscriptions`



# Update Package
Source: https://docs.telegent.com/api-reference/packages/update-package

/api-reference/openapi.json post /v1.0/packages/update
Update an existing package's name, description, type, price, or billing cycle. Changes apply immediately and affect all active subscriptions tied to this package. Use the PackageId (PID-) returned when the package was created.

**What this does:** Returns the updated package record. Changes apply to the package definition immediately but do not retroactively change active subscriptions.

**Next steps:**
- Confirm the update — `GET /v1.0/packages`
- View package subscriptions — `GET /v1.0/packages/subscriptions`



# Update Package Item
Source: https://docs.telegent.com/api-reference/packages/update-package-item

/api-reference/openapi.json post /v1.0/packages/items/update
Update an existing item within a package. Modify price, type, or billing frequency for the package item.

**What this does:** Returns the updated package item record. Use this to adjust pricing or billing frequency for a product within a specific package without affecting the product definition itself.

**Next steps:**
- Confirm the update — `GET /v1.0/packages/items`



# Create Product
Source: https://docs.telegent.com/api-reference/products/create-product

/api-reference/openapi.json post /v1.0/products
Create a new product with SKU, description, type, cost, and billing frequency. Products can be bundled into packages for subscriber offerings.

**What this does:** Returns the new product's `ProductId` (`PRID-`) and full record. Once created, add it to packages using the package items endpoints.

**Next steps:**
- Add the product to a package — `POST /v1.0/packages/items/add`
- Create a service — `POST /v1.0/services`



# Delete Product
Source: https://docs.telegent.com/api-reference/products/delete-product

/api-reference/openapi.json post /v1.0/products/delete
Permanently delete a product by its ProductId. This action cannot be undone.

**What this does:** Returns a deletion confirmation. Products included in active packages cannot be deleted — remove them from all packages first.

**Next steps:**
- Remove from a package — `POST /v1.0/packages/items/delete`



# Product Details
Source: https://docs.telegent.com/api-reference/products/product-details

/api-reference/openapi.json get /v1.0/products
Retrieve detailed information about a specific product by its ProductId. Returns SKU, description, type, cost, and billing frequency.

**What this does:** Returns the product details including SKU, description, type, cost, and billing frequency. Use this to retrieve the `PRID-` ID needed when adding products to packages.

**Next steps:**
- Add this product to a package — `POST /v1.0/packages/items/add`
- Update product — `POST /v1.0/products/update`



# Update Product
Source: https://docs.telegent.com/api-reference/products/update-product

/api-reference/openapi.json post /v1.0/products/update
Update an existing product's SKU, description, type, cost, or billing cycle. Changes apply immediately and are reflected across all packages that include this product. Use the ProductId (PID-) returned when the product was created.

**What this does:** Returns the updated product record. Only fields you send are changed. Changes affect all packages that include this product at their next billing cycle.

**Next steps:**
- Confirm the update — `GET /v1.0/products`



# Add Service Item
Source: https://docs.telegent.com/api-reference/services/add-service-item

/api-reference/openapi.json post /v1.0/services/items/add
Add a new pricing item or component to an existing service. Service items define the cost and billing frequency (monthly or one-time) for the service at a specific distributor or aggregator level.

**What this does:** Returns a confirmation for the new item. Service items define the price and billing frequency for a service at a specific distributor or aggregator scope. Multiple items can exist on a single service for different pricing tiers.

**Next steps:**
- View all items on the service — `GET /v1.0/services/items`
- Update an item — `POST /v1.0/services/items/update`



# Create Service
Source: https://docs.telegent.com/api-reference/services/create-service

/api-reference/openapi.json post /v1.0/services
Create a new service with a name, cost, and billing frequency. Services can be added to packages and assigned to subscribers.

**What this does:** Returns the new service's `ServiceId` (`SID-`) and full record. Services are the billable unit; add pricing tiers using the service items endpoints, then associate the service with products.

**Next steps:**
- Add a pricing item — `POST /v1.0/services/items/add`



# Delete Service
Source: https://docs.telegent.com/api-reference/services/delete-service

/api-reference/openapi.json post /v1.0/services/delete
Permanently delete a service by its ServiceId. This action cannot be undone.

**What this does:** Returns a deletion confirmation. Deleting a service removes it from the platform permanently — ensure it is not referenced in any active products or packages before deleting.

**Next steps:**
- View all services — `GET /v1.0/services`



# Delete Service Item
Source: https://docs.telegent.com/api-reference/services/delete-service-item

/api-reference/openapi.json post /v1.0/services/items/delete
Remove a service item from a service.

**What this does:** Returns a deletion confirmation. Removes the pricing tier from the service. Ensure no active subscriptions depend on this item before deleting.

**Next steps:**
- View remaining items — `GET /v1.0/services/items`



# Get Service Details
Source: https://docs.telegent.com/api-reference/services/get-service-details

/api-reference/openapi.json get /v1.0/services
Retrieve detailed information about a specific service by its ServiceId. Returns service name, cost, billing frequency, and status.

**What this does:** Returns the service details including name, cost, billing frequency, and status. Use this to retrieve the `SID-` ID needed when adding service items or associating the service with products.

**Next steps:**
- View service items — `GET /v1.0/services/items`
- Update service — `POST /v1.0/services/update`



# Get Service Items
Source: https://docs.telegent.com/api-reference/services/get-service-items

/api-reference/openapi.json get /v1.0/services/items
Retrieve the items (pricing tiers or components) associated with a specific service. Pass the ServiceId to get its configured items.

**What this does:** Returns the list of pricing items for the service including price, billing frequency (monthly or one-time), and distributor/aggregator scope. Use this to audit or review the pricing tiers before modifying them.

**Next steps:**
- Add a pricing item — `POST /v1.0/services/items/add`
- Update an item — `POST /v1.0/services/items/update`



# Update Service
Source: https://docs.telegent.com/api-reference/services/update-service

/api-reference/openapi.json post /v1.0/services/update
Update an existing service's name, cost, or billing cycle. Changes take effect immediately and are reflected across all packages and subscriptions that include this service. Use the ServiceId returned when the service was created.

**What this does:** Returns the updated service record. Only fields you send are changed; omitted fields retain their current values.

**Next steps:**
- Confirm the update — `GET /v1.0/services`
- View service items — `GET /v1.0/services/items`



# Update Service Item
Source: https://docs.telegent.com/api-reference/services/update-service-item

/api-reference/openapi.json post /v1.0/services/items/update
Update an existing service item's pricing or billing configuration.

**What this does:** Returns the updated service item record. Only the fields you send are changed. Pricing changes apply at the next billing cycle for active subscriptions using this service.

**Next steps:**
- Confirm the update — `GET /v1.0/services/items`



# Clear SIM Status
Source: https://docs.telegent.com/api-reference/sims/clear-sim-status

/api-reference/openapi.json post /v1.0/sims/clear-status
Reset a SIM card's status to Empty, effectively unassigning it from any active number or subscriber. Useful when decommissioning a SIM before reassigning it.

**What this does:** Returns the ICCID with a status of `Empty` and a success confirmation. After clearing, the SIM is unassigned and ready to be re-provisioned or reassigned to a different number.

**Next steps:**
- Re-provision the SIM — `POST /v1.0/numbers/provision`



# Add Allowed Contacts
Source: https://docs.telegent.com/api-reference/subscribers/add-allowed-contacts

/api-reference/openapi.json post /v1.0/subscribers/message-filter/allowed-contacts/add
Add trusted phone numbers that bypass message filtering.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and an existing `MessageFilterId` (`MFID-`)

**What this does:** Adds one or more phone numbers (E.164 format) to the allowed list. Messages from these contacts bypass all content filtering — keyword checks, link blocking, and media restrictions do not apply. Common use case: family members, doctors, or known business numbers.

**Next steps:**
- Verify the addition — `GET /v1.0/subscribers/message-filter/allowed-contacts`
- Undo — `POST /v1.0/subscribers/message-filter/allowed-contacts/remove`



# Add Allowed Numbers
Source: https://docs.telegent.com/api-reference/subscribers/add-allowed-numbers

/api-reference/openapi.json post /v1.0/subscribers/call-filter/allowed-numbers/add
Add trusted phone numbers that are allowed to call a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and an existing `CallFilterId` (`CFID-`)
- Filter is in `WHITELIST` mode for the allow list to actively gate callers (in other modes, the list is informational)

**What this does:** Adds one or more phone numbers to the allowed callers list. In `WHITELIST` mode, only numbers on this list can ring the subscriber — all others are blocked or sent to voicemail. Common use case: family members, doctors, or known business contacts.

**Next steps:**
- Verify the addition — `GET /v1.0/subscribers/call-filter/allowed-numbers`
- Undo — `POST /v1.0/subscribers/call-filter/allowed-numbers/remove`



# Add Blocked Contacts
Source: https://docs.telegent.com/api-reference/subscribers/add-blocked-contacts

/api-reference/openapi.json post /v1.0/subscribers/message-filter/blocked-contacts/add
Block phone numbers from messaging a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and an existing `MessageFilterId` (`MFID-`)

**What this does:** Adds one or more phone numbers to the blocked list. Messages from blocked contacts are silently dropped — they are never delivered, and the sender sees no error. Common use case: preventing unwanted or harassing contacts.

**Next steps:**
- Verify the addition — `GET /v1.0/subscribers/message-filter/blocked-contacts`
- Undo — `POST /v1.0/subscribers/message-filter/blocked-contacts/remove`



# Add Blocked Numbers
Source: https://docs.telegent.com/api-reference/subscribers/add-blocked-numbers

/api-reference/openapi.json post /v1.0/subscribers/call-filter/blocked-numbers/add
Block phone numbers from calling a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and an existing `CallFilterId` (`CFID-`)

**What this does:** Adds one or more phone numbers to the blocked list. Calls from blocked numbers are rejected or silently dropped — the caller may hear a disconnect tone or nothing at all. Common use case: preventing unwanted, scam, or harassing callers from reaching a subscriber.

**Next steps:**
- Verify the addition — `GET /v1.0/subscribers/call-filter/blocked-numbers`
- Undo — `POST /v1.0/subscribers/call-filter/blocked-numbers/remove`



# Configure Guardian Features
Source: https://docs.telegent.com/api-reference/subscribers/configure-guardian-features

/api-reference/openapi.json post /v1.0/subscribers/guardian-features
Enable or disable AI Guardian on a subscriber. This is the **first step** for every Guardian workflow — filters, keyword rules, and parent/child relationships will not function until Guardian is enabled here.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing Subscriber (`TSUID-`) — `POST /v1.0/subscribers/create`

**What this does:** Turns AI Guardian on or off for the subscriber's calls and messages independently. Set `EnableIntelligentGuardianCalls` and `EnableIntelligentGuardianMessages` to `true` to enable monitoring; set both to `false` to fully disable Guardian.

**Next steps:**
- Confirm the change took effect — `GET /v1.0/subscribers/guardian-features`
- Link a parent and child for supervision — `POST /v1.0/subscribers/guardians/relation`
- Create a message filter — `POST /v1.0/subscribers/message-filter`
- Create a call filter — `POST /v1.0/subscribers/call-filter`



# Create Call Filter
Source: https://docs.telegent.com/api-reference/subscribers/create-call-filter

/api-reference/openapi.json post /v1.0/subscribers/call-filter
Create a new call filter that controls who can place or receive calls for a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing Subscriber (`TSUID-`) — `POST /v1.0/subscribers/create`
- AI Guardian enabled for calls — `POST /v1.0/subscribers/guardian-features`
- (Optional) For age-preset modes (`CHILD`, `TEENAGER`, `ADOLESCENT`): a parent-child guardian relation — `POST /v1.0/subscribers/guardians/relation`

**What this does:** Creates a call filter and returns a `CallFilterId` (`CFID-`). Choose mode: `WHITELIST` (only allowed numbers ring through), `BLACKLIST` (block listed numbers, allow others), or an age preset that applies Telegent-recommended defaults. Configure transcription, keyword alerts, action on detection (warn/terminate/notify), and time-based restrictions. The filter takes effect immediately.

**Next steps:**
- Verify it was saved — `GET /v1.0/subscribers/call-filter`
- Add allowed callers — `POST /v1.0/subscribers/call-filter/allowed-numbers/add`
- Add blocked callers — `POST /v1.0/subscribers/call-filter/blocked-numbers/add`
- Review keyword rules — `GET /v1.0/subscribers/call-filter/keywords`
- Update later — `POST /v1.0/subscribers/call-filter/update`



# Create Guardian Relation
Source: https://docs.telegent.com/api-reference/subscribers/create-guardian-relation

/api-reference/openapi.json post /v1.0/subscribers/guardians/relation
Link a parent (guardian) subscriber to a child subscriber so the parent can supervise the child's communications.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Both subscribers must exist (`TSUID-`) — `POST /v1.0/subscribers/create`
- AI Guardian must be enabled on both subscribers — `POST /v1.0/subscribers/guardian-features`

**What this does:** Creates a one-way parent-to-child link. The parent gains the ability to receive filter notifications, manage filters on behalf of the child, and use age-preset modes (`CHILD`, `TEENAGER`, `ADOLESCENT`) on the child's call filters.

**Next steps:**
- Verify the link — `GET /v1.0/subscribers/guardians/relation/parent` (lookup by parent) or `GET /v1.0/subscribers/guardians/relation/child` (lookup by child)
- Create message and call filters on the child — `POST /v1.0/subscribers/message-filter`, `POST /v1.0/subscribers/call-filter`
- Remove the link later — `POST /v1.0/subscribers/guardians/relation/delete`



# Create Message Filter
Source: https://docs.telegent.com/api-reference/subscribers/create-message-filter

/api-reference/openapi.json post /v1.0/subscribers/message-filter
Create a new message filter that controls what messages a subscriber can send and receive.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing Subscriber (`TSUID-`) — `POST /v1.0/subscribers/create`
- AI Guardian enabled for messages — `POST /v1.0/subscribers/guardian-features`

**What this does:** Creates a filter and returns a `MessageFilterId` (`MFID-`). The filter applies to the specified phone number. Configure mode (`ACTIVE`/`MONITOR_ONLY`/`INACTIVE`), allowed/blocked contacts, keyword rules, and restrictions on links, media, and unknown numbers. The filter takes effect immediately.

**Next steps:**
- Verify it was saved — `GET /v1.0/subscribers/message-filter`
- Add trusted contacts that bypass filtering — `POST /v1.0/subscribers/message-filter/allowed-contacts/add`
- Add senders to silently drop — `POST /v1.0/subscribers/message-filter/blocked-contacts/add`
- Review configured keywords — `GET /v1.0/subscribers/message-filter/keywords`
- Update later — `POST /v1.0/subscribers/message-filter/update`



# Create Subscriber
Source: https://docs.telegent.com/api-reference/subscribers/create-subscriber

/api-reference/openapi.json post /v1.0/subscribers/create
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Account ID (AID) — provided by your Telegent representative

---

Create a new subscriber with name, email, phone numbers, role, and password. Returns the newly created subscriber details.

**What this does:** Returns the new subscriber's `SubscriberId` (`TSUID-`) and full profile. The `TSUID-` is required for creating subscriptions, assigning numbers, and configuring AI Guardian. Store it for all subsequent subscriber-related calls.

**Next steps:**
- Assign a subscription — `POST /v1.0/subscriptions`
- Provision a number — `POST /v1.0/numbers/provision`



# Delete Call Filter
Source: https://docs.telegent.com/api-reference/subscribers/delete-call-filter

/api-reference/openapi.json post /v1.0/subscribers/call-filter/delete
Permanently remove a call filter from a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing `CallFilterId` (`CFID-`)

**What this does:** Permanently deletes the filter and all its associated allowed/blocked numbers and keyword rules. Calls will no longer be filtered after this call. **This cannot be undone.**

**Next steps:**
- Confirm removal — `GET /v1.0/subscribers/call-filter`
- Create a new filter — `POST /v1.0/subscribers/call-filter`



# Delete Message Filter
Source: https://docs.telegent.com/api-reference/subscribers/delete-message-filter

/api-reference/openapi.json post /v1.0/subscribers/message-filter/delete
Permanently remove a message filter from a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing `MessageFilterId` (`MFID-`)

**What this does:** Permanently deletes the filter and all its associated contacts and keyword rules. Messages will be delivered without any filtering after this call. **This cannot be undone.**

**Tip:** If you only want to pause filtering without losing your settings, use `POST /v1.0/subscribers/message-filter/update` and set `FilterMode` to `INACTIVE` instead.

**Next steps:**
- Confirm removal — `GET /v1.0/subscribers/message-filter`
- Create a new filter — `POST /v1.0/subscribers/message-filter`



# Get Allowed Contacts
Source: https://docs.telegent.com/api-reference/subscribers/get-allowed-contacts

/api-reference/openapi.json get /v1.0/subscribers/message-filter/allowed-contacts
View the list of phone numbers that bypass content filtering on a message filter.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `MessageFilterId` (`MFID-`) — find one with `GET /v1.0/subscribers/message-filter`

**What this does:** Returns every phone number on the allowed list. Messages from these contacts skip keyword checks, link blocking, and media restrictions — they are always delivered.

**Next steps:**
- Add a new trusted contact — `POST /v1.0/subscribers/message-filter/allowed-contacts/add`
- Remove someone from the list — `POST /v1.0/subscribers/message-filter/allowed-contacts/remove`
- View the blocked side — `GET /v1.0/subscribers/message-filter/blocked-contacts`



# Get Allowed Numbers
Source: https://docs.telegent.com/api-reference/subscribers/get-allowed-numbers

/api-reference/openapi.json get /v1.0/subscribers/call-filter/allowed-numbers
View the list of phone numbers allowed to call a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `CallFilterId` (`CFID-`) — find one with `GET /v1.0/subscribers/call-filter`

**What this does:** Returns every phone number on the allowed list. In `WHITELIST` mode, only these numbers can ring through to the subscriber — all other callers are blocked or sent to voicemail.

**Next steps:**
- Add a new trusted caller — `POST /v1.0/subscribers/call-filter/allowed-numbers/add`
- Remove someone from the list — `POST /v1.0/subscribers/call-filter/allowed-numbers/remove`
- View the blocked side — `GET /v1.0/subscribers/call-filter/blocked-numbers`



# Get Blocked Contacts
Source: https://docs.telegent.com/api-reference/subscribers/get-blocked-contacts

/api-reference/openapi.json get /v1.0/subscribers/message-filter/blocked-contacts
View the list of phone numbers blocked from messaging a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `MessageFilterId` (`MFID-`)

**What this does:** Returns every phone number currently blocked. Messages from these numbers are silently dropped — the sender receives no error or notification.

**Next steps:**
- Block a new sender — `POST /v1.0/subscribers/message-filter/blocked-contacts/add`
- Unblock someone — `POST /v1.0/subscribers/message-filter/blocked-contacts/remove`
- View the allowed side — `GET /v1.0/subscribers/message-filter/allowed-contacts`



# Get Blocked Numbers
Source: https://docs.telegent.com/api-reference/subscribers/get-blocked-numbers

/api-reference/openapi.json get /v1.0/subscribers/call-filter/blocked-numbers
View the list of phone numbers blocked from calling a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `CallFilterId` (`CFID-`)

**What this does:** Returns every phone number currently blocked. Calls from blocked numbers are rejected or silently dropped — the caller may hear a disconnect tone or nothing at all.

**Next steps:**
- Block a new caller — `POST /v1.0/subscribers/call-filter/blocked-numbers/add`
- Unblock someone — `POST /v1.0/subscribers/call-filter/blocked-numbers/remove`
- View the allowed side — `GET /v1.0/subscribers/call-filter/allowed-numbers`



# Get Call Filter Keywords
Source: https://docs.telegent.com/api-reference/subscribers/get-call-filter-keywords

/api-reference/openapi.json get /v1.0/subscribers/call-filter/keywords
View the keyword monitoring rules attached to a call filter.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `CallFilterId` (`CFID-`)
- Call transcription must be enabled on the filter for keywords to take effect at runtime — set `EnableTranscription` to `true` via `POST /v1.0/subscribers/call-filter/update`

**What this does:** Returns the keyword filter configuration: `CustomKeywords` (your own words), `SystemKeywords` (Telegent-provided categories like Profanity, Threats), and `SeverityMap` (risk level per term: `HIGH`/`MEDIUM`/`LOW`). When transcription is on, calls are analyzed against these keywords and the configured `TranscriptionAction` is taken when a match is found.

**Next steps:**
- Add or change keywords — `POST /v1.0/subscribers/call-filter/update` (use the `KeywordFilter` field)
- See the rest of the filter — `GET /v1.0/subscribers/call-filter`



# Get Call Filters
Source: https://docs.telegent.com/api-reference/subscribers/get-call-filters

/api-reference/openapi.json get /v1.0/subscribers/call-filter
List the call filters configured on a subscriber or phone number.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID or phone number to filter by (otherwise returns all)

**What this does:** Returns the full configuration of each matching filter — mode, allowed/blocked number lists, transcription settings, and keyword alert rules. Use this to audit a subscriber's call controls or to find the `CallFilterId` (`CFID-`) you need for subsequent calls.

**Next steps:**
- Inspect allowed/blocked lists in detail — `GET /v1.0/subscribers/call-filter/allowed-numbers`, `GET /v1.0/subscribers/call-filter/blocked-numbers`
- View keyword rules — `GET /v1.0/subscribers/call-filter/keywords`
- Modify a filter — `POST /v1.0/subscribers/call-filter/update`
- Remove a filter — `POST /v1.0/subscribers/call-filter/delete`



# Get Guardian Features
Source: https://docs.telegent.com/api-reference/subscribers/get-guardian-features

/api-reference/openapi.json get /v1.0/subscribers/guardian-features
Check whether AI Guardian is currently enabled for a subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing Subscriber (`TSUID-`)

**What this does:** Returns the current `EnableIntelligentGuardianCalls` and `EnableIntelligentGuardianMessages` flags for the subscriber. Use this after toggling features to confirm the change took effect before applying filters or guardian relationships.

**Next steps:**
- Change the settings — `POST /v1.0/subscribers/guardian-features`
- View existing filters — `GET /v1.0/subscribers/message-filter` or `GET /v1.0/subscribers/call-filter`



# Get Guardian Relation Child
Source: https://docs.telegent.com/api-reference/subscribers/get-guardian-relation-child

/api-reference/openapi.json get /v1.0/subscribers/guardians/relation/child
List every parent (guardian) linked to a specific child subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Child Subscriber ID (`TSUID-`)

**What this does:** Returns all guardian relations where the supplied subscriber is the child. Use this to confirm which guardians have oversight over a particular child account.

**Next steps:**
- Look up the inverse (a parent's children) — `GET /v1.0/subscribers/guardians/relation/parent`
- Remove a relation — `POST /v1.0/subscribers/guardians/relation/delete`
- Add a new relation — `POST /v1.0/subscribers/guardians/relation`



# Get Guardian Relation Parent
Source: https://docs.telegent.com/api-reference/subscribers/get-guardian-relation-parent

/api-reference/openapi.json get /v1.0/subscribers/guardians/relation/parent
List every child subscriber that a parent is currently linked to.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Parent Subscriber ID (`TSUID-`)

**What this does:** Returns all guardian relations where the supplied subscriber is the parent. Use this to verify a relationship was set up correctly or to audit which children a guardian oversees.

**Next steps:**
- Look up the inverse (children's guardians) — `GET /v1.0/subscribers/guardians/relation/child`
- Remove a relation — `POST /v1.0/subscribers/guardians/relation/delete`
- Add a new relation — `POST /v1.0/subscribers/guardians/relation`



# Get Message Filter Keywords
Source: https://docs.telegent.com/api-reference/subscribers/get-message-filter-keywords

/api-reference/openapi.json get /v1.0/subscribers/message-filter/keywords
View the keyword rules attached to a message filter.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `MessageFilterId` (`MFID-`)

**What this does:** Returns the keyword filter configuration: `CustomKeywords` (your own words), `SystemKeywords` (Telegent-provided categories like Profanity, Violence), and `SeverityMap` (risk level per term: `HIGH`/`MEDIUM`/`LOW`). Use this to audit exactly what words will trigger filter actions.

**Next steps:**
- Add or change keywords — `POST /v1.0/subscribers/message-filter/update` (use the `KeywordFilter` field)
- See the rest of the filter — `GET /v1.0/subscribers/message-filter`



# Get Message Filters
Source: https://docs.telegent.com/api-reference/subscribers/get-message-filters

/api-reference/openapi.json get /v1.0/subscribers/message-filter
List the message filters configured on a subscriber or phone number.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID or phone number to filter by (otherwise returns all)

**What this does:** Returns the full configuration of each matching filter — mode, allowed/blocked contacts, keyword rules, and restrictions on links/media/unknown numbers. Use this to audit a subscriber's messaging controls or to find the `MessageFilterId` (`MFID-`) you need for subsequent calls.

**Next steps:**
- Inspect allowed/blocked lists in detail — `GET /v1.0/subscribers/message-filter/allowed-contacts`, `GET /v1.0/subscribers/message-filter/blocked-contacts`
- View keyword rules — `GET /v1.0/subscribers/message-filter/keywords`
- Modify a filter — `POST /v1.0/subscribers/message-filter/update`
- Remove a filter — `POST /v1.0/subscribers/message-filter/delete`



# Get Subscriber Details
Source: https://docs.telegent.com/api-reference/subscribers/get-subscriber-details

/api-reference/openapi.json get /v1.0/subscribers/get
Retrieve detailed information about a specific subscriber including name, email, phone numbers, role, and associated account details.

**What this does:** Returns the subscriber's profile including name, email, role, assigned phone numbers, account ID, and status. Use this to confirm a subscriber's configuration or retrieve the `TSUID-` for use in subscription and AI Guardian calls.

**Next steps:**
- Update subscriber — `POST /v1.0/subscribers/update`
- Assign a subscription — `POST /v1.0/subscriptions`
- Enable AI Guardian — `POST /v1.0/subscribers/guardian-features`



# Remove Allowed Contacts
Source: https://docs.telegent.com/api-reference/subscribers/remove-allowed-contacts

/api-reference/openapi.json post /v1.0/subscribers/message-filter/allowed-contacts/remove
Remove phone numbers from the allowed contacts list.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `MessageFilterId` (`MFID-`)
- Numbers must currently be on the allowed list — confirm with `GET /v1.0/subscribers/message-filter/allowed-contacts`

**What this does:** Removes one or more phone numbers from the allowed list. After removal, messages from those contacts go through the normal filter pipeline (keyword checks, link blocking, etc.).

**Next steps:**
- Verify the removal — `GET /v1.0/subscribers/message-filter/allowed-contacts`
- Block the contact instead — `POST /v1.0/subscribers/message-filter/blocked-contacts/add`



# Remove Allowed Numbers
Source: https://docs.telegent.com/api-reference/subscribers/remove-allowed-numbers

/api-reference/openapi.json post /v1.0/subscribers/call-filter/allowed-numbers/remove
Remove phone numbers from the allowed callers list.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `CallFilterId` (`CFID-`)
- Numbers must currently be on the allowed list — confirm with `GET /v1.0/subscribers/call-filter/allowed-numbers`

**What this does:** Removes one or more phone numbers from the allowed list. In `WHITELIST` mode, calls from those numbers will no longer ring through and are treated like any other non-allowed caller.

**Next steps:**
- Verify the removal — `GET /v1.0/subscribers/call-filter/allowed-numbers`
- Block the caller instead — `POST /v1.0/subscribers/call-filter/blocked-numbers/add`



# Remove Blocked Contacts
Source: https://docs.telegent.com/api-reference/subscribers/remove-blocked-contacts

/api-reference/openapi.json post /v1.0/subscribers/message-filter/blocked-contacts/remove
Unblock phone numbers so their messages start being delivered again.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `MessageFilterId` (`MFID-`)
- Numbers must currently be on the blocked list — confirm with `GET /v1.0/subscribers/message-filter/blocked-contacts`

**What this does:** Removes one or more phone numbers from the blocked list. After removal, messages from those contacts go through the normal filter pipeline and are delivered if they pass the rules.

**Next steps:**
- Verify the removal — `GET /v1.0/subscribers/message-filter/blocked-contacts`
- Add to allowed instead — `POST /v1.0/subscribers/message-filter/allowed-contacts/add`



# Remove Blocked Numbers
Source: https://docs.telegent.com/api-reference/subscribers/remove-blocked-numbers

/api-reference/openapi.json post /v1.0/subscribers/call-filter/blocked-numbers/remove
Unblock phone numbers so they can call the subscriber again.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- Subscriber ID and `CallFilterId` (`CFID-`)
- Numbers must currently be on the blocked list — confirm with `GET /v1.0/subscribers/call-filter/blocked-numbers`

**What this does:** Removes one or more phone numbers from the blocked list. After removal, calls from those numbers are handled normally according to the active filter mode (e.g., they will ring through in `BLACKLIST` mode unless they're caught by another rule).

**Next steps:**
- Verify the removal — `GET /v1.0/subscribers/call-filter/blocked-numbers`
- Add to allowed instead — `POST /v1.0/subscribers/call-filter/allowed-numbers/add`



# Remove Guardian Relation
Source: https://docs.telegent.com/api-reference/subscribers/remove-guardian-relation

/api-reference/openapi.json post /v1.0/subscribers/guardians/relation/delete
Unlink a parent (guardian) from a child subscriber.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing parent-child relation

**What this does:** Removes the guardian relation only. The subscribers themselves and their individual filters remain untouched. After removal, the parent will no longer receive filter notifications or be able to manage the child's filters.

**Next steps:**
- Confirm removal — `GET /v1.0/subscribers/guardians/relation/parent`
- Re-establish the link later — `POST /v1.0/subscribers/guardians/relation`



# Transfer Subscriber
Source: https://docs.telegent.com/api-reference/subscribers/transfer-subscriber

/api-reference/openapi.json post /v1.0/subscribers/transfer
Transfer a subscriber from one account to another. Requires both origin and destination account IDs.

**What this does:** Returns a confirmation that the subscriber has been moved to the target account. All subscriptions and number assignments are preserved. Use this in reseller workflows when a subscriber needs to move between managed accounts.

**Next steps:**
- Confirm new account association — `GET /v1.0/subscribers/get`



# Update Call Filter
Source: https://docs.telegent.com/api-reference/subscribers/update-call-filter

/api-reference/openapi.json post /v1.0/subscribers/call-filter/update
Modify an existing call filter without deleting and recreating it.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing `CallFilterId` (`CFID-`) — find one with `GET /v1.0/subscribers/call-filter`

**What this does:** Replaces the configuration of the specified filter. Use this to change modes (e.g., `BLACKLIST` → `WHITELIST`), update allowed/blocked number lists, toggle transcription, change keyword alerts, or adjust restrictions like blocking unknown or international numbers. Note: the Update endpoint only accepts `WHITELIST` and `BLACKLIST` modes — age presets must be set on creation.

**Next steps:**
- Verify the change — `GET /v1.0/subscribers/call-filter`
- Pause without deleting — use `POST /v1.0/subscribers/call-filter/update` with `EnableTranscription` off and an empty rules set, or delete the filter
- Permanently remove — `POST /v1.0/subscribers/call-filter/delete`



# Update Message Filter
Source: https://docs.telegent.com/api-reference/subscribers/update-message-filter

/api-reference/openapi.json post /v1.0/subscribers/message-filter/update
Modify an existing message filter without deleting and recreating it.

**Prerequisites:**
- Bearer token — `POST /v1.0/oauth2/tokens`
- An existing `MessageFilterId` (`MFID-`) — find one with `GET /v1.0/subscribers/message-filter`

**What this does:** Replaces the configuration of the specified filter. Use this to switch modes (e.g., `MONITOR_ONLY` → `ACTIVE` to start enforcing rules), update contact lists, adjust keyword settings, or toggle link/media/unknown-number restrictions. Changes take effect immediately.

**Next steps:**
- Verify the change — `GET /v1.0/subscribers/message-filter`
- Pause without deleting — set `FilterMode` to `INACTIVE` and call this endpoint again
- Permanently remove — `POST /v1.0/subscribers/message-filter/delete`



# Update Subscriber
Source: https://docs.telegent.com/api-reference/subscribers/update-subscriber

/api-reference/openapi.json post /v1.0/subscribers/update
Update an existing subscriber's information including name, phone numbers, role, and password.

**What this does:** Returns the updated subscriber record. Only the fields you send are changed; omitted fields retain their current values.

**Next steps:**
- Confirm the update — `GET /v1.0/subscribers/get`



# Create Feature
Source: https://docs.telegent.com/api-reference/subscriptions/create-feature

/api-reference/openapi.json post /v1.0/subscriptions/features/add
Create a new feature that can be assigned to subscriptions. Features represent optional add-on capabilities such as international roaming, VoIP, SMS bundles, or data speed tiers.

**What this does:** Returns the new `FeatureId` and full feature record. After creating a feature, assign it to subscriptions using `POST /v1.0/subscriptions/features/assignments/add`.

**Next steps:**
- Assign to a subscription — `POST /v1.0/subscriptions/features/assignments/add`
- View feature details — `GET /v1.0/subscriptions/features`



# Create Feature Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/create-feature-assignment

/api-reference/openapi.json post /v1.0/subscriptions/features/assignments/add
Assign an existing feature to a subscription, enabling that subscription to use the feature's capability.

**What this does:** Returns the new `FeatureAssignmentId` and assignment record. A feature can be assigned to multiple subscriptions; each assignment is tracked independently.

**Next steps:**
- View all assignments for this feature — `GET /v1.0/subscriptions/features/assignments`
- Remove the assignment — `POST /v1.0/subscriptions/features/assignments/delete`



# Create Subscription
Source: https://docs.telegent.com/api-reference/subscriptions/create-subscription

/api-reference/openapi.json post /v1.0/subscriptions
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Package ID (PID) — `POST /v1.0/packages`
- **Required:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create`

---

Link a subscriber to a package to grant them access to a set of services. A subscription ties together a subscriber (TSUID), a package (PID), a phone number (TNID), and a SIM card (ICCID) — all four are required. The subscriber, package, and phone number must all exist before creating the subscription. Active subscriptions determine what services and capabilities are available to the subscriber.

**What this does:** Returns the new `SubscriptionId` (`SUB-`) and full subscription record. Creating a subscription links the subscriber to a package, granting them the services and capabilities defined in that package.

**Next steps:**
- Confirm the subscription — `GET /v1.0/subscriptions`
- View the package contents — `GET /v1.0/packages/items`



# Create Threshold
Source: https://docs.telegent.com/api-reference/subscriptions/create-threshold

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/add
Create a new usage threshold that can be assigned to subscriptions. A threshold specifies a resource type, a trigger amount, and the action to take when that amount is reached — such as sending an alert or pausing service.

**What this does:** Returns the new `ThresholdId` and full threshold record. After creating a threshold, assign it to one or more subscriptions using `POST /v1.0/subscriptions/thresholds/assignments/add`.

**Next steps:**
- Assign the threshold to a subscription — `POST /v1.0/subscriptions/thresholds/assignments/add`
- View threshold details — `GET /v1.0/subscriptions/thresholds`



# Create Threshold Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/create-threshold-assignment

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/assignments/add
Assign an existing threshold to a subscription. Once assigned, the threshold monitors that subscription's resource usage and fires its configured action when the limit is reached.

**What this does:** Returns the new `ThresholdAssignmentId` and assignment record. A threshold can be assigned to multiple subscriptions; each assignment is tracked independently.

**Next steps:**
- View all assignments for this threshold — `GET /v1.0/subscriptions/thresholds/assignments`
- Remove the assignment — `POST /v1.0/subscriptions/thresholds/assignments/delete`



# Delete Feature
Source: https://docs.telegent.com/api-reference/subscriptions/delete-feature

/api-reference/openapi.json post /v1.0/subscriptions/features/delete
Permanently delete a feature by its `FeatureId`. Deleting a feature also removes all of its assignments from associated subscriptions.

**What this does:** Returns a deletion confirmation. Subscriptions previously assigned this feature will lose access to the capability it provided.

**Next steps:**
- Create a replacement feature — `POST /v1.0/subscriptions/features/add`



# Delete Feature Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/delete-feature-assignment

/api-reference/openapi.json post /v1.0/subscriptions/features/assignments/delete
Remove a feature assignment by its `FeatureAssignmentId`. This unlinks the feature from the associated subscription; the feature itself is not deleted.

**What this does:** Returns a deletion confirmation. The subscription will no longer have access to the capability provided by this feature.

**Next steps:**
- Re-assign the feature — `POST /v1.0/subscriptions/features/assignments/add`



# Delete Subscription
Source: https://docs.telegent.com/api-reference/subscriptions/delete-subscription

/api-reference/openapi.json post /v1.0/subscriptions/delete
Permanently delete a subscription by its SubscriptionId. This removes the subscriber's access to the associated package.

**What this does:** Returns a deletion confirmation. Deleting a subscription removes the subscriber's access to the associated package and its services. The subscriber and phone number are not deleted.

**Next steps:**
- Create a new subscription — `POST /v1.0/subscriptions`



# Delete Threshold
Source: https://docs.telegent.com/api-reference/subscriptions/delete-threshold

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/delete
Permanently delete a threshold by its `ThresholdId`. Deleting a threshold also removes all of its assignments from associated subscriptions.

**What this does:** Returns a deletion confirmation. Any subscriptions previously assigned this threshold will no longer have a threshold applied.

**Next steps:**
- Create a replacement threshold — `POST /v1.0/subscriptions/thresholds/add`



# Delete Threshold Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/delete-threshold-assignment

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/assignments/delete
Remove a threshold assignment by its `ThresholdAssignmentId`. This unlinks the threshold from the associated subscription; the threshold itself is not deleted.

**What this does:** Returns a deletion confirmation. The subscription will no longer have this threshold applied to its usage.

**Next steps:**
- Re-assign the threshold — `POST /v1.0/subscriptions/thresholds/assignments/add`



# Get Feature
Source: https://docs.telegent.com/api-reference/subscriptions/get-feature

/api-reference/openapi.json get /v1.0/subscriptions/features
Retrieve the details of a specific feature by its `FeatureId`. Features represent add-on capabilities (such as roaming, VoIP, or data boosters) that can be assigned to subscriptions.

**What this does:** Returns the feature record including its name, type, and description. Use the `FeatureId` query parameter to look up a single feature.

**Next steps:**
- Create a feature — `POST /v1.0/subscriptions/features/add`
- Assign it to a subscription — `POST /v1.0/subscriptions/features/assignments/add`



# Get Feature Assignments
Source: https://docs.telegent.com/api-reference/subscriptions/get-feature-assignments

/api-reference/openapi.json get /v1.0/subscriptions/features/assignments
Retrieve all assignments for a given feature. Each assignment links a feature to a subscription, enabling that subscription to use the feature's capability.

**What this does:** Returns a list of assignment records for the specified `FeatureId`, including the linked `SubscriptionId` and assignment status.

**Next steps:**
- Add an assignment — `POST /v1.0/subscriptions/features/assignments/add`
- Remove an assignment — `POST /v1.0/subscriptions/features/assignments/delete`



# Get Subscription Details
Source: https://docs.telegent.com/api-reference/subscriptions/get-subscription-details

/api-reference/openapi.json get /v1.0/subscriptions
Retrieve detailed information about a specific subscription by its SubscriptionId. Returns subscriber, package, phone number, and status information.

**What this does:** Returns the subscription record including the linked subscriber (`TSUID-`), package (`PID-`), phone number (`NID-`), ICCID, subscription type, and active status. Use this to confirm a subscriber's current plan or retrieve the `SUB-` ID for updates.

**Next steps:**
- Update subscription — `POST /v1.0/subscriptions/update`
- Delete subscription — `POST /v1.0/subscriptions/delete`



# Get Threshold
Source: https://docs.telegent.com/api-reference/subscriptions/get-threshold

/api-reference/openapi.json get /v1.0/subscriptions/thresholds
Retrieve the details of a specific usage threshold by its `ThresholdId`. Thresholds define a resource limit (data, SMS, or voice) and the action to take when that limit is reached.

**What this does:** Returns the threshold record including its name, type, amount, unit, and action. Use the `ThresholdId` query parameter to look up a single threshold.

**Next steps:**
- Create a threshold — `POST /v1.0/subscriptions/thresholds/add`
- Assign it to a subscription — `POST /v1.0/subscriptions/thresholds/assignments/add`



# Get Threshold Assignments
Source: https://docs.telegent.com/api-reference/subscriptions/get-threshold-assignments

/api-reference/openapi.json get /v1.0/subscriptions/thresholds/assignments
Retrieve all assignments for a given threshold. Each assignment links a threshold to a subscription, enabling the threshold to trigger on that subscription's usage.

**What this does:** Returns a list of assignment records for the specified `ThresholdId`, including the linked `SubscriptionId` and assignment status.

**Next steps:**
- Add an assignment — `POST /v1.0/subscriptions/thresholds/assignments/add`
- Remove an assignment — `POST /v1.0/subscriptions/thresholds/assignments/delete`



# Update Feature
Source: https://docs.telegent.com/api-reference/subscriptions/update-feature

/api-reference/openapi.json post /v1.0/subscriptions/features/update
Update the details of an existing feature. Only the fields you include in the request body are changed; omitted fields retain their current values.

**What this does:** Returns the updated feature record. Changes apply to all subscriptions currently assigned this feature.

**Next steps:**
- Confirm the update — `GET /v1.0/subscriptions/features`
- View assignments — `GET /v1.0/subscriptions/features/assignments`



# Update Feature Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/update-feature-assignment

/api-reference/openapi.json post /v1.0/subscriptions/features/assignments/update
Update an existing feature assignment — for example, to re-point it to a different subscription or feature. Only included fields are changed.

**What this does:** Returns the updated assignment record.

**Next steps:**
- Confirm the update — `GET /v1.0/subscriptions/features/assignments`



# Update Subscription
Source: https://docs.telegent.com/api-reference/subscriptions/update-subscription

/api-reference/openapi.json post /v1.0/subscriptions/update
Update an existing subscription's information including subscriber, package, phone number, or SIM card associations.

**What this does:** Returns the updated subscription record. Only fields you send are changed; omitted fields retain their current values. Use this to swap a subscriber's package or update the associated phone number.

**Next steps:**
- Confirm the update — `GET /v1.0/subscriptions`



# Update Threshold
Source: https://docs.telegent.com/api-reference/subscriptions/update-threshold

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/update
Update the configuration of an existing threshold. Only the fields you include in the request body are changed; omitted fields retain their current values.

**What this does:** Returns the updated threshold record. Changes take effect on all subscriptions already assigned this threshold.

**Next steps:**
- Confirm the update — `GET /v1.0/subscriptions/thresholds`
- View assignments — `GET /v1.0/subscriptions/thresholds/assignments`



# Update Threshold Assignment
Source: https://docs.telegent.com/api-reference/subscriptions/update-threshold-assignment

/api-reference/openapi.json post /v1.0/subscriptions/thresholds/assignments/update
Update an existing threshold assignment — for example, to re-point it to a different subscription or threshold. Only included fields are changed.

**What this does:** Returns the updated assignment record.

**Next steps:**
- Confirm the update — `GET /v1.0/subscriptions/thresholds/assignments`



# Create Voice Route
Source: https://docs.telegent.com/api-reference/voice/create-voice-route

/api-reference/openapi.json post /v1.0/voice/routes
Create a new voice route to define how inbound calls are handled for numbers assigned to it. Routes support SIP trunk termination, webhook-based IVR, forwarding, and workgroup distribution. Each route returns a unique CRID (Call Route ID) used when provisioning or updating numbers. Workgroups and Schedules can be attached to a route after creation to enable ring groups and business-hours routing.

**What this does:** Returns the new route's `CallRouteId` (`CRID-`). Store this ID — it is required when provisioning numbers with voice enabled. Configure SIP trunk IPs, forwarding URLs, or workgroups after creation using the update endpoint.

**Next steps:**
- Assign the route to a number — `POST /v1.0/numbers/provision`
- Add a workgroup — `POST /v1.0/workgroups`



# Delete Voice Route
Source: https://docs.telegent.com/api-reference/voice/delete-voice-route

/api-reference/openapi.json post /v1.0/voice/routes/delete
Permanently delete a voice route from your account. Phone numbers using this route will need to be reassigned to a different route before deletion. This action cannot be undone.

**What this does:** Returns a deletion confirmation. Numbers assigned to this route will lose voice routing — reassign them to a different route before deleting to avoid service disruption.

**Next steps:**
- Create a replacement route — `POST /v1.0/voice/routes`
- Update affected numbers — `POST /v1.0/numbers/update`



# Get Voice Route Details
Source: https://docs.telegent.com/api-reference/voice/get-voice-route-details

/api-reference/openapi.json get /v1.0/voice/routes
Retrieve detailed configuration for a specific voice route using its CRID. Returns SIP trunk configuration, forwarding rules, IVR settings, workgroup assignments, and schedule information.

**What this does:** Returns the full route configuration including route type, SIP trunk settings, webhook URLs, authentication, and workgroup associations. Use this to confirm route settings or retrieve the `CRID-` for use in provisioning.

**Next steps:**
- Update route — `POST /v1.0/voice/routes/update`
- Provision a number using this route — `POST /v1.0/numbers/provision`



# Update Voice Route
Source: https://docs.telegent.com/api-reference/voice/update-voice-route

/api-reference/openapi.json post /v1.0/voice/routes/update
Update an existing voice route's configuration including SIP trunk settings, forwarding numbers, IVR menus, and workgroup assignments. Changes apply immediately to all numbers using this route.

**What this does:** Returns the updated route configuration. Only fields you send are changed. Changes apply immediately to all numbers using this route.

**Next steps:**
- Confirm the update — `GET /v1.0/voice/routes`
- View numbers using this route — `GET /v1.0/numbers/inventory`



# Activate Voicemail
Source: https://docs.telegent.com/api-reference/voicemail/activate-voicemail

/api-reference/openapi.json post /v1.0/numbers/voicemail/activate
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Provisioned phone number — `POST /v1.0/numbers/provision`

---

Activate voicemail for a phone number. Set a PIN, notification email, and subscriber name. Once activated, unanswered calls to this number will be directed to voicemail.

**What this does:** Enables voicemail on the number and returns a confirmation. Once activated, unanswered calls are captured as voicemail and a notification is sent to the configured email. The PIN is required to retrieve messages.

**Next steps:**
- Confirm voicemail is active — `POST /v1.0/numbers/voicemail/info`
- Update settings — `POST /v1.0/numbers/voicemail/update`



# Delete Voicemail
Source: https://docs.telegent.com/api-reference/voicemail/delete-voicemail

/api-reference/openapi.json post /v1.0/numbers/voicemail/delete
Remove voicemail configuration from a phone number. After deletion, the number will no longer have voicemail enabled and unanswered calls will not be captured.

**What this does:** Removes voicemail from the number and returns a confirmation. Existing voicemail messages are deleted. Unanswered calls will no longer be captured after this call.

**Next steps:**
- Reactivate voicemail — `POST /v1.0/numbers/voicemail/activate`



# Get Voicemail Info
Source: https://docs.telegent.com/api-reference/voicemail/get-voicemail-info

/api-reference/openapi.json post /v1.0/numbers/voicemail/info
Retrieve current voicemail settings and configuration details for a specific phone number, including PIN status, notification email, and account association.

**What this does:** Returns whether voicemail is active on the number, the notification email, subscriber name, and PIN status. Use this to confirm voicemail is configured before troubleshooting missed-call behaviour.

**Next steps:**
- Activate voicemail — `POST /v1.0/numbers/voicemail/activate`
- Update settings — `POST /v1.0/numbers/voicemail/update`



# Update Voicemail
Source: https://docs.telegent.com/api-reference/voicemail/update-voicemail

/api-reference/openapi.json post /v1.0/numbers/voicemail/update
Update voicemail settings for a phone number including PIN, notification email, and subscriber name details.

**What this does:** Returns confirmation that the voicemail configuration has been updated. Only the fields you send are changed; omitted fields retain their current values.

**Next steps:**
- Confirm the update — `POST /v1.0/numbers/voicemail/info`



# Create Webhook
Source: https://docs.telegent.com/api-reference/webhooks/create-webhook

/api-reference/openapi.json post /v1.0/webhook/create
Register a webhook endpoint to receive event notifications from your Telegent account. Use this to subscribe to events such as order updates, message status changes, or other platform activity, with optional Basic or Token authentication for callback security.

**Available subscribable events:** `Order_Update`, `New_Sms`, `Call_Completed`, `Call_On_Hold`, `Call_Recording`, `Call_In_Progress`, `Call_Ringing`

After you register, Telegent POSTs a JSON payload to your `Url` each time a subscribed event fires. See [Webhook Event Payloads](/resources/reference#43-receiving-events--webhook-payloads) for the delivered body shape per event type.



# Delete Webhook
Source: https://docs.telegent.com/api-reference/webhooks/delete-webhook

/api-reference/openapi.json post /v1.0/webhook/delete
Permanently deletes a webhook subscription, stopping all future event deliveries to its configured URL. Use this to remove webhooks that are no longer needed or to clean up obsolete event subscriptions on an account.



# Get Webhook
Source: https://docs.telegent.com/api-reference/webhooks/get-webhook

/api-reference/openapi.json get /v1.0/webhook
Retrieves the full configuration of a single webhook by its `WebhookId`, including the target URL, HTTP method, data format, authentication details, and subscribed events. Use this to inspect or audit an existing webhook before updating or deleting it.

**What this returns:** A `Webhook_Result` object containing the `WebhookUrl`, `Method`, `DataFormat`, `AuthenticationType` and credentials, `SubscribedEvents`, and the webhook's `Active` status.

**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** `WebhookId` from a prior `POST /v1.0/webhook` call



# Update Webhook
Source: https://docs.telegent.com/api-reference/webhooks/update-webhook

/api-reference/openapi.json post /v1.0/webhook/update
Update the configuration of an existing webhook, including its destination URL, HTTP method, authentication credentials, and the list of subscribed events. Use this to rotate credentials, change the callback endpoint, or modify which events trigger notifications without recreating the webhook.



# Create Workgroup
Source: https://docs.telegent.com/api-reference/workgroups/create-workgroup

/api-reference/openapi.json post /v1.0/workgroups
**Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Voice Route ID (CRID) — `POST /v1.0/voice/routes`

---

Create a new workgroup for intelligent call routing. Workgroups support types such as IVR, simultaneous ring, and round-robin distribution. Returns a unique WorkgroupId.

**What this does:** Returns the new workgroup's `WorkgroupId` (`WG-`) and full configuration. Once created, add members using `POST /v1.0/workgroups/activity` and assign the workgroup to a voice route.

**Next steps:**
- Add members — `POST /v1.0/workgroups/activity`
- View account workgroups — `GET /v1.0/account/workgroups`



# Create Workgroup Activity
Source: https://docs.telegent.com/api-reference/workgroups/create-workgroup-activity

/api-reference/openapi.json post /v1.0/workgroups/activity
Add a member (user or nested workgroup) to an existing workgroup. Each activity defines how calls are distributed to that member including their position (DigitOrder) and notification preferences.

**What this does:** Returns the new activity record including the `ActivityId` and member configuration. Each activity represents one member in the workgroup ring sequence. The `CallOrder` field determines ring priority.

**Next steps:**
- Update a member — `POST /v1.0/workgroups/activity/update`
- Remove a member — `POST /v1.0/workgroups/activity/delete`
- View the workgroup — `GET /v1.0/workgroups`



# Delete Workgroup
Source: https://docs.telegent.com/api-reference/workgroups/delete-workgroup

/api-reference/openapi.json post /v1.0/workgroups/delete
Permanently remove a workgroup. Before deleting, ensure the workgroup is not assigned to any active voice routes or numbers.

**What this does:** Returns a deletion confirmation. Ensure the workgroup is not assigned to any active voice routes before deleting to avoid call routing failures.

**Next steps:**
- View account workgroups — `GET /v1.0/account/workgroups`
- Create a replacement — `POST /v1.0/workgroups`



# Delete Workgroup Activity
Source: https://docs.telegent.com/api-reference/workgroups/delete-workgroup-activity

/api-reference/openapi.json post /v1.0/workgroups/activity/delete
Remove a member activity from a workgroup. The workgroup itself is not deleted.

**What this does:** Returns a deletion confirmation. Removing the activity removes that member from the workgroup's ring sequence. The workgroup itself is not affected.

**Next steps:**
- View the updated workgroup — `GET /v1.0/workgroups`
- Add a replacement member — `POST /v1.0/workgroups/activity`



# Get Workgroup Details
Source: https://docs.telegent.com/api-reference/workgroups/get-workgroup-details

/api-reference/openapi.json get /v1.0/workgroups
Retrieve configuration details for a specific workgroup by its WorkgroupId. Returns the workgroup's name, type, members, schedule, and routing settings.

**What this does:** Returns the full workgroup configuration including name, type, assigned phone number, schedule, timezone, hold music, off-hours forwarding rules, and member activities. Use this to audit a workgroup or retrieve the `WG-` ID for use in route configuration.

**Next steps:**
- Add a member — `POST /v1.0/workgroups/activity`
- Update the workgroup — `POST /v1.0/workgroups/update`
- Attach to a voice route — `POST /v1.0/voice/routes/update`



# Update Workgroup
Source: https://docs.telegent.com/api-reference/workgroups/update-workgroup

/api-reference/openapi.json post /v1.0/workgroups/update
Update an existing workgroup configuration. Requires the WorkgroupId of the workgroup to modify.

**What this does:** Returns the updated workgroup configuration. Only fields you send are changed; omitted fields retain their current values. Changes apply immediately to all calls routing through this workgroup.

**Next steps:**
- Confirm the update — `GET /v1.0/workgroups`
- View members — `POST /v1.0/workgroups/activity`



# Update Workgroup Activity
Source: https://docs.telegent.com/api-reference/workgroups/update-workgroup-activity

/api-reference/openapi.json post /v1.0/workgroups/activity/update
Update the configuration of a member within a workgroup. A workgroup activity represents an individual agent, destination, or nested workgroup within a ring group. Modify fields such as dial order (DigitOrder), forwarding number, or notification preferences. Requires the WorkgroupActivityId (WAID-) of the activity to update.

**What this does:** Returns the updated activity record. Use this to change a member's ring order, SIP details, or timeout settings within the workgroup.

**Next steps:**
- Confirm the update — `GET /v1.0/workgroups`
- Remove the member — `POST /v1.0/workgroups/activity/delete`



# Changelog
Source: https://docs.telegent.com/changelog/index

A complete record of all updates, enhancements, and bug fixes to the Telegent mPaaS API.

This changelog is published with each product release and documents all changes to the Telegent mPaaS API. Each entry includes a version number, publication date, and a categorized summary of changes.

<Info>
  Release notes are published with every product update. For urgent security notices, customers are also notified directly via email.
</Info>

## How to read this changelog

| Category     | Description                                               |
| ------------ | --------------------------------------------------------- |
| **New**      | Newly added endpoints, features, or capabilities          |
| **Enhanced** | Improvements to existing functionality                    |
| **Fixed**    | Corrections to incorrect behavior or documentation        |
| **Removed**  | Features, fields, or endpoints that have been retired     |
| **Breaking** | Changes that may require updates to existing integrations |

## Release history

| Version                         | Date               | Summary                                                                                                                                                   |
| ------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [v1.3.0](/changelog/v1-3-0)     | September 18, 2026 | New Numbers Inventory Report endpoint; Device Details now IMEI-based with full device profile; InternationalVoiceEnabled and distributor AdminEmail added |
| [v1.2.0.2](/changelog/v1-2-0-2) | September 9, 2026  | Port In accepts messaging, voice and MMS configuration at submission; MmsMessageEnabled now settable on Provision and Update                              |
| [v1.2.0.1](/changelog/v1-2-0-1) | August 20, 2026    | ForwardingNumber and MmsMessageEnabled added to Number Details, Numbers Inventory and Numbers Update                                                      |
| [v1.2.0](/changelog/v1-2-0)     | August 19, 2026    | Per-line MMS control added to Numbers; new Health Status endpoint for platform and T-Mobile API checks                                                    |
| [v1.1.3](/changelog/v1-1-3)     | July 30, 2026      | New Device Unlock Status endpoint — check carrier lock state for any IMEI                                                                                 |
| [v1.1.2](/changelog/v1-1-2)     | July 22, 2026      | Number swap now live; swap limit documented on Numbers Status                                                                                             |
| [v1.1.1](/changelog/v1-1-1)     | May 28, 2026       | 2 new E911 address management endpoints added                                                                                                             |
| [v1.1.0](/changelog/v1-1-0)     | May 27, 2026       | 7 new endpoints added; 58 endpoints updated; 4 endpoints removed                                                                                          |
| [v1.0.2.3](/changelog/v1-0-2-3) | May 27, 2026       | Response payloads added throughout Best Practices and expanded number provisioning guidance                                                               |
| [v1.0.2.2](/changelog/v1-0-2-2) | May 21, 2026       | Dedicated Postman Collection tab added with download button and import guide                                                                              |
| [v1.0.2.1](/changelog/v1-0-2-1) | May 21, 2026       | Port-in expanded to full lifecycle, port-out section added, onboarding checklist updated                                                                  |
| [v1.0.2](/changelog/v1-0-2)     | May 21, 2026       | New Onboarding and Best Practices tabs added; Quick Start Guide tab removed                                                                               |
| [v1.0.1.1](/changelog/v1-0-1-1) | May 20, 2026       | Port-in, voicemail, and provision updates; data usage default note; OAuth2 path correction; portal improvements                                           |
| [v1.0.1](/changelog/v1-0-1)     | May 18, 2026       | API documentation overhaul, endpoint corrections, Service Item Id removal                                                                                 |
| [v1.0.0](/changelog/v1-0-0)     | January 1, 2026    | Initial public release of the Telegent mPaaS API                                                                                                          |


# v1.0.0
Source: https://docs.telegent.com/changelog/v1-0-0

Initial public release of the Telegent mPaaS API.

<Info>
  **Version:** 1.0.0 · **Published:** January 1, 2026 · **Published by:** Telegent Platform Team
</Info>

This is the initial public release of the Telegent mPaaS API. The API provides programmatic access to Telegent's mobile Platform as a Service (mPaaS), enabling customers to manage accounts, services, phone numbers, packages, and more.

***

## New

<AccordionGroup>
  <Accordion title="Full REST API with Bearer authentication">
    The Telegent mPaaS API is available as a REST API secured with Bearer token authentication. All endpoints require a valid access token obtained via the OAuth2 token endpoint.
  </Accordion>

  <Accordion title="Core resource groups available">
    The initial release includes endpoints across all core resource groups: Accounts, Services, Phone Numbers, Packages, Orders, Billing, and more. See the [API Reference](/api-reference/introduction) for the complete list.
  </Accordion>

  <Accordion title="OpenAPI specification published">
    The full OpenAPI 3.0 specification is available and can be used to generate client SDKs in any language.
  </Accordion>

  <Accordion title="API playground">
    An interactive playground is available in the developer portal, allowing you to test API calls directly from the documentation without writing any code.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.1
Source: https://docs.telegent.com/changelog/v1-0-1

API documentation overhaul, endpoint corrections, and removal of deprecated fields.

<Info>
  **Version:** 1.0.1 · **Published:** May 18, 2026 · **Published by:** Telegent Platform Team
</Info>

This release covers documentation accuracy improvements, correction of endpoint descriptions, removal of the deprecated `ServiceItemId` field, and the addition of 37 new endpoints sourced from the live API specification.

***

## New

<AccordionGroup>
  <Accordion title="37 new endpoints added">
    37 endpoints have been added to the API reference, sourced directly from the live developer Swagger specification. These endpoints span existing resource groups and are now fully documented with request/response schemas and descriptions.
  </Accordion>

  <Accordion title="'What this does' summaries on all endpoints">
    Every endpoint in the API reference now includes a plain-language **What this does** section, giving integrators a plain-English overview of each operation without needing to parse the full schema.
  </Accordion>
</AccordionGroup>

***

## Enhanced

<AccordionGroup>
  <Accordion title="Endpoint group names updated">
    API endpoint groupings have been restructured to match the naming conventions in the live developer Swagger specification. This improves consistency between the developer portal and internal tooling.
  </Accordion>

  <Accordion title="GET prefix added to read endpoints">
    All read-only endpoints now carry an explicit `GET` prefix in the sidebar label, improving discoverability and distinguishing them from write operations at a glance.
  </Accordion>

  <Accordion title="AccountId and ServiceId formatting standardised">
    Inconsistent spacing and casing around `AccountId` and `ServiceId` fields have been corrected throughout the specification. Field names now follow a single consistent format across all endpoints.
  </Accordion>

  <Accordion title="PRID replaces PRD throughout the specification">
    All references to `PRD` have been updated to the correct identifier `PRID` (Phone Rate ID) across every applicable endpoint and schema description.
  </Accordion>

  <Accordion title="Package and product ID prefixes corrected">
    `ProductId` and `AggregatorId` field prefixes in Get Package Items and related package endpoints have been corrected to match the live specification. Relevant schema components have also been scoped to only include fields directly used by each endpoint, reducing payload noise.
  </Accordion>

  <Accordion title="Port Out endpoint description corrected">
    The description for the Port Out endpoint was inaccurate and has been rewritten to correctly explain what the operation does and what callers should expect in response.
  </Accordion>
</AccordionGroup>

***

## Removed

<AccordionGroup>
  <Accordion title="ServiceItemId field removed">
    The `ServiceItemId` field has been removed from all endpoints and schemas. This field is no longer part of the API and references to it have been retired from the specification and documentation.
  </Accordion>

  <Accordion title="Duplicate OAuth2 token endpoint removed">
    A duplicate entry for the OAuth2 token endpoint has been removed from the API reference. Only a single, canonical entry remains.
  </Accordion>
</AccordionGroup>

***

## Fixed

* Typos and inconsistencies in field names and descriptions corrected throughout the OpenAPI specification.
* Support email address updated to the correct Telegent support address.

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.1.1
Source: https://docs.telegent.com/changelog/v1-0-1-1

New data usage renewal endpoint, port-in and voicemail updates, data usage default note, OAuth2 path correction, and portal improvements.

<Info>
  **Version:** 1.0.1.1 · **Published:** May 20, 2026 · **Published by:** Telegent Platform Team
</Info>

This release adds the data usage renewal endpoint, expands the port-in and voicemail schemas, corrects the OAuth2 token path to match the live API, and improves the developer portal navigation and branding.

***

## New

<AccordionGroup>
  <Accordion title="Data usage renewal configuration endpoint">
    `POST /v1.0/numbers/data-usage/update-renewal-info` is now documented. Use this endpoint to configure the monthly or weekly usage reset cycle for one or more phone numbers, enable or disable auto-renew, and optionally zero out current usage immediately with `ResetUsage: true`. The renewal cycle is anchored to a per-number `RenewalDay` — not a global calendar reset.
  </Accordion>
</AccordionGroup>

***

## Enhanced

<AccordionGroup>
  <Accordion title="AccountId field added to Number Provision">
    `AccountId` (AID) is now documented as a field on `POST /v1.0/numbers/provision`. Required when a distributor account has more than one sub-account to scope the provisioned number to the correct account.
  </Accordion>

  <Accordion title="ProductType marked as required on Number Provision">
    `ProductType` is now correctly marked as a required field on `POST /v1.0/numbers/provision`. The four supported values are `Sms-Only`, `Data-Only`, `Sms+Data`, and `Sms+Data+Voice`.
  </Accordion>

  <Accordion title="TargetClassification added to Port In Eligibility">
    `TargetClassification` is now a required field on `POST /v1.0/numbers/portin/eligibility`. Specifies the intended number classification for the port (e.g. `Mobile`, `Landline`).
  </Accordion>

  <Accordion title="Port In Update payload expanded">
    `POST /v1.0/numbers/portin/update` now documents the full available payload: `PortInDate`, `TargetPortinClassification`, `SubscriberName`, and `ICCID` (required for pSIM port-ins only) in addition to the existing carrier and billing address fields.
  </Accordion>

  <Accordion title="FirstName and LastName added to Voicemail Update sample">
    The request body sample for `POST /v1.0/numbers/voicemail/update` now includes `FirstName` and `LastName` fields alongside `PIN` and `Email`.
  </Accordion>

  <Accordion title="Default data limit noted on Data Usage Limit endpoint">
    The description for `POST /v1.0/numbers/data-usage` now notes that unless a `LimitValue` is specified, the default data limit is **20 MB**.
  </Accordion>

  <Accordion title="Cancel Port In alias endpoint removed">
    `POST /v1.0/numbers/cancel-portin` has been removed from the API reference. Use `POST /v1.0/numbers/portin/cancel` instead.
  </Accordion>

  <Accordion title="OAuth2 token endpoint path corrected">
    The token endpoint path in the API reference has been corrected from `/v1.0/oauth2/tokens` to `/v1.0/OAuth2/tokens` to match the casing used by the live API. Existing integrations are unaffected as the live API handles both casings, but the documentation now reflects the canonical path.
  </Accordion>

  <Accordion title="Changelog navigation shows version numbers only">
    The changelog sidebar now displays version numbers only (e.g. v1.0.1.1) rather than the month and year. The published date is shown on each entry page.
  </Accordion>

  <Accordion title="Browser tab icon updated">
    The developer portal favicon has been updated to the Telegent logo mark, replacing the previous placeholder icon.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.2
Source: https://docs.telegent.com/changelog/v1-0-2

New Best Practices and Onboarding tabs added to the developer portal, replacing the Quick Start Guide.

<Info>
  **Version:** 1.0.2 · **Published:** May 21, 2026 · **Published by:** Telegent Platform Team
</Info>

This release adds two new documentation tabs to the developer portal — **Onboarding** and **Best Practices** — and retires the Quick Start Guide tab. The Onboarding tab replaces the Quick Start Guide with a full partner onboarding checklist covering every phase from POC kickoff through go-live. The Best Practices tab adds a comprehensive MVNO provisioning reference with request/response payloads, field tables, and an ID glossary.

***

## New

<AccordionGroup>
  <Accordion title="Onboarding tab — Partner onboarding checklist (8 pages)">
    A new **Onboarding** tab has been added as the first tab in the portal navigation. It replaces the Quick Start Guide with a complete partner onboarding plan covering all phases from POC kickoff through the first 30 days of production:

    * **Overview** — phase summary table and navigation cards
    * **Discovery & Setup** — POC kickoff, NDA, scope, contacts, Slack channel setup
    * **Phase 1 — Credentials & Access** — DID assignment, documentation access, first OAuth token
    * **Phase 2 — Connectivity** — webhook URLs, CDR delivery, SIP interconnect
    * **Phase 3 — API Walkthrough & Sandbox Testing** — end-to-end testing checklist covering all Intelligent API categories (Accounts, Products, Packages, Routes, Subscribers, Numbers, Subscriptions, Messaging, Voice, Data, CDRs)
    * **Phase 4 — Production Cutover** — production credentials, first live number, monitoring
    * **Phase 5 — Post-launch** — CDR reconciliation, billing review, 30-day retro
    * **Conditional Add-ons** — A2P (10DLC), IoT, and Static IP / private APN configuration

    Each phase page includes an owner column (Telegent / Partner / Joint), a phase complete gate, and navigation to the next phase.
  </Accordion>

  <Accordion title="Best Practices tab — MVNO provisioning guide (3 pages)">
    A new **Best Practices** tab has been added to the portal navigation, positioned to the right of API Reference. It contains a comprehensive MVNO provisioning guide originally distributed as the Telegent API Best Practices internal document:

    * **Overview** — provisioning flow diagram and 7-phase quick start summary using the `Steps` component
    * **Comprehensive Reference** — full request/response payloads, field tables, and gotchas for all 10 API sections: Authentication, Account, Subscribers & Roles, Routes, ICCID, Products & Packages, Subscriptions, Provisioning & Porting, Data Usage, and AI Guardian
    * **Appendix** — ID glossary (AID, TSUID, MRID, CRID, PID, PKID, NID, ICCID, CFID, MFID) and common error reference

    All JSON payloads from the source document are preserved verbatim in code blocks.
  </Accordion>

  <Accordion title="Provisioning flow diagram added to Best Practices Overview">
    A full-width SVG diagram — **The Provisioning Flow** — has been added to the Best Practices Overview page. It shows all seven provisioning resources (Account, Subscribers, Routes, Products/Packages, Subscription, Provision/Port, Data Limits + Guardian) in a horizontal sequence, grouped into three labeled stages: **1. Set up**, **2. Define what you sell**, and **3. Light up the line**.
  </Accordion>
</AccordionGroup>

***

## Removed

<AccordionGroup>
  <Accordion title="Quick Start Guide tab removed from navigation">
    The **Quick Start Guide** tab has been removed from the portal navigation. Its content is superseded by the new Onboarding tab, which provides a more complete partner onboarding experience. The underlying `quick-start-guide.mdx` file is retained on disk and can be restored if needed.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.2.1
Source: https://docs.telegent.com/changelog/v1-0-2-1

Port-in expanded to a full 5-step lifecycle, new port-out section, and onboarding checklist updated to match.

<Info>
  **Version:** 1.0.2.1 · **Published:** May 21, 2026 · **Published by:** Telegent Platform Team
</Info>

This release updates the Best Practices guide and Partner Onboarding checklist to reflect the full port-in lifecycle and the addition of port-out support, based on an updated source document.

***

## Enhanced

<AccordionGroup>
  <Accordion title="Port-in expanded to a full 5-step lifecycle (Best Practices Reference — Section 8.2)">
    Section 8.2 has been rewritten from a 2-step flow to a complete 5-step lifecycle guide:

    1. **Eligibility** — check before collecting anything from the subscriber; go/no-go guidance based on the result
    2. **Submit** — save the `OrderId` from the response; all subsequent lifecycle calls key off it
    3. **Update** (`POST /v1.0/numbers/portin/update`) — correct name mismatches, wrong account numbers, or missing `PortInDate` without cancelling and resubmitting
    4. **Cancel** (`POST /v1.0/numbers/portin/cancel`) — cancel by `OrderId`; cancel is final
    5. **Monitor** (`GET /v1.0/numbers/order?OrderId=…`) — poll through `Submitted`, `Pending Carrier Approval`, `Scheduled`, `Completed`, `Rejected`, `Cancelled`

    Inline comments added to the eligibility and port-in submit request bodies. Best practice tip expanded to include polling cadence and subscriber notification guidance.
  </Accordion>

  <Accordion title="Port-out section added (Best Practices Reference — Section 8.3)">
    New Section 8.3 documents the port-out flow: the gaining carrier initiates the transfer, and the MVNO must issue a PIN via `POST /v1.0/numbers/portout`. Includes a callout on FCC obligations — issue the PIN promptly and do not suspend service before the port-out completes.
  </Accordion>

  <Accordion title="Phase 6 quick-start description updated (Best Practices Overview)">
    The Phase 6 step on the Best Practices Overview page now reflects the full port-in lifecycle and mentions port-out PIN issuance, replacing the previous single-sentence description.
  </Accordion>

  <Accordion title="Port-in and port-out testing tasks added to onboarding Phase 3">
    The Phase 3 API Walkthrough checklist now includes six additional tasks covering the full port-in lifecycle (eligibility, submit, update, cancel, monitor) and port-out PIN issuance. Both sections are marked as conditional — skip if porting is not in scope for the partner.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.2.2
Source: https://docs.telegent.com/changelog/v1-0-2-2

Dedicated Postman Collection tab added with download button and import guide.

<Info>
  **Version:** 1.0.2.2 · **Published:** May 21, 2026 · **Published by:** Telegent Platform Team
</Info>

This release adds a dedicated **Download Postman** tab to the documentation navigation, giving users a central place to download the mPaaS Postman collection and follow a step-by-step import guide.

***

## New

<AccordionGroup>
  <Accordion title="Download Postman tab added to navigation">
    A new **Download Postman** tab now appears in the top navigation alongside Changelog. Clicking it opens a page with:

    * A **Download Postman Collection** button that saves `Telegent-mPaaS-Postman-Collection.json` directly to your machine
    * An overview of what's included — 121 endpoints across 16 folders with Bearer auth pre-configured
    * A step-by-step guide covering import, environment setup, authentication, and making your first call

    The collection is a Postman Collection v2.1 file generated from the live OpenAPI spec and regenerated automatically whenever the spec is updated.
  </Accordion>

  <Accordion title="Landing page Explore section updated">
    The **Explore the API** card group on the landing page now includes a **Postman Collection** card linking to the new tab, replacing the previous standalone download button.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.0.2.3
Source: https://docs.telegent.com/changelog/v1-0-2-3

Response payloads added throughout Best Practices and expanded number provisioning guidance.

<Info>
  **Version:** 1.0.2.3 · **Published:** May 27, 2026 · **Published by:** Telegent Platform Team
</Info>

This release enriches the Best Practices reference guide with response payload examples for every major API call across Sections 4–10, so you can see exactly what each endpoint returns before writing integration code. The number provisioning walkthrough (Section 8.1) also receives expanded step-by-step context.

***

## Enhanced

<AccordionGroup>
  <Accordion title="Response payloads added to Best Practices Sections 4–10">
    Every key API call in the Best Practices reference guide now shows both the request **and** the response in a tabbed code block. Previously, only request bodies were shown. The following sections are updated:

    | Section                     | Endpoints with new response examples                                                                                           |
    | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | **4 — Routes**              | Create Message Route, Create Voice Route                                                                                       |
    | **5 — Products & Packages** | Create Product, Create Package, Add Package Item                                                                               |
    | **6 — Subscriptions**       | Create Subscription                                                                                                            |
    | **7 — Number Provisioning** | Check Availability, Provision Number                                                                                           |
    | **8 — Port-In Lifecycle**   | Check Eligibility, Submit Port-In, Update Port-In, Cancel Port-In, Check Order Status, Port-Out                                |
    | **9 — Data Usage Controls** | Set Data Usage Rules                                                                                                           |
    | **10 — AI Guardian**        | Enable Guardian Features, Create Call Filter, Add Allowed/Blocked Numbers, Create Message Filter, Add Allowed/Blocked Contacts |

    Response examples include the full object returned — IDs, status fields, and all populated properties — giving you a reliable reference for what to parse and store after each call.
  </Accordion>

  <Accordion title="Number provisioning steps now include descriptive context (Section 8.1)">
    Steps 1 and 2 of the number provisioning walkthrough now explain what each call does, what to look for in the response, and how to carry the result into the next step:

    * **Step 1 (Check Availability):** Clarifies that `AvailableNumberAreas` returns `NGP` and `AreaCode` pairs with live inventory, and that `PageNumber` can be used to paginate if your target area code doesn't appear on the first page.
    * **Step 2 (Provision):** Explains that the response returns `PhoneNumberId` (the `NID-` identifier) and `PhoneNumberAssigned` (the E.164 number), and that both should be saved for use in subscriptions, data usage settings, and route updates.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.1.0
Source: https://docs.telegent.com/changelog/v1-1-0

Webhook management, number reactivation, and documentation improvements across 58 endpoints.

<Info>
  **Version:** 1.1.0 · **Published:** May 27, 2026 · **Published by:** Telegent Platform Team
</Info>

This release introduces full webhook management through the API, number reactivation, and data usage renewal controls. Documentation across 58 existing endpoints has also been improved with clearer descriptions and fully visible request body fields.

***

## New

<AccordionGroup>
  <Accordion title="Webhook Management (4 endpoints)">
    A full CRUD suite for managing webhooks directly through the API — no portal required. Create webhooks with your target URL and event configuration, update them as your infrastructure changes, and delete them when no longer needed. Use `GET /v1.0/webhook` to retrieve a specific webhook by ID at any time.

    * `GET /v1.0/webhook` — Retrieve a webhook by ID
    * `POST /v1.0/webhook/create` — Create a new webhook
    * `POST /v1.0/webhook/update` — Update an existing webhook
    * `POST /v1.0/webhook/delete` — Delete a webhook
  </Accordion>

  <Accordion title="Numbers (2 endpoints)">
    **Number Reactivation** — Reactivate a cancelled number without reprovisioning. Numbers are eligible for reactivation within 24 hours of cancellation. Pass the number identifier and the reactivation is processed immediately.

    **Data Usage Renewal Info** — Update the renewal configuration for data usage settings on a number. Use this to adjust how data thresholds reset at the end of a billing cycle without needing to recreate the full data usage policy.

    * `POST /v1.0/numbers/reactivate` — Numbers - Reactivate
    * `POST /v1.0/numbers/data-usage/update-renewal-info` — Data Usage Update Renewal Info
  </Accordion>

  <Accordion title="Accounts (1 endpoint)">
    **Account Webhooks** — Retrieve all webhooks configured on your account in a single call. Useful for auditing your event delivery configuration or syncing webhook state into your own system.

    * `GET /v1.0/account/webhooks` — Get Account Webhooks
  </Accordion>
</AccordionGroup>

***

## Enhanced

Documentation for 58 endpoints has been improved. Raw code samples have been replaced with structured prose descriptions, request body fields are now fully visible with individual property definitions, and summaries have been standardised for consistency across the reference.

Endpoints updated span Accounts, Numbers, Subscribers, Guardian Features, Call Filter, and Message Filter.

<AccordionGroup>
  <Accordion title="Accounts (11 endpoints)">
    * `GET /v1.0/account` — Get Account Details
    * `POST /v1.0/account/create` — Create New Account
    * `POST /v1.0/account/update` — Update Account
    * `GET /v1.0/account/voice/routes` — List Voice Routes
    * `GET /v1.0/account/message/routes` — List Message Routes
    * `GET /v1.0/account/workgroups` — Get Account's Workgroups
    * `GET /v1.0/account/schedules` — Get Account Schedules
    * `GET /v1.0/account/subscriptions` — Get Subscriptions
    * `GET /v1.0/account/products` — Get Products
    * `GET /v1.0/account/services` — Get Services
    * `GET /v1.0/account/packages` — Get Packages
  </Accordion>

  <Accordion title="Numbers (15 endpoints)">
    * `GET /v1.0/numbers` — Number Details
    * `POST /v1.0/numbers/device-details` — Device Details
    * `GET /v1.0/numbers/inventory` — Numbers Inventory
    * `POST /v1.0/numbers/availability` — Search Available Numbers
    * `POST /v1.0/numbers/provision` — Number Provision (Purchase/Order)
    * `POST /v1.0/numbers/portin` — Numbers - Port In
    * `POST /v1.0/numbers/portin/eligibility` — Numbers - Port In Eligibility
    * `POST /v1.0/numbers/portin/update` — Numbers - Update Port In
    * `POST /v1.0/numbers/cancel-portin` — Cancel Port-in of a Number
    * `POST /v1.0/numbers/portin/cancel` — Numbers - Cancel Port In
    * `POST /v1.0/numbers/portout` — Numbers - Port Out
    * `POST /v1.0/numbers/update` — Numbers Update
    * `POST /v1.0/numbers/status` — Numbers Status
    * `GET /v1.0/numbers/order` — Order ID Details
    * `POST /v1.0/numbers/refresh-nnid` — Numbers - Refresh NNID
  </Accordion>

  <Accordion title="Subscribers (4 endpoints)">
    * `GET /v1.0/subscribers/get` — Get Subscriber Details
    * `POST /v1.0/subscribers/create` — Create Subscriber
    * `POST /v1.0/subscribers/update` — Update Subscriber
    * `POST /v1.0/subscribers/transfer` — Transfer Subscriber
  </Accordion>

  <Accordion title="Guardian Features (6 endpoints)">
    * `GET /v1.0/subscribers/guardian-features` — Get Guardian Features
    * `POST /v1.0/subscribers/guardian-features` — Configure Guardian Features
    * `GET /v1.0/subscribers/guardians/relation/parent` — Get Guardian Relation Parent
    * `GET /v1.0/subscribers/guardians/relation/child` — Get Guardian Relation Child
    * `POST /v1.0/subscribers/guardians/relation` — Create Guardian Relation
    * `POST /v1.0/subscribers/guardians/relation/delete` — Remove Guardian Relation
  </Accordion>

  <Accordion title="Call Filter (8 endpoints)">
    * `POST /v1.0/subscribers/call-filter` — Create Call Filter
    * `GET /v1.0/subscribers/call-filter` — Get Call Filters
    * `POST /v1.0/subscribers/call-filter/update` — Update Call Filter
    * `POST /v1.0/subscribers/call-filter/delete` — Delete Call Filter
    * `GET /v1.0/subscribers/call-filter/allowed-numbers` — Get Allowed Numbers
    * `POST /v1.0/subscribers/call-filter/allowed-numbers/add` — Add Allowed Numbers
    * `POST /v1.0/subscribers/call-filter/allowed-numbers/remove` — Remove Allowed Numbers
    * `GET /v1.0/subscribers/call-filter/keywords` — Get Call Filter Keywords
  </Accordion>

  <Accordion title="Blocked Numbers (3 endpoints)">
    * `GET /v1.0/subscribers/call-filter/blocked-numbers` — Get Blocked Numbers
    * `POST /v1.0/subscribers/call-filter/blocked-numbers/add` — Add Blocked Numbers
    * `POST /v1.0/subscribers/call-filter/blocked-numbers/remove` — Remove Blocked Numbers
  </Accordion>

  <Accordion title="Message Filter (11 endpoints)">
    * `POST /v1.0/subscribers/message-filter` — Create Message Filter
    * `GET /v1.0/subscribers/message-filter` — Get Message Filters
    * `POST /v1.0/subscribers/message-filter/update` — Update Message Filter
    * `POST /v1.0/subscribers/message-filter/delete` — Delete Message Filter
    * `GET /v1.0/subscribers/message-filter/allowed-contacts` — Get Allowed Contacts
    * `POST /v1.0/subscribers/message-filter/allowed-contacts/add` — Add Allowed Contacts
    * `POST /v1.0/subscribers/message-filter/allowed-contacts/remove` — Remove Allowed Contacts
    * `GET /v1.0/subscribers/message-filter/blocked-contacts` — Get Blocked Contacts
    * `POST /v1.0/subscribers/message-filter/blocked-contacts/add` — Add Blocked Contacts
    * `POST /v1.0/subscribers/message-filter/blocked-contacts/remove` — Remove Blocked Contacts
    * `GET /v1.0/subscribers/message-filter/keywords` — Get Message Filter Keywords
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.1.1
Source: https://docs.telegent.com/changelog/v1-1-1

E911 address management added with two new endpoints.

<Info>
  **Version:** 1.1.1 · **Published:** May 28, 2026 · **Published by:** Telegent Platform Team
</Info>

This patch release adds E911 address management to the Numbers group, enabling partners to register and retrieve emergency service addresses for any provisioned phone number directly through the API.

***

## New

<AccordionGroup>
  <Accordion title="Numbers (2 endpoints)">
    **E911 Address Management** — Register or update the emergency 911 address associated with a phone number, and retrieve the address currently on file. The E911 address is provided to emergency services when a 911 call is placed from the specified number. Addresses must match a valid MSAG (Master Street Address Guide) location.

    * `GET /v1.0/numbers/e911address` — Numbers - Get E911 Address
    * `POST /v1.0/numbers/e911address/update` — Numbers - Update E911 Address
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.1.2
Source: https://docs.telegent.com/changelog/v1-1-2

Number swap functionality is now live; swap limit documented on the Numbers Status endpoint.

<Info>
  **Version:** 1.1.2 · **Published:** July 22, 2026 · **Published by:** Telegent Platform Team
</Info>

This release enables the `Swap` action on the Numbers Status endpoint and documents the associated swap frequency limit.

***

## Enhanced

<AccordionGroup>
  <Accordion title="Number swap is now live on Numbers Status">
    The `Swap` action code on `POST /v1.0/numbers/status` is now fully functional. A number can be swapped **twice every 120 days**; additional `Swap` requests for the same number within that rolling window will be rejected. This limit is now documented directly on the endpoint reference.
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.1.3
Source: https://docs.telegent.com/changelog/v1-1-3

Device unlock status lookup added for any IMEI.

<Info>
  **Version:** 1.1.3 · **Published:** July 30, 2026 · **Published by:** Telegent Platform Team
</Info>

This patch release adds a device unlock status lookup to the Numbers group, letting partners check the carrier lock state of any device — including handsets that were never provisioned on the Telegent network.

***

## New

<AccordionGroup>
  <Accordion title="Numbers (1 endpoint)">
    **Device Unlock Status** — Check whether a device is carrier-locked or unlocked, by IMEI or by phone number. Supply `PhoneNumber` for a device already on your account and its IMEI is resolved automatically; supply `IMEI` directly for any other device, including handsets never provisioned on the Telegent network. `PhoneNumber` is optional — if it is blank, `IMEI` is required.

    * `POST /v1.0/numbers/device/unlock-status` — Device Unlock Status
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.2.0
Source: https://docs.telegent.com/changelog/v1-2-0

Per-line MMS control and a new platform health check endpoint.

<Info>
  **Version:** 1.2.0 · **Published:** August 19, 2026 · **Published by:** Telegent Platform Team
</Info>

This release adds per-line control of MMS to the Numbers group, and introduces a Health Status group with a platform health check that reports the reachability of the Telegent database and the upstream T-Mobile API.

***

## New

<AccordionGroup>
  <Accordion title="Numbers (1 endpoint)">
    **Numbers - Update MMS Settings** — Enable or disable MMS on a provisioned line. MMS is a per-line setting independent of the message route: disabling it stops picture, video and group messaging on that line while leaving SMS in place. The response returns the resulting state in `MMS` (`Enabled` or `Disabled`) alongside `Status` and `StatusMessage`. `AccountId` is required for distributors whose token has access to more than one account.

    * `POST /v1.0/numbers/mms/update` — Numbers - Update MMS Settings
  </Accordion>

  <Accordion title="Health Status (1 endpoint)">
    **Health Status** — Check that the platform and its upstream dependencies are reachable. Returns a top-level `Status`, the UTC time the checks ran in `Checked_On_UTC`, and a block per dependency — `Database` and `TMobile_Api` — each reporting its own `Status`, round-trip `Duration_Ms`, and an `Error` that is `null` while healthy. An unhealthy dependency is reported in the payload rather than as an HTTP error, so read `Status` instead of relying on the status code alone.

    * `POST /v1.0/health-status` — Health Status
  </Accordion>
</AccordionGroup>

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.2.0.1
Source: https://docs.telegent.com/changelog/v1-2-0-1

Forwarding number and per-line MMS state now returned on the Numbers endpoints.

<Info>
  **Version:** 1.2.0.1 · **Published:** August 20, 2026 · **Published by:** Telegent Platform Team
</Info>

Two fields have been added to the Numbers group. `ForwardingNumber` exposes the number that calls to a line are forwarded to, and `MmsMessageEnabled` reports whether MMS is enabled on the line. Both are returned by Number Details and Numbers Inventory, and `ForwardingNumber` can now be set through Numbers Update.

***

## Enhanced

* **Number Details** (`GET /v1.0/numbers`) — the response now includes `ForwardingNumber` and `MmsMessageEnabled`.
* **Numbers Inventory** (`GET /v1.0/numbers/inventory`) — every record in `PhoneNumbers` now includes `ForwardingNumber` and `MmsMessageEnabled`.
* **Numbers Update** (`POST /v1.0/numbers/update`) — `ForwardingNumber` is now accepted in the request body and returned in the response.

`ForwardingNumber` is an E.164 string and is returned as an empty string on lines with no forwarding configured. Send an empty string to clear forwarding on a line.

`MmsMessageEnabled` is a boolean and is independent of `MessageEnabled` — disabling MMS leaves SMS in place. It is read-only on these endpoints; to change it, use `POST /v1.0/numbers/mms/update`.

These are additive changes. Existing integrations continue to work without modification.

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.2.0.2
Source: https://docs.telegent.com/changelog/v1-2-0-2

Port In accepts messaging, voice and MMS configuration at submission; MMS is now settable on Provision and Update.

<Info>
  **Version:** 1.2.0.2 · **Published:** September 9, 2026 · **Published by:** Telegent Platform Team
</Info>

Port In now accepts a number's messaging, voice, and MMS configuration directly in the submission request. Previously these were applied with a separate `POST /v1.0/numbers/update` call after the port; they can now be set up front, so a ported-in number arrives already configured. The same release adds inline MMS control to Number Provision and Numbers Update.

***

## Enhanced

<AccordionGroup>
  <Accordion title="Port In (POST /v1.0/numbers/portin)">
    **Port In** now accepts the full messaging and voice configuration in the submission request, removing the need for a follow-up **Numbers Update** call after the port completes:

    * `MessageType` — `a2p` or `p2p`
    * `MessageEnabled` — enable SMS on the line
    * `MmsMessageEnabled` — enable MMS on the line (optional; independent of `MessageEnabled`)
    * `MessageRouteId` — MRID for message routing (required when SMS or MMS is enabled)
    * `VoiceEnabled` / `VoiceRouteId` — enable voice and assign a CRID (required when voice is enabled)
    * `DataEnabled` — enable data capabilities (IoT numbers)
    * `AssignedSubscriberId` — assign a subscriber (`TSUID-`) at port time
    * `ProductType` — `Sms-Only`, `Data-Only`, `Sms+Data`, or `Sms+Data+Voice`
  </Accordion>

  <Accordion title="Number Provision & Numbers Update">
    **Number Provision** (`POST /v1.0/numbers/provision`) and **Numbers Update** (`POST /v1.0/numbers/update`) now accept `MmsMessageEnabled` in the request body, so MMS can be enabled or disabled inline. `MmsMessageEnabled` is independent of `MessageEnabled` (SMS) and can still be changed on its own via `POST /v1.0/numbers/mms/update`.
  </Accordion>
</AccordionGroup>

***

## Fixed

* Clarified the `MessageEnabled` description across the Numbers endpoints — it controls **SMS only** and does not affect MMS. Earlier copy implied a single field toggled both SMS and MMS.

***

These are additive changes. Existing integrations continue to work without modification.

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# v1.3.0
Source: https://docs.telegent.com/changelog/v1-3-0

New Numbers Inventory Report endpoint; Device Details is now an IMEI-based device lookup; InternationalVoiceEnabled and distributor AdminEmail added.

<Info>
  **Version:** 1.3.0 · **Published:** September 18, 2026 · **Published by:** Telegent Platform Team
</Info>

This release adds a Numbers Inventory Report endpoint for bulk exports, expands Device Details into a full IMEI-based device lookup, and introduces per-line international voice control plus a distributor admin email for report delivery.

***

## New

<AccordionGroup>
  <Accordion title="Numbers (1 endpoint)">
    **Numbers Inventory Report** — Request a full inventory report for a distributor without paging through the inventory endpoint. Submit a `DistributorId` and optional `Filter`; the report is generated asynchronously and a CSV of every number (with number details) is emailed to the distributor's admin email. Returns `200 OK` with no body.

    * `POST /v1.0/numbers/inventory-report` — Numbers Inventory Report
  </Accordion>
</AccordionGroup>

***

## Enhanced

* **Device Details** (`POST /v1.0/numbers/device-details`) — now looked up by **`IMEI`** instead of phone number (number ownership is no longer required), and the response returns the full device profile: `DeviceManufacturer` plus `Sim_Specifications`, `Technology`, `Device_Specifications`, `Device_Capabilities`, `Network_Compatibility`, and `Certification` (returned as JSON-encoded strings). `PhoneNumber` is no longer accepted as input.
* **International voice** — a new `InternationalVoiceEnabled` boolean is returned by **Number Details** (`GET /v1.0/numbers`) and **Numbers Inventory** (`GET /v1.0/numbers/inventory`), and can be set on **Numbers Update** (`POST /v1.0/numbers/update`).
* **Distributors** — **Create Distributor** (`POST /v1.0/distributor/create`) and **Update Distributor** (`POST /v1.0/distributor/update`) now accept and return `AdminEmail`, the address that receives distributor reports (including the Numbers Inventory Report CSV).

***

<Note>
  If you have questions about any of these changes, contact [support@telegent.com](mailto:support@telegent.com).
</Note>


# Conditional Add-ons
Source: https://docs.telegent.com/onboarding/add-ons

A2P (10DLC), IoT, and Static IP / private APN add-ons — run these alongside the matching phase.

Run these alongside the matching phase. Skip any that don't apply to your use case.

***

## Add-on A — A2P Messaging (10DLC)

**Required if** the partner is sending A2P (application-to-person) messages. Slots in alongside **Phase 3 — Intelligent Messaging** testing.

| # | Task                                                                                    | Owner   | Notes       |
| - | --------------------------------------------------------------------------------------- | ------- | ----------- |
| 1 | TCR brand registered via Telegent's Sinch DCA path.                                     | Partner | Brand ID    |
| 2 | TCR campaign registered (use case, sample messages, opt-in/opt-out flow).               | Partner | Campaign ID |
| 3 | KYC documentation submitted to Sinch / TCR.                                             | Partner | —           |
| 4 | Campaign approved and bound to partner's `NumberType=mvno` + `MessageType=a2p` numbers. | Joint   | —           |
| 5 | Throughput / TPS confirmed for the campaign tier.                                       | Joint   | —           |

<Note>
  For A2P, use `NumberType = "mvno"` and `MessageType = "a2p"` when provisioning numbers. `iot` numbers are p2p only; `voip` numbers are a2p only.
</Note>

***

## Add-on B — IoT

**Required for** IoT modules / cellular devices that aren't phones. Slots in alongside **Phase 3 — Intelligent Data** testing.

| # | Task                                                                                                       | Owner    | Notes                            |
| - | ---------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
| 1 | APN confirmed (default: `iot.joonto`).                                                                     | Joint    | —                                |
| 2 | Module IMEI / TAC list provided for whitelist if device class is non-phone.                                | Partner  | —                                |
| 3 | T-Mobile IMEI / TAC whitelist applied to the account.                                                      | Telegent | Prevents `EMM_CAUSE_ESM_FAILURE` |
| 4 | Radio access confirmed (Cat-1 validated; CAT-M1 / NB-IoT subject to engineering confirmation per SIM SKU). | Joint    | —                                |
| 5 | Test device attach + data session on partner module.                                                       | Partner  | —                                |
| 6 | Sample data CDR delivered with expected fields populated.                                                  | Partner  | —                                |

<Warning>
  **CAT-M1 / NB-IoT support** is subject to engineering confirmation per SIM SKU — verify with your Telegent rep before committing to a device class.
</Warning>

***

## Add-on C — Static IP / Private APN

**Required if** the partner needs static IP allocations or a dedicated APN. Slots in alongside **Phase 2 or Phase 3**.

| # | Task                                                                         | Owner    | Notes |
| - | ---------------------------------------------------------------------------- | -------- | ----- |
| 1 | Static-IP requirement confirmed (count, region, IPv4/IPv6).                  | Joint    | —     |
| 2 | APN confirmed (e.g., `telegent.static`) or private APN scoped with T-Mobile. | Telegent | —     |
| 3 | IP allocations issued and mapped to ICCIDs / MSISDNs.                        | Telegent | —     |
| 4 | Partner-side firewall / NAT rules adjusted.                                  | Partner  | —     |
| 5 | Reachability test from partner to device IP.                                 | Partner  | —     |

***

<Note>
  Pair this checklist with the **Telegent Customer FAQ** for technical detail on each API call.
</Note>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding" title="Back to Onboarding Overview">
    Full phase summary and navigation
  </Card>

  <Card icon="book-open" href="/resources" title="MVNO Guide">
    Deep-dive API reference for MVNO provisioning
  </Card>
</CardGroup>


# Discovery & Setup
Source: https://docs.telegent.com/onboarding/discovery

Kick off the POC, confirm scope, get the NDA in place, and stand up communication channels.

**Goal:** Kick off the POC, confirm scope, get the NDA in place, and stand up communication channels.

***

## Checklist

| # | Task                                                                                                                               | Owner    |
| - | ---------------------------------------------------------------------------------------------------------------------------------- | -------- |
| 1 | POC kickoff call held — confirm use case (MVNO / IoT / SIP / API only) and add-ons needed (A2P, SIP interconnect, IoT, static IP). | Joint    |
| 2 | POC scope and success criteria agreed — what does "POC passed" mean for this partner?                                              | Joint    |
| 3 | NDA in place (required before sharing technical details).                                                                          | Joint    |
| 4 | Primary technical contact identified (name + email + phone).                                                                       | Partner  |
| 5 | Primary commercial / billing contact identified.                                                                                   | Partner  |
| 6 | Shared Slack channel created (e.g., `partner-external`) and partner team invited.                                                  | Telegent |
| 7 | Freshdesk support email shared with partner team for ticket intake.                                                                | Telegent |
| 8 | MSA / order form signed — typically completed during the POC, not a kickoff blocker.                                               | Joint    |

***

<Check>
  **Phase complete when:** POC has kicked off, NDA is in place, scope is agreed, and both teams are in Slack.
</Check>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding" title="Back to Overview">
    Return to the full onboarding overview
  </Card>

  <Card icon="arrow-right" href="/onboarding/phase-1" title="Next: Phase 1 — Credentials & Access">
    Get credentials issued and the first OAuth token working
  </Card>
</CardGroup>


# Partner Onboarding
Source: https://docs.telegent.com/onboarding/index

MVNO / IoT / API partner onboarding checklist — from POC kickoff through go-live and first 30 days.

## Overview

This plan walks a new Telegent partner from POC kickoff through go-live and the first 30 days of steady-state operation. It is a joint checklist — tasks are owned by **Telegent**, the **Partner**, or both (**Joint**).

<Note>
  **How to use this plan:**

  * Onboarding begins with a POC. Work the phases in order.
  * Each phase has a clear owner and a **Phase Complete** gate — don't move on until it's met.
  * Skip conditional sections that don't apply to your use case (e.g., skip SIP if you're API-only).
  * Conditional add-ons (A2P / IoT / Static IP) are documented at the end and slot in alongside the relevant phase.
</Note>

***

## Onboarding at a Glance

| Phase       | Name                              | Summary                                                      |
| ----------- | --------------------------------- | ------------------------------------------------------------ |
| **D\&S**    | Discovery & Setup                 | POC kickoff, NDA, scope, contacts, Slack.                    |
| **Phase 1** | Credentials & Access              | Account, DID, docs, OAuth working.                           |
| **Phase 2** | Connectivity                      | Webhooks, CDR delivery, SIP interconnect (if voice via SIP). |
| **Phase 3** | API Walkthrough & Sandbox Testing | Work through each Intelligent API section on dev.            |
| **Phase 4** | Production Cutover                | Issue prod credentials, first live number, go-live.          |
| **Phase 5** | Post-launch (30d)                 | Release notes, CDRs, billing review, retro.                  |

***

## Phases

<CardGroup>
  <Card icon="flag" href="/onboarding/discovery" title="Discovery & Setup">
    POC kickoff, NDA, scope alignment, and Slack channel setup
  </Card>

  <Card icon="key" href="/onboarding/phase-1" title="Phase 1 — Credentials & Access">
    Credentials issued, documentation access confirmed, first OAuth token generated
  </Card>

  <Card icon="plug" href="/onboarding/phase-2" title="Phase 2 — Connectivity">
    Webhooks configured, CDR delivery set up, SIP interconnect (if applicable)
  </Card>

  <Card icon="flask" href="/onboarding/phase-3" title="Phase 3 — API Walkthrough & Testing">
    End-to-end sandbox testing of all Intelligent API categories
  </Card>

  <Card icon="rocket" href="/onboarding/phase-4" title="Phase 4 — Production Cutover">
    Production credentials, first live number, monitoring in place
  </Card>

  <Card icon="chart-line" href="/onboarding/phase-5" title="Phase 5 — Post-launch">
    CDR reconciliation, billing review, 30-day retro
  </Card>

  <Card icon="puzzle-piece" href="/onboarding/add-ons" title="Conditional Add-ons">
    A2P (10DLC), IoT, and Static IP / private APN add-ons
  </Card>
</CardGroup>


# Phase 1 — Credentials & Access
Source: https://docs.telegent.com/onboarding/phase-1

Get the partner into the dev environment with credentials, documentation access, and a working OAuth token.

**Goal:** Get the partner into the dev environment with credentials, documentation access, and a working OAuth token.

***

## Checklist

| # | Task                                                                                                  | Owner    |
| - | ----------------------------------------------------------------------------------------------------- | -------- |
| 1 | Telegent account created and DID (Distributor ID) assigned.                                           | Telegent |
| 2 | `AccountKey` (DID-...) and `AccountSecret` issued via secure channel.                                 | Telegent |
| 3 | Partner confirmed access to [docs.telegent.com](https://docs.telegent.com) (partner-facing API docs). | Partner  |
| 4 | Partner accessed Swagger at `https://api.telegent.com/docs/index.html` (interactive API explorer).    | Partner  |
| 5 | Partner imported Postman collection (optional — Swagger covers most cases).                           | Partner  |
| 6 | Partner generated first OAuth token successfully against `/v1.0/oauth2/tokens`.                       | Partner  |
| 7 | Partner reviewed escalation contacts and on-call paths.                                               | Partner  |

***

### Generating Your First Token

**Endpoint:** `POST /v1.0/oauth2/tokens`

```json Request theme={null}
{
  "AccountKey": "YOUR_ACCOUNT_KEY",
  "AccountSecret": "YOUR_ACCOUNT_SECRET",
  "ApiEndpoint": "https://api.telegent.com/v1.0/numbers/provision"
}
```

```json Response theme={null}
{
  "token": "abcdefghi.................",
  "successful": true,
  "tokenExpiry": "05/02/2026 06:36:13 PM"
}
```

<Warning>
  **Token reminder:** Tokens are scoped to a specific `ApiEndpoint` and expire after a few minutes — always include `AccountKey`, `AccountSecret`, **and** `ApiEndpoint` in every token request. Never share credentials over email.
</Warning>

***

<Check>
  **Phase complete when:** Partner can hit the dev API and generate a valid token on their own.
</Check>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding/discovery" title="Previous: Discovery & Setup">
    POC kickoff and NDA
  </Card>

  <Card icon="arrow-right" href="/onboarding/phase-2" title="Next: Phase 2 — Connectivity">
    Configure webhooks and SIP interconnect
  </Card>
</CardGroup>


# Phase 2 — Connectivity
Source: https://docs.telegent.com/onboarding/phase-2

Collect webhook URLs and, for SIP partners, exchange SBC IPs and agree on signaling so the network is ready before testing begins.

**Goal:** Collect the partner's webhook URLs and, for SIP partners, exchange SBC IPs and agree on signaling so the network is ready before testing begins.

***

## Checklist

### Webhooks — Inbound Messaging and DLR

| # | Task                                                                                                                              | Owner   |
| - | --------------------------------------------------------------------------------------------------------------------------------- | ------- |
| 1 | Partner provided inbound message webhook URL (with auth type: Bearer / Basic).                                                    | Partner |
| 2 | Partner provided DLR (delivery report) webhook URL — may reuse the inbound URL.                                                   | Partner |
| 3 | Webhook URLs reachable from Telegent infrastructure (firewall / IP whitelist done).                                               | Joint   |
| 4 | CDR delivery method chosen: webhook / email / both. Voice and SMS files are split.                                                | Partner |
| 5 | Partner reviewed inbound JSON schema (`Message_ID`, `Owner`, `To`, `From`, `Message_Body`, `Segment`, etc.) per the Customer FAQ. | Partner |

### SIP Interconnect — If Voice via SIP is in Scope

| # | Task                                                                               | Owner    |
| - | ---------------------------------------------------------------------------------- | -------- |
| 6 | Partner provided SBC public IP(s) for SIP signaling and media.                     | Partner  |
| 7 | Telegent provided Telegent SBC IP(s).                                              | Telegent |
| 8 | Mutual IP whitelist applied on both sides.                                         | Joint    |
| 9 | Custom SIP headers agreed (e.g., hairpin flags for FMC, identifying flag headers). | Joint    |

***

### Inbound Message Webhook — Expected JSON Schema

When an inbound SMS/MMS is delivered to your webhook, the payload includes:

| Field          | Description                                   |
| -------------- | --------------------------------------------- |
| `Message_ID`   | Unique identifier for the message             |
| `Owner`        | The Telegent number that received the message |
| `To`           | Recipient number (E.164)                      |
| `From`         | Sender number (E.164)                         |
| `Message_Body` | Text content of the message                   |
| `Segment`      | Number of SMS segments                        |

<Note>
  For the full inbound message schema, refer to the Customer FAQ provided by your Telegent representative.
</Note>

***

<Check>
  **Phase complete when:** Webhooks are reachable from Telegent, and (for SIP partners) both sides have whitelisted each other and agreed on headers.
</Check>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding/phase-1" title="Previous: Phase 1 — Credentials & Access">
    Credentials and first OAuth token
  </Card>

  <Card icon="arrow-right" href="/onboarding/phase-3" title="Next: Phase 3 — API Walkthrough & Testing">
    End-to-end sandbox testing
  </Card>
</CardGroup>


# Phase 3 — API Walkthrough & Sandbox Testing
Source: https://docs.telegent.com/onboarding/phase-3

Walk through every Intelligent API section in dependency order. By the end, the partner has built their own number end-to-end on dev.

**Goal:** Walk the partner through every Intelligent API section in dependency order. By the end, the partner has built their own number end-to-end on dev.

<Note>
  **Work the sections in order.** Each one depends on the previous: you can't create a Subscription without a Subscriber, a Number, and a Package; you can't provision a Number without Routes. Skip optional sections (Voice, Data) if they're out of scope.
</Note>

***

## Checklist

### Intelligent Accounts — Child Accounts Under the Distributor

*Skip if operating under a single account.*

| # | Task                                                                 | Owner   | ID to Save |
| - | -------------------------------------------------------------------- | ------- | ---------- |
| 1 | Partner creates a child Account under their Distributor via the API. | Partner | `AID-...`  |

### Intelligent Products — SKUs That Will Be Billed

| # | Task                                                            | Owner   | ID to Save |
| - | --------------------------------------------------------------- | ------- | ---------- |
| 2 | Partner creates one or more Products via `POST /v1.0/products`. | Partner | `PID-...`  |

### Intelligent Packages — Bundle Products into Priced Offerings

| # | Task                                                                               | Owner   | ID to Save |
| - | ---------------------------------------------------------------------------------- | ------- | ---------- |
| 3 | Partner creates a Package bundling one or more Products via `POST /v1.0/packages`. | Partner | `PKID-...` |

### Intelligent Routes — Message and Voice Routing Infrastructure

| # | Task                                                                                                                                                             | Owner   | ID to Save |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------- |
| 4 | Partner creates a Message Route (MRID) via API. First-time setup can be a joint call.                                                                            | Partner | `MRID-...` |
| 5 | Partner creates a Voice Route (CRID) via API. For SIP partners, this is a SIP-enabled route pointing to the partner's SBC. First-time setup can be a joint call. | Partner | `CRID-...` |

### Intelligent Subscribers — The End-User Record

| # | Task                                                       | Owner   | ID to Save  |
| - | ---------------------------------------------------------- | ------- | ----------- |
| 6 | Partner creates a Subscriber via `POST /v1.0/subscribers`. | Partner | `TSUID-...` |

### Intelligent Mobile Numbers — Number Provisioning and Lifecycle

| # | Task                                                                                                          | Owner   | ID to Save |
| - | ------------------------------------------------------------------------------------------------------------- | ------- | ---------- |
| 7 | Partner provisions a test number via `POST /v1.0/numbers/provision`.                                          | Partner | `TNID-...` |
| 8 | Partner tests number status changes (suspend / restore / deactivate / reactivate) via `/v1.0/numbers/status`. | Partner | —          |

### Intelligent Port-In — Full Lifecycle *(if porting is in scope)*

| #  | Task                                                                                                                                                                                           | Owner   | Notes                                                         |
| -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
| 8a | Eligibility checked via `POST /v1.0/numbers/portin/eligibility` before collecting any subscriber details.                                                                                      | Partner | Confirm number is portable to target classification           |
| 8b | Port-in submitted via `POST /v1.0/numbers/portin` after LOA signed and current-carrier details confirmed.                                                                                      | Partner | Save `OrderId` (JNUOID-…) from the response                   |
| 8c | Port-in update tested via `POST /v1.0/numbers/portin/update` using the `OrderId` — simulate a carrier rejection correction.                                                                    | Partner | Test `PortInDate` for wireline scenarios                      |
| 8d | Port-in cancel tested via `POST /v1.0/numbers/portin/cancel` using the `OrderId`.                                                                                                              | Partner | Confirm cancel is final — a fresh submit is required to retry |
| 8e | Order status monitored via `GET /v1.0/numbers/order?OrderId=…` and partner can read all statuses (`Submitted`, `Pending Carrier Approval`, `Scheduled`, `Completed`, `Rejected`, `Cancelled`). | Partner | —                                                             |

### Intelligent Port-Out — PIN Issuance *(if porting out is in scope)*

| #  | Task                                                                    | Owner   | Notes                                              |
| -- | ----------------------------------------------------------------------- | ------- | -------------------------------------------------- |
| 8f | Port-out PIN issued via `POST /v1.0/numbers/portout` for a test number. | Partner | Confirm PIN reaches the gaining carrier simulation |

### Intelligent Subscriptions — Link Subscriber + Number + Package

| # | Task                                                                                                                        | Owner   | ID to Save |
| - | --------------------------------------------------------------------------------------------------------------------------- | ------- | ---------- |
| 9 | Partner creates a Subscription via `POST /v1.0/subscriptions` referencing `SubscriberId`, `TNID`, `ICCID`, and `PackageId`. | Partner | `SUB-...`  |

### Intelligent Messaging — SMS and MMS Round-Trip

| #  | Task                                                                                 | Owner   | Notes                       |
| -- | ------------------------------------------------------------------------------------ | ------- | --------------------------- |
| 10 | Outbound SMS sent via `/v1.0/message/outbound` and DLR received on partner webhook.  | Partner | Path is singular: `message` |
| 11 | Inbound SMS received on partner webhook with correct JSON schema.                    | Partner | —                           |
| 12 | Outbound and inbound MMS tested with `MMS_Media_URL` populated. *(If MMS in scope.)* | Partner | —                           |

### Intelligent Voice — Call Placement and Receipt

*Skip if voice is not in scope.*

| #  | Task                                                                                                                                      | Owner   | Notes |
| -- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- |
| 13 | Partner numbers assigned to the correct Voice Route via API (SIP-enabled route for SIP partners). Allow up to 10 minutes for propagation. | Partner | —     |
| 14 | OPTIONS keepalive confirmed both directions. *(SIP partners only.)*                                                                       | Joint   | —     |
| 15 | Outbound call placed from the test number and connected. SIP partners verify it lands on their SBC.                                       | Partner | —     |
| 16 | Inbound call received on the test number. SIP partners verify the Request-URI and headers match the agreed format.                        | Partner | —     |

### Intelligent Data — Data Attach and Session

*Skip if data is not in scope.*

| #  | Task                                                                                              | Owner   | Notes |
| -- | ------------------------------------------------------------------------------------------------- | ------- | ----- |
| 17 | Data session attached on the assigned APN (e.g., `iot.joonto` for IoT, `wireless.mobi` for MVNO). | Partner | —     |

### CDRs — Call Detail Records

| #  | Task                                                                                     | Owner   | Notes             |
| -- | ---------------------------------------------------------------------------------------- | ------- | ----------------- |
| 18 | Sample CDR delivered (via configured method: webhook / email) and parsed by the partner. | Partner | Voice + SMS split |

### Sign-off

| #  | Task                                            | Owner |
| -- | ----------------------------------------------- | ----- |
| 19 | End-to-end happy path signed off by both teams. | Joint |

***

<Warning>
  **Voice-route propagation:** Voice-route changes propagate via a 10-minute automation cycle. For urgent moves during testing, ping Telegent on-call for a manual flip.
</Warning>

***

<Check>
  **Phase complete when:** Every relevant Intelligent API category has been tested on dev. The partner can provision, message, and (if applicable) call from a number they created themselves.
</Check>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding/phase-2" title="Previous: Phase 2 — Connectivity">
    Webhooks and SIP interconnect
  </Card>

  <Card icon="arrow-right" href="/onboarding/phase-4" title="Next: Phase 4 — Production Cutover">
    Move to production credentials and go live
  </Card>
</CardGroup>


# Phase 4 — Production Cutover
Source: https://docs.telegent.com/onboarding/phase-4

Move the partner to production credentials, provision the first live number, and confirm monitoring is in place.

**Goal:** Move the partner to production credentials, provision the first live number, and confirm monitoring is in place.

***

## Checklist

| # | Task                                                                                                     | Owner    | Notes                                     |
| - | -------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------- |
| 1 | Production `AccountKey` and `AccountSecret` issued.                                                      | Telegent | —                                         |
| 2 | Production webhooks confirmed reachable from Telegent infrastructure.                                    | Joint    | —                                         |
| 3 | Production Message Route + Voice Route created (partner-owned going forward).                            | Partner  | Joint call for first-time setup if needed |
| 4 | First production number provisioned end-to-end (Product → Package → Subscriber → Number → Subscription). | Partner  | Capture MSISDN + TNID                     |
| 5 | First production outbound SMS sent and delivered.                                                        | Joint    | —                                         |
| 6 | First production inbound SMS received and parsed.                                                        | Joint    | —                                         |
| 7 | Partner-side monitoring / alerting in place (webhook failures, token expiry, error rates).               | Partner  | —                                         |
| 8 | On-call escalation path documented (who pages whom, what hours, how).                                    | Joint    | —                                         |
| 9 | Go-live sign-off.                                                                                        | Joint    | Date + initials                           |

***

### First Production Number — End-to-End Flow

The first live number must be provisioned in this exact dependency order:

<Steps>
  <Step title="Create Product">
    `POST /v1.0/products` — defines what you're selling (eSIM, data, SMS bucket, etc.)
  </Step>

  <Step title="Create Package">
    `POST /v1.0/packages` — bundles one or more Products into a priced offering
  </Step>

  <Step title="Create Subscriber">
    `POST /v1.0/subscribers/create` — the end user who will own the number
  </Step>

  <Step title="Provision Number">
    `POST /v1.0/numbers/provision` — assign the number to the Subscriber and Account

    Save the `PhoneNumberAssigned` (MSISDN) and `PhoneNumberId` (TNID).
  </Step>

  <Step title="Create Subscription">
    `POST /v1.0/subscriptions` — links the Subscriber + Number + Package and starts billing
  </Step>
</Steps>

***

<Check>
  **Phase complete when:** First production message has flowed both directions, monitoring is live, and the escalation path is written down.
</Check>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding/phase-3" title="Previous: Phase 3 — API Walkthrough & Testing">
    Sandbox testing sign-off
  </Card>

  <Card icon="arrow-right" href="/onboarding/phase-5" title="Next: Phase 5 — Post-launch">
    First 30 days stabilization
  </Card>
</CardGroup>


# Phase 5 — Post-launch
Source: https://docs.telegent.com/onboarding/phase-5

Stabilize, confirm CDRs and billing are accurate, and capture anything to fix in the first 30 days.

**Goal:** Stabilize, confirm CDRs and billing are accurate, and capture anything to fix in the first 30 days.

***

## Checklist

| # | Task                                                                                             | Owner   | Notes |
| - | ------------------------------------------------------------------------------------------------ | ------- | ----- |
| 1 | Partner following the [changelog](/changelog) and subscribed to the release-notes Slack channel. | Partner | —     |
| 2 | CDRs delivering at agreed cadence (hourly today, 15-minute cadence in flight).                   | Partner | —     |
| 3 | First-month billing reviewed against partner-side usage records.                                 | Joint   | —     |
| 4 | Open-issue list reviewed.                                                                        | Joint   | —     |
| 5 | 30-day retro held — what worked, what to fix.                                                    | Joint   | —     |

***

<Check>
  **Phase complete when:** Partner is independently operating, CDRs reconcile, and the relationship has moved from onboarding to steady-state support.
</Check>

***

<Note>
  After Phase 5, ongoing support moves to the Freshdesk ticket queue. For urgent issues, use the escalation path documented in Phase 4.
</Note>

***

<CardGroup>
  <Card icon="arrow-left" href="/onboarding/phase-4" title="Previous: Phase 4 — Production Cutover">
    First live number and go-live sign-off
  </Card>

  <Card icon="puzzle-piece" href="/onboarding/add-ons" title="Conditional Add-ons">
    A2P, IoT, and Static IP configuration
  </Card>
</CardGroup>


# Postman Collection
Source: https://docs.telegent.com/postman/index

Download the full Telegent mPaaS API collection and start testing in Postman in minutes.

The Telegent mPaaS Postman Collection gives you all 147 API endpoints pre-configured and organized, so you can authenticate and start making real API calls without writing a single line of code.

<a href="/public/telegent-postman-collection.json">
  ↓ Download Postman Collection
</a>

***

## What's included

* **147 endpoints** across 16 folders — Numbers, Message, Voice, Accounts, Subscribers, Distributors, and more
* **Bearer auth pre-configured** at the collection level — set your token once and every request inherits it
* **Pre-filled request bodies** pulled directly from the API spec so you're not starting from scratch
* **Environment variable placeholders** — `{{base_url}}` and `{{token}}` ready to fill in

***

## How to import

<Steps>
  <Step title="Download the collection">
    Click the **Download Postman Collection** button above. Your browser will save `telegent-postman-collection.json` to your machine.
  </Step>

  <Step title="Import into Postman">
    Open Postman, click **Import** (top left), then drag and drop the downloaded file or click **Upload Files** to select it. The collection will appear in your sidebar under **Collections**.
  </Step>

  <Step title="Create an environment">
    In Postman, go to **Environments → Add** and create a new environment with these two variables:

    | Variable   | Value                                              |
    | ---------- | -------------------------------------------------- |
    | `base_url` | `https://api.telegent.com/v1.0`                    |
    | `token`    | Your Bearer token from the Authentication endpoint |

    Select the environment from the dropdown in the top right corner.
  </Step>

  <Step title="Get your Bearer token">
    Before calling any other endpoint, run the **Get Token** request in the **OAuth2** folder. Use your `AccountKey` and `AccountSecret` as the request body. Copy the token from the response and paste it into your `token` environment variable.
  </Step>

  <Step title="Make your first call">
    You're ready. Open any folder, select an endpoint, and hit **Send**. All requests will automatically use your `base_url` and `token`.
  </Step>
</Steps>

***

## Keeping the collection up to date

The collection is regenerated automatically whenever the API spec is updated. To get the latest version, simply return to this page and download again — then re-import into Postman using the same steps above.

<Note>
  Need help or have questions? Contact [support@telegent.com](mailto:support@telegent.com)
</Note>


# Appendix
Source: https://docs.telegent.com/resources/appendix

ID glossary and common error reference for the Telegent API.

## ID Glossary

Every ID in Telegent has a prefix that tells you exactly what it refers to. When you see an unknown ID in a payload or error message, look it up here first.

| ID             | Resource       | How it's created                                                      |
| -------------- | -------------- | --------------------------------------------------------------------- |
| `AID`          | Account        | `POST /v1.0/account/create`                                           |
| `TSUID`        | Subscriber     | `POST /v1.0/subscribers/create`                                       |
| `MRID`         | Message Route  | `POST /v1.0/message/routes` — required to provision numbers           |
| `CRID`         | Voice Route    | `POST /v1.0/voice/routes` — required if `VoiceEnabled`                |
| `PID`          | Product        | `POST /v1.0/products` — smallest billable unit, bundled into Packages |
| `PKID`         | Package        | `POST /v1.0/packages` — a bundle of Products sold at one price        |
| `NID` / `TNID` | Phone Number   | `POST /v1.0/numbers/provision` or `/numbers/portin`                   |
| `ICCID`        | SIM            | Physical SIM or eSIM identifier — optional on most calls              |
| `CFID`         | Call Filter    | Per-subscriber Guardian call-filter record                            |
| `MFID`         | Message Filter | Per-subscriber Guardian message-filter record                         |

<Info>
  `PRID` and `PIID` also appear in some endpoints (Phone Rate ID, Product Item ID). For their exact meaning and where they apply, see [docs.telegent.com](https://docs.telegent.com) — the spec is the source of truth.
</Info>

***

## Common Errors

| Error                               | Area         | Resolution                                                                                                                          |
| ----------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `401`                               | Auth         | Bearer token expired, or the token's `ApiEndpoint` scope doesn't match the URL you called. Generate a fresh, endpoint-scoped token. |
| `MessageRouteId required`           | Routes       | You skipped Phase 4. Create an MRID before `/numbers/provision`.                                                                    |
| `Email already exists`              | Subscribers  | Subscriber emails are unique platform-wide. Pick a different one.                                                                   |
| `Invalid AccountId`                 | Account      | AID typo or you used a sandbox AID against production. Verify with your rep.                                                        |
| `NumberType / MessageType mismatch` | Provisioning | `iot` = p2p only; `voip` = a2p only. Use `mvno` for a2p on a mobile line.                                                           |

***

<CardGroup>
  <Card icon="arrow-left" href="/resources/reference" title="Back to Reference">
    Full request/response payloads and field tables
  </Card>

  <Card icon="code" href="/api-reference/introduction" title="API Reference">
    Full OpenAPI spec with interactive playground
  </Card>
</CardGroup>


# MVNO Guide Overview
Source: https://docs.telegent.com/resources/index

A clean, end-to-end flow for provisioning subscribers, numbers, packages, data limits, and AI Guardian.

## Overview

This guide is your companion to the Telegent API. It covers the full provisioning lifecycle — from authentication through AI Guardian — written specifically for MVNOs building on the Telegent mPaaS platform.

<Note>
  **What this guide covers:**

  * A Quick Start summary of the seven provisioning phases in order
  * A deep-dive reference for each phase with request/response payloads, field tables, and gotchas
  * An appendix with the full ID glossary and common errors

  **Base URL:** `https://api.telegent.com/v1.0`
  **Full API Reference:** [docs.telegent.com](https://docs.telegent.com)
  **Postman:** Telegent Core APIs.json (provided by your rep)
</Note>

<Info>
  **How to read this guide**

  The Quick Start below tells you what to do and in what order. The [Reference](/resources/reference) gives you the request and response payloads, field tables, and gotchas for each phase. If you ever see an ID name you don't recognize (PRID, PID, PIID, MRID, CRID), check the [Appendix](/resources/appendix) or docs.telegent.com.
</Info>

***

## Quick Start Flow

Seven short phases, in order, that take an MVNO from zero to a live, billable subscriber on a Telegent-provisioned number. Each phase links to its deep-dive in the Reference.

<img alt="The Provisioning Flow — seven boxes in a horizontal sequence grouped into three stages: Set up (Account, Subscribers, Routes), Define what you sell (Products/Packages, Subscription), and Light up the line (Provision/Port, Data Limits + Guardian)" />

<Steps>
  <Step title="Phase 1 — Authenticate">
    Trade your `AccountKey` and `AccountSecret` for a short-lived Bearer token, scoped to a specific endpoint URL.

    → [Section 1 — Authentication](/resources/reference#1-authentication)
  </Step>

  <Step title="Phase 2 — Account">
    Create the Account. An Account is a family or a business — it sits under a Distributor, which sits under the Aggregator. Every Subscriber and every Number you provision lives under exactly one Account.

    → [Section 2 — Account](/resources/reference#2-account)
  </Step>

  <Step title="Phase 3 — Subscribers and Roles">
    Create the Manager and Subscribers under the Account. One Manager per Account is the convention; Subscribers can hold one or many Numbers each. Every Number must be assigned to both an Account and a Subscriber.

    → [Section 3 — Subscribers and Roles](/resources/reference#3-subscribers-and-roles)
  </Step>

  <Step title="Phase 4 — Message Route and Voice Route">
    Set up where SMS lands (MRID) and where calls go (CRID). Numbers cannot be provisioned without a Message Route. Voice Route is required only if you are offering voice.

    → [Section 4 — Routes](/resources/reference#4-routes-message-and-voice)
  </Step>

  <Step title="Phase 5 — Products, Packages, Subscriptions">
    Define what you sell (Products), bundle them into Packages, and tie a Package to a Subscriber with a Subscription. Telegent can pre-load common Products (eSIM, data plans) to get you started — ask your rep.

    → [Section 6 — Products and Packages](/resources/reference#6-products-and-packages)
    → [Section 7 — Subscriptions](/resources/reference#7-subscriptions)
  </Step>

  <Step title="Phase 6 — Provision or Port a Number">
    Either provision a brand-new mobile, IoT, or VoIP number, or port one in from another carrier. Port-ins are a multi-step lifecycle — eligibility, submit, update, cancel, and monitor — that can stay open for days while the losing carrier responds. When a subscriber leaves, issue a port-out PIN so the gaining carrier can complete the transfer.

    → [Section 5 — ICCID](/resources/reference#5-iccid-when-to-use-it)
    → [Section 8 — Provisioning or Porting](/resources/reference#8-provisioning-or-porting)
  </Step>

  <Step title="Phase 7 — Data Usage and AI Guardian">
    Set notify, throttle, and hard-limit thresholds per number. Enable AI Guardian per subscriber for allow-list / block-list control on SMS and Voice, plus SMS-only filter levels (CHILD / ADOLESCENT / TEENAGER).

    → [Section 9 — Data Usage](/resources/reference#9-data-usage-limits-and-thresholds)
    → [Section 10 — AI Guardian](/resources/reference#10-ai-guardian-allow-block-filter-levels)
  </Step>
</Steps>

***

## What's Next?

<CardGroup>
  <Card icon="book-open" href="/resources/reference" title="Comprehensive Reference">
    Full request/response payloads, field tables, and gotchas for all 10 sections
  </Card>

  <Card icon="list" href="/resources/appendix" title="Appendix">
    ID glossary and common error reference
  </Card>

  <Card icon="code" href="/api-reference/introduction" title="API Reference">
    Full OpenAPI spec with interactive playground
  </Card>

  <Card icon="rocket" href="/onboarding" title="Partner Onboarding">
    Step-by-step onboarding plan for new partners
  </Card>
</CardGroup>


# Comprehensive Reference
Source: https://docs.telegent.com/resources/reference

Full request/response payloads, field tables, and gotchas for all 10 API sections.

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`

<CodeGroup>
  ```json Request theme={null}
  {
    "AccountKey": "YOUR_ACCOUNT_KEY",
    "AccountSecret": "YOUR_ACCOUNT_SECRET",
    "ApiEndpoint": "https://api.telegent.com/v1.0/numbers/provision"
  }
  ```

  ```json Response theme={null}
  {
    "token": "abcdefghi.................",
    "successful": true,
    "tokenExpiry": "05/02/2026 06:36:13 PM"
  }
  ```
</CodeGroup>

Once you have a token, add this header to every subsequent request:

```
Authorization: Bearer YOUR_TOKEN
```

<Tip>
  **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.
</Tip>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "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
    }
  }
  ```

  ```json Response theme={null}
  {
    "AccountId": "AID-ceb82085-2725-45a1-bd5e-526ed19799d7",
    "AccountName": "Acme MVNO",
    "TotalSubscribers": 0,
    "BillingAddress": { "..." : "..." },
    "MailingAddress": { "..." : "..." }
  }
  ```
</CodeGroup>

### Parameters worth knowing

| Field            | Type   | Description                                                                             |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `AccountName`    | string | Display name — the name of the family or business. Visible on invoices and reports.     |
| `AccountAdmin`   | string | Email of the Manager. They receive billing and system notices for the whole Account.    |
| `BillingAddress` | object | Required for invoicing. Set `Country = USA` unless you're an international Distributor. |
| `MailingAddress` | object | Optional. Leave fields null if same as Billing.                                         |

<Warning>
  **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.
</Warning>

<Note>
  **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.
</Note>

***

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

| Role              | Description                                                                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscriber**    | End user. Holds one or more Numbers, a Subscription, and (optionally) Guardian filters. Cannot administer the Account.                               |
| **Manager**       | The steward of the Account — typically one per Account. Manages Subscribers, Subscriptions, Guardian filters, and data limits within their Account.  |
| **Account Admin** | Administrative role at the Account level. Can configure routes, manage Packages, update billing info. Use sparingly; Distributors usually hold this. |

<Info>
  **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.
</Info>

**Endpoint:** `POST /v1.0/subscribers/create`

<CodeGroup>
  ```json Request theme={null}
  {
    "Name": "Jane Doe",
    "Email": "jane@example.com",
    "PhoneNumbers": ["+18015551234"],
    "Role": "Subscriber",
    "Password": "set-a-secure-default",
    "AccountId": "AID-…"
  }
  ```

  ```json Response theme={null}
  {
    "SubscriberId": "TSUID-90c644ff-7f70-4587-a27e-d1d45bde7528",
    "Name": "Jane Doe",
    "Email": "jane@example.com",
    "PhoneNumbers": ["+18015551234"],
    "Role": "Subscriber",
    "Account": {
      "AccountId": "AID-…",
      "CompanyName": "Acme MVNO"
    }
  }
  ```
</CodeGroup>

### Parameters worth knowing

| Field          | Type      | Description                                                                |
| -------------- | --------- | -------------------------------------------------------------------------- |
| `Name`         | string    | Required. Free-text display name.                                          |
| `Email`        | string    | Required. Must be unique across the entire platform.                       |
| `PhoneNumbers` | string\[] | Required. E.164 format. Can be empty array on create, then assigned later. |
| `Role`         | enum      | `Subscriber` \| `Manager` \| `Account Admin`                               |
| `Password`     | string    | Required at create. Issue a temp value and force a reset on first login.   |
| `AccountId`    | string    | Required. The AID this subscriber belongs to.                              |

<Warning>
  **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.
</Warning>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "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-…"
  }
  ```

  ```json Response theme={null}
  {
    "MessageRouteId": "MRID-ad0ff867-57dc-4aeb-80e9-9d18349080e9",
    "AccountId": "AID-…",
    "RouteName": "Main SMS Webhook",
    "MessageUrl": "https://yourapi.example.com/inbound-sms",
    "MessageUrlMethod": "POST",
    "MessageRouteEnabled": true,
    "MessageAuthenticationType": "Basic",
    "MessageUsername": "admin",
    "CallbackMessageUrl": "https://yourapi.example.com/sms-status",
    "CallbackMessageUrlMethod": "POST",
    "CallbackMessageAuthenticationType": "Basic",
    "InboundBypass": false,
    "OutboundBypass": false,
    "IntelligentRouteEnabled": true
  }
  ```
</CodeGroup>

<Check>
  Save the `MessageRouteId` (MRID) — you will need it on every number provision call.
</Check>

### 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`.

<CodeGroup>
  ```json Request theme={null}
  {
    "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-…"
  }
  ```

  ```json Response theme={null}
  {
    "CallRouteId": "CRID-509de94f-79cc-429b-a317-2102654dabbb",
    "AccountId": "AID-…",
    "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,
    "IntelligentRouteEnabled": true,
    "RouteEnabled": true,
    "IpWhiteList": []
  }
  ```
</CodeGroup>

<Check>
  Save the `CallRouteId` (CRID) for voice-enabled provisioning.
</Check>

### Parameters worth knowing

| Field                     | Type   | Description                                                            |
| ------------------------- | ------ | ---------------------------------------------------------------------- |
| `MessageUrl`              | string | Where inbound SMS/MMS payloads are delivered.                          |
| `CallbackMessageUrl`      | string | Where delivery receipts and status callbacks are delivered.            |
| `TrunkIp1` / `Uri1`       | string | Primary SIP endpoint. Configure two trunks (1 + 2) for failover.       |
| `IntelligentRouteEnabled` | bool   | Turn this on to enable AI Guardian + intelligent routing on the route. |
| `AccountId`               | string | Conditional: required when a Distributor manages multiple Accounts.    |

<Note>
  **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.
</Note>

### 4.3 Receiving Events — Webhook Payloads

Once you register a webhook via `POST /v1.0/webhook/create`, Telegent POSTs a JSON body to your `Url` each time a subscribed event fires. The body shape depends on which event you subscribed to (`Order_Update`, `New_Sms`, `Call_Completed`, and so on). For an `Order_Update`, the payload looks like:

<CodeGroup>
  ```json Order_Update payload theme={null}
  {
    "OrderId": "JNUOID-6c058364-66a7-485b-93e1-7a2aa75e4fed",
    "Status": "Complete",
    "ErrorMessage": ""
  }
  ```
</CodeGroup>

| Field          | Type   | Description                                                                                                       |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `OrderId`      | string | The `JNUOID-…` of the affected order. Match this against the `OrderId` you saved at submit time.                  |
| `Status`       | string | New order status, e.g. `Submitted`, `Pending Carrier Approval`, `Scheduled`, `Complete`, `Rejected`, `Cancelled`. |
| `ErrorMessage` | string | Populated when the order fails or is rejected; empty otherwise.                                                   |

<Note>
  **Authentication on your endpoint.** The same auth options as Routes apply — Telegent supports Basic and Bearer on the webhook `Url`, set via the auth fields on `POST /v1.0/webhook/create`. Use HTTPS, and acknowledge with a `2xx` quickly so the delivery is not retried.
</Note>

***

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

<Note>
  **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.
</Note>

<CardGroup>
  <Card icon="check" title="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
  </Card>

  <Card icon="xmark" title="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
  </Card>
</CardGroup>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "SKU": "eSim",
    "Description": "Telegent eSim",
    "Type": "esim",
    "SubType": "esim",
    "Cost": 12.34,
    "BillingFrequency": "MRC"
  }
  ```

  ```json Response theme={null}
  {
    "ProductId": "PRID-4384E69B-3194-9943-F839-20E477C8E399",
    "SKU": "eSim",
    "Description": "Telegent eSim",
    "Type": "esim",
    "SubType": "esim",
    "Cost": 12.34,
    "BillingFrequency": "MRC",
    "Active": true
  }
  ```
</CodeGroup>

| Field              | Type   | Description                                                                                          |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `SKU`              | string | Your internal stock-keeping code. Keep it stable; reports key off this.                              |
| `Type` / `SubType` | string | Product family (`esim`, `data`, `sms`, `feature`, etc.). See docs.telegent.com for the current enum. |
| `Cost`             | number | Wholesale cost to you. Pricing to the subscriber lives on the Package.                               |
| `BillingFrequency` | string | `MRC` (monthly), `NRC` (one-time), or usage-based. Drives invoicing cadence.                         |

<Tip>
  **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.
</Tip>

### 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`.

<CodeGroup>
  ```json Request theme={null}
  {
    "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"  }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "PackageId": "PID-23bf4d8d-14bf-431b-88a4-9a214a87b58a",
    "PackageName": "Family 10GB",
    "Description": "10GB data + unlimited SMS",
    "Type": "sip",
    "Price": 39.99,
    "Monthly": true,
    "Active": true
  }
  ```
</CodeGroup>

### Adding items after the fact

If you need to add an item to an existing Package without rebuilding it:

**Endpoint:** `POST /v1.0/packages/items/add`

<CodeGroup>
  ```json Request theme={null}
  {
    "PackageId": "PKID-…",
    "ProductId": "PID-…",
    "Price": "1.12",
    "Monthly": false,
    "Type": "addon"
  }
  ```

  ```json Response theme={null}
  {
    "PackageItemId": "PIID-4efee842-16f0-4803-9780-8c3c30d19b74",
    "PackageId": "PKID-…",
    "Type": "addon",
    "Price": 1.12,
    "Monthly": false,
    "Active": true
  }
  ```
</CodeGroup>

<Tip>
  **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.
</Tip>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "TNID":  "NID-…",
    "ICCID": "8901240397190002080",
    "PackageId": "PKID-…",
    "Type": "Voip"
  }
  ```

  ```json Response theme={null}
  {
    "SubscriptionId": "SUB-ef84c0b5-d750-4a5a-99b1-4705089cd20c",
    "SubscriberId": "TSUID-…",
    "TNID": "NID-…",
    "ICCID": "8901240397190002080",
    "PackageId": "PKID-…",
    "Type": "Voip",
    "Active": true
  }
  ```
</CodeGroup>

### Parameters worth knowing

| Field          | Type   | Description                                                                   |
| -------------- | ------ | ----------------------------------------------------------------------------- |
| `SubscriberId` | string | TSUID from Section 3.                                                         |
| `TNID`         | string | The number identifier issued by `/numbers/provision` or `/numbers/portin`.    |
| `ICCID`        | string | Optional. Bind the SIM to this Subscription.                                  |
| `PackageId`    | string | PKID from Section 6.2.                                                        |
| `Type`         | string | `Voip`, `Mvno`, `Iot` — must match the kind of number the Subscription is on. |

<Note>
  **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.
</Note>

***

## 8. Provisioning or Porting

<Warning>
  **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.
</Warning>

### 8.1 Provision a brand-new number

**Step 1 — Check availability:**

Before committing to a provision, confirm that inventory exists in your target area. Pass the number type and capabilities you need along with an `AreaCode` or `ZipCode`. The response returns `AvailableNumberAreas` — a list of `NGP` code and `AreaCode` pairs that have live inventory. Pick the `NGP` and `AreaCode` you want and carry them into Step 2. Use `PageNumber` to paginate if your preferred area code doesn't appear on the first page.

**Endpoint:** `POST /v1.0/numbers/availability`

<CodeGroup>
  ```json Request theme={null}
  {
    "NumberType": "mobile",
    "MessageType": "p2p",
    "MessageEnabled": true,
    "VoiceEnabled": true,
    "PageNumber": 1,
    "AreaCode": "201",
    "ZipCode": ""
  }
  ```

  ```json Response theme={null}
  {
    "RequestId": "T-04139",
    "RequestDate": "2025-05-14T18:37:18.2408767Z",
    "NumberType": "mobile",
    "VoiceEnabled": true,
    "MessageEnabled": true,
    "AreaCode": "201",
    "PageNumber": 1,
    "ResultsTotal": 7700,
    "AvailableNumberAreas": [
      { "NGP": "SAG", "AreaCode": 201, "Zipcode": "07001" },
      { "NGP": "AGP", "AreaCode": 201, "Zipcode": "07002" }
    ]
  }
  ```
</CodeGroup>

**Step 2 — Provision:**

Once you have an available area, purchase and activate the number. Supply the `MessageRouteId` (MRID) and `VoiceRouteId` (CRID) from Section 4 and the `AreaCode` from Step 1. Set `ProductType` to match the capabilities you want on the line — `sms+data+voice` for a full MVNO line, `data-only` for IoT. The response returns `PhoneNumberId` (the `NID-` identifier) and `PhoneNumberAssigned` (the E.164 number) — save both. `NID` is what you'll reference in subscriptions, data usage settings, and route updates.

**Endpoint:** `POST /v1.0/numbers/provision`

<CodeGroup>
  ```json Request theme={null}
  {
    "NumberType": "mvno",
    "MessageType": "p2p",
    "MessageEnabled": true,
    "VoiceEnabled": true,
    "DataEnabled": true,
    "MessageRouteId": "MRID-…",
    "VoiceRouteId": "CRID-…",
    "AreaCode": "201",
    "ICCID": "8901240397190195850",
    "ProductType": "sms+data+voice",
    "AssignedSubscriberId": "TSUID-…",
    "AccountId": "AID-…"
  }
  ```

  ```json Response theme={null}
  {
    "OrderDate": "2025-10-29T12:36:19.338438+00:00",
    "OrderId": "JNUOID-76ba71a8-d7a6-4489-b695-1ad363b8d596",
    "OrderStatus": "Complete",
    "PhoneNumberAssigned": "+12015551234",
    "PhoneNumberId": "NID-8bdf915a-ef65-46c9-8c66-96c98d42d9ca",
    "ICCID": "8901240397190195850",
    "SubscriberId": "TSUID-…",
    "ErrorMessage": null
  }
  ```
</CodeGroup>

<Note>
  **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"`.
</Note>

### 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:**

<CodeGroup>
  ```json Request theme={null}
  {
    "PhoneNumber": "+13136398786",
    "TargetClassification": "mvno"
  }
  ```

  ```json Response theme={null}
  {
    "PhoneNumber": "+13136398786",
    "Eligible": true,
    "CurrentCarrier": "Verizon",
    "NumberType": "mobile",
    "Message": "Number is eligible for port-in"
  }
  ```
</CodeGroup>

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:**

<CodeGroup>
  ```json Request theme={null}
  {
    "PortInNumber": "+15555551234",
    "ICCID": "8901240397190195850",
    "CurrentCarrierName": "Verizon",
    "CurrentAccountNumber": "46512222",
    "CurrentAccountPassword": "0000",
    "TargetPortinClassification": "mvno",
    "SubscriberName": "Jane Doe",
    "CurrentBillingAddress": {
      "Street1": "2701 N Thanksgiving Way",
      "Street2": "Suite 202",
      "City": "Lehi",
      "State": "UT",
      "Zip": "84043"
    }
  }
  ```

  ```json Response theme={null}
  {
    "OrderId": "JNUOID-6c058364-66a7-485b-93e1-7a2aa75e4fed",
    "OrderDate": "2025-05-14T18:00:00.0000000+00:00",
    "Status": "Pending",
    "PhoneNumber": "+15555551234",
    "ICCID": "8901240397190195850"
  }
  ```
</CodeGroup>

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.

<CodeGroup>
  ```json Request theme={null}
  {
    "OrderId": "JNUOID-6c058364-66a7-485b-93e1-7a2aa75e4fed",
    "CurrentCarrierName": "Sinch",
    "SubscriberName": "Jane Doe",
    "CurrentAccountNumber": "7617",
    "CurrentAccountPassword": "0813",
    "PortInDate": "04/23/2026",
    "CurrentBillingAddress": {
      "Street1": "2701 N Thanksgiving Way",
      "Street2": "",
      "City": "Lehi",
      "State": "UT",
      "Zip": "84043"
    }
  }
  ```

  ```json Response theme={null}
  {
    "OrderId": "JNUOID-6c058364-66a7-485b-93e1-7a2aa75e4fed",
    "Status": "Updated",
    "Message": "Port-in order updated successfully"
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```json Request theme={null}
  {
    "OrderId": "JNUOID-6e3eb213-baf1-47bb-9db0-5d7d09d4b7b4"
  }
  ```

  ```json Response theme={null}
  {
    "OrderId": "JNUOID-6e3eb213-baf1-47bb-9db0-5d7d09d4b7b4",
    "Status": "Cancelled"
  }
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>

**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
```

```json Response theme={null}
{
  "OrderDate": "2025-12-08T00:12:08.89",
  "OrderId": "JNUOID-19b3d376-2440-477f-a3dc-c91a36989316",
  "OrderStatus": "Completed",
  "OrderType": "portin",
  "PhoneNumbersOrdered": [
    { "Number": "+15555551234" }
  ]
}
```

<Tip>
  **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.
</Tip>

### 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:

<CodeGroup>
  ```json Request theme={null}
  {
    "PortOutNumber": "+17746996223",
    "PortOutPIN": "1234"
  }
  ```

  ```json Response theme={null}
  {
    "OrderId": "JNUOID-dabada8a-b621-4c99-8ef3-9c79254e30b1",
    "OrderDate": "2025-05-14T18:00:00.0000000+00:00",
    "Status": "Pending",
    "PhoneNumber": "+17746996223"
  }
  ```
</CodeGroup>

<Note>
  **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.
</Note>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "ValueUnit": "MB",
    "NotifyValue": 8,
    "ThrottleValue": 10,
    "ThrottleSpeed": "1-mbps",
    "LimitValue": 15,
    "PhoneNumbers": [
      { "Number": "+12016093801" },
      { "Number": "+12232233180" }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "Status": "Complete",
    "StatusMessage": "",
    "ValueUnit": "MB",
    "NotifyValue": 8,
    "ThrottleValue": 10,
    "ThrottleSpeed": "1-mbps",
    "LimitValue": 15,
    "PhoneNumbers": [
      { "Number": "+12016093801" },
      { "Number": "+12232233180" }
    ]
  }
  ```
</CodeGroup>

### Parameters worth knowing

| Field           | Type   | Description                                                                                                         |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `ValueUnit`     | enum   | `MB`. Applies to all three thresholds.                                                                              |
| `NotifyValue`   | number | Subscriber is notified when usage hits this value.                                                                  |
| `ThrottleValue` | number | Speed is throttled to `ThrottleSpeed` once usage hits this value.                                                   |
| `ThrottleSpeed` | enum   | `64-kbps` \| `128-kbps` \| `256-kbps` \| `512-kbps` \| `1-mbps` \| `5-mbps` \| `20-mbps` \| `50-mbps` \| `100-mbps` |
| `LimitValue`    | number | Hard cap. Data is cut off (or charged overage, depending on plan) past this.                                        |
| `PhoneNumbers`  | array  | One or many numbers. The same thresholds apply to every number in the array.                                        |

<Info>
  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.
</Info>

<Note>
  Tether/hotspot throttling is not configurable. The `Throttle` threshold above applies to overall data usage on the number — there is no separate knob to throttle or cap tethering/hotspot traffic independently.
</Note>

***

## 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`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "EnableIntelligentGuardianCalls": true,
    "EnableIntelligentGuardianMessages": true
  }
  ```

  ```json Response theme={null}
  {
    "SubscriberId": "TSUID-…",
    "EnableIntelligentGuardianCalls": true,
    "EnableIntelligentGuardianMessages": true
  }
  ```
</CodeGroup>

<Info>
  `GET /v1.0/subscribers/guardian-features?SubscriberId=TSUID-…` returns the current flags so your UI can render checkbox state.
</Info>

### 10.2 Voice — Allow / Block only

**Endpoint:** `POST /v1.0/subscribers/call-filter`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "Phone": "+18015551234",
    "AllowedNumbers": ["+18015550001", "+18015550002"],
    "BlockedNumbers": ["+18015559999"]
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "CFID-05c3d6d2-21c2-4fab-8c7c-12746cad1499",
    "SubscriberId": "TSUID-…",
    "Phone": "+18015551234",
    "AllowedNumbers": ["+18015550001", "+18015550002"],
    "BlockedNumbers": ["+18015559999"],
    "ApplyToInbound": true,
    "ApplyToOutbound": true,
    "BlockUnknownNumbers": false,
    "BlockInternational": false
  }
  ```
</CodeGroup>

Manage entries incrementally:

**Endpoint:** `POST /v1.0/subscribers/call-filter/allowed-numbers/add`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "CallFilterId": "CFID-…",
    "Numbers": ["+15555555555"]
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "CFID-05c3d6d2-21c2-4fab-8c7c-12746cad1499",
    "SubscriberId": "TSUID-…",
    "AllowedNumbers": ["+18015550001", "+18015550002", "+15555555555"]
  }
  ```
</CodeGroup>

**Endpoint:** `POST /v1.0/subscribers/call-filter/blocked-numbers/add`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "CallFilterId": "CFID-…",
    "Numbers": ["+15555556666"]
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "CFID-05c3d6d2-21c2-4fab-8c7c-12746cad1499",
    "SubscriberId": "TSUID-…",
    "BlockedNumbers": ["+18015559999", "+15555556666"]
  }
  ```
</CodeGroup>

<Warning>
  **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.
</Warning>

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

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "Phone": "+18015551234",
    "FilterMode": "ACTIVE",
    "AllowedContacts": ["+18015550001"],
    "BlockedContacts": ["+18015559999"],
    "ApplyToInbound": true,
    "ApplyToOutbound": true,
    "BlockLinks": true,
    "BlockMedia": true
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "MFID-7435d672-a2d0-451e-ab62-45499f5bc7a1",
    "SubscriberId": "TSUID-…",
    "Phone": "+18015551234",
    "FilterMode": "ACTIVE",
    "AllowedContacts": ["+18015550001"],
    "BlockedContacts": ["+18015559999"],
    "ApplyToInbound": true,
    "ApplyToOutbound": true,
    "BlockLinks": true,
    "BlockMedia": true,
    "BlockUnknownNumbers": false
  }
  ```
</CodeGroup>

Manage lists incrementally:

**Endpoint:** `POST /v1.0/subscribers/message-filter/allowed-contacts/add`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "MessageFilterId": "MFID-…",
    "Contacts": ["+15555555555"]
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "MFID-7435d672-a2d0-451e-ab62-45499f5bc7a1",
    "SubscriberId": "TSUID-…",
    "AllowedContacts": ["+18015550001", "+15555555555"]
  }
  ```
</CodeGroup>

**Endpoint:** `POST /v1.0/subscribers/message-filter/blocked-contacts/add`

<CodeGroup>
  ```json Request theme={null}
  {
    "SubscriberId": "TSUID-…",
    "MessageFilterId": "MFID-…",
    "Contacts": ["+15555556666"]
  }
  ```

  ```json Response theme={null}
  {
    "FilterId": "MFID-7435d672-a2d0-451e-ab62-45499f5bc7a1",
    "SubscriberId": "TSUID-…",
    "BlockedContacts": ["+18015559999", "+15555556666"]
  }
  ```
</CodeGroup>

### SMS Filter Levels

| Level        | Description                                                                     |
| ------------ | ------------------------------------------------------------------------------- |
| `CHILD`      | Most restrictive. Strong blocking on adult content, links, and unknown senders. |
| `ADOLESCENT` | Moderate. Blocks the worst categories but allows most everyday messaging.       |
| `TEENAGER`   | Lightest of the three. Filters extreme content; otherwise hands-off.            |

***

***

## 11. Error Codes

Every Telegent API response includes an HTTP status code. The table below covers every code the platform returns, what it means, and the most common cause.

| Code  | Name                | Meaning                                                                                                                                                                           |
| ----- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Success             | The request was accepted and processed. The response body contains the result.                                                                                                    |
| `400` | Bad Request         | The request payload is malformed, missing a required field, or contains an invalid value. Check the response body for details on which field failed validation.                   |
| `401` | Unauthorized        | No Bearer token was provided, or the token is expired or invalid. Re-authenticate via `POST /v1.0/oauth2/tokens` and retry with a fresh token.                                    |
| `403` | Forbidden           | The token is valid but does not have permission to perform this action. This is most often a scope mismatch — the token was issued for a different `ApiEndpoint`.                 |
| `404` | Not Found           | The resource identified by the ID in your request does not exist, or it belongs to a different Account. Verify the ID and the `AccountId`.                                        |
| `405` | Method Not Allowed  | You used the wrong HTTP method for this endpoint (e.g. `GET` on a `POST`-only route). Check the endpoint definition in the API Reference.                                         |
| `408` | Request Timeout     | The server did not receive a complete request within the timeout window. This is typically a network issue — retry with exponential backoff.                                      |
| `429` | Too Many Requests   | Your account has exceeded the rate limit. Slow your request cadence and wait before retrying. The response may include a `Retry-After` header.                                    |
| `500` | Server Error        | An unexpected error occurred on the Telegent platform. If the error persists, contact [support@telegent.com](mailto:support@telegent.com) with the request details and timestamp. |
| `503` | Service Unavailable | The API is temporarily unavailable, typically during maintenance or a platform incident. Retry after a short delay.                                                               |
| `504` | Gateway Timeout     | An upstream service did not respond in time. Treat this the same as `408` — retry with backoff. If it recurs, check the Telegent status page.                                     |

<Tip>
  **Retry strategy.** For transient errors (`408`, `429`, `500`, `503`, `504`), implement exponential backoff — start at 1 second, double on each retry, and cap at 30 seconds. Do not retry `400`, `401`, `403`, or `404` automatically; those require a code or credential fix, not a retry.
</Tip>

***

<Note>
  This document is a living guide. When in doubt, the OpenAPI spec at [docs.telegent.com](https://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.
</Note>


# Elastic SIP Trunk Documentation
Source: https://docs.telegent.com/resources/sip-documentation

Use-case samples, PCAP snippets, and a reference guide for SIP INVITEs and expected header-handling behavior when interworking T-Mobile, Joonto SBC/OpenSIPS, and UC partners.

## Overview

The following provides specific use-case samples and examples of various SIP documentation, PCAP snippets, and reference guide for SIP INVITEs and expected header-handling behavior when interworking T-Mobile, Joonto SBC/OpenSIPS, and UC partners.

<Note>
  Telegent highly recommends sending the `Identity` header received from T-Mobile whenever possible. If an upstream partner does not provide the `Identity` header, the call should still be allowed to proceed, but may have potential for STIR/SHAKEN attestation issues.
</Note>

***

## Voice Origination – OTT

* The `Diversion` header allows an OTT call to not automatically be marked as scam likely on the T-Mobile network, because the call didn't originate on the device
* `PRACK` is required for T-Mobile to ring the device

### Inbound INVITE sample where no Identity header is passed to Telegent SBC

```text theme={null}
INVITE sip:+19087645402@13.83.167.165:5060 SIP/2.0
Via: SIP/2.0/UDP 137.192.80.69:5060;branch=z9hG4bKa3b9hn207o8hmq36oqj0.1
Max-Forwards: 69
From: <sip:+17328532203@137.192.80.69>;tag=06gN621vNF84F
To: <sip:+19087645402@13.83.167.165:5060>
Call-ID: d42edea3-7661-123f-989f-be10809469ca
CSeq: 110219115 INVITE
Contact: <sip:gw+rayo@137.192.80.69:5060;gw=rayo;transport=udp>
User-Agent: vp2-inteliquent
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, MESSAGE, INFO, UPDATE, REGISTER, REFER, NOTIFY
Supported: timer, path, replaces
Allow-Events: talk, hold, conference, refer
Content-Type: application/sdp
Content-Disposition: session
Content-Length: 394
Remote-Party-ID: "+17328532203" <sip:+17328532203@137.192.80.69>;party=calling;screen=yes;privacy=off
P-Asserted-Identity: <sip:+17328532203@137.192.80.69;user=phone>
Diversion: <sip:+19087645402@msg.pc.t-mobile.com>;reason=deflection
```

<Frame>
  <img alt="Voice Origination flow diagram: outbound voice originated with OTT, UC sends SIP traffic to Telegent mPaaS SBC, Telegent sends SIP traffic to Tmo iSBC, receiving device rings with Tmo MSISDN and Tmo STIR/SHAKEN token" />
</Frame>

***

## Voice Termination – Single SIM Device Endpoint

### Step 1: Inbound INVITE sent first to UC partner for inbound ringing with Identity header

```text theme={null}
INVITE sip:+14155837080@3.232.127.185 SIP/2.0
Via: SIP/2.0/UDP 13.83.167.160:5060;branch=z9hG4bKeade.3d49cb14.0
Max-Forwards: 62
From: <sip:+15302899128@13.83.167.160>;tag=as1eb30ca5
To: <sip:+14155837080@3.232.127.185>
Call-ID: 511cb1aa5180c4b84a1ab34e06988c55@12.7.192.27
CSeq: 102 INVITE
Contact: <sip:13.83.167.160;did=dde.45d132a2>
Supported: replaces
Allow: INVITE,ACK,CANCEL,OPTIONS,BYE,REFER,SUBSCRIBE,NOTIFY,INFO,PUBLISH,MESSAGE
P-Asserted-Identity: tel:+15302899128
Content-Type: application/sdp
Content-Length: 318
Session-Expires: 1800;refresher=uas
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9zdGlyLm5hNC5saXZldm94LmNvbS9jZXJ0L1I5ZmZsdGZMIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNDE1NTgzNzA4MCJdfSwiaWF0IjoxNzY5NTM2NTAxLCJvcmlnIjp7InRuIjoiMTUzMDI4OTkxMjgifSwib3JpZ2lkIjoiNGQxOGM4ODQtZmJhOS0xMWYwLWI1ZDEtMWJlMGJiM2QzMDkyIn0.yY88EdiWSNEig4loaAUqF6eqh0Z2J_H42AaIbtnhcwcvf7wGGi48DNG10QhCz-pSYkJbh5nQY9gLHd_hQ3llgQ;info=<https://stir.na4.livevox.com/cert/R9ffltfL>;alg=ES256;ppt="shaken"

v=0
o=ccs-0-303-11 0300111855943011 1470322392 IN IP4 13.83.167.160
s=CX-IVS-SBC
c=IN IP4 13.83.167.160
b=AS:80
b=RS:1000
b=RR:3000
t=0 0
m=audio 31562 RTP/AVP 0 101
b=AS:80
b=RS:1000
b=RR:3000
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=sendrecv
a=rtcp:31563
a=ptime:20
```

### Step 2: INVITE sent to Telegent SBC for ringing SIM device

* `PRACK` is required for T-Mobile to ring the device

```text theme={null}
INVITE sip:+14155837080@13.83.167.160:5060 SIP/2.0
Via: SIP/2.0/UDP 3.232.127.185:5060;rport;branch=z9hG4bKPjd861bc21-52a2-41fc-8f03-db9b6f353727
From: <sip:+15302899128@172.31.57.87>;tag=e7ffee04-82a3-421b-93ba-c6c0701eb71d
To: <sip:+14155837080@13.83.167.160>
Contact: <sip:asterisk@3.232.127.185:5060>
Call-ID: 427dd7b3-49bd-45b2-8525-e3030f3d0463
CSeq: 15418 INVITE
Allow: OPTIONS, REGISTER, SUBSCRIBE, NOTIFY, PUBLISH, INVITE, ACK, BYE, CANCEL, UPDATE, PRACK, MESSAGE, REFER
Supported: 100rel, timer, replaces, norefersub, histinfo
Session-Expires: 1800
Min-SE: 90
P-Asserted-Identity: <sip:+15302899128@172.31.57.87>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9zdGlyLm5hNC5saXZldm94LmNvbS9jZXJ0L1I5ZmZsdGZMIn0.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxNDE1NTgzNzA4MCJdfSwiaWF0IjoxNzY5NTM2NTAxLCJvcmlnIjp7InRuIjoiMTUzMDI4OTkxMjgifSwib3JpZ2lkIjoiNGQxOGM4ODQtZmJhOS0xMWYwLWI1ZDEtMWJlMGJiM2QzMDkyIn0.yY88EdiWSNEig4loaAUqF6eqh0Z2J_H42AaIbtnhcwcvf7wGGi48DNG10QhCz-pSYkJbh5nQY9gLHd_hQ3llgQ;info=<https://stir.na4.livevox.com/cert/R9ffltfL>;alg=ES256;ppt=shaken
Max-Forwards: 70
User-Agent: Asterisk PBX 18.10.0~dfsg+~cs6.10.40431411-2
Content-Type: application/sdp
Content-Length: 263

v=0
o=- 1032313863 1032313863 IN IP4 3.232.127.185
s=Asterisk
c=IN IP4 3.232.127.185
t=0 0
m=audio 17256 RTP/AVP 0 8 101
a=rtpmap:0 PCMU/8000
a=rtpmap:8 PCMA/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=maxptime:150
a=sendrecv
```

### Sample of above call scenario

<Frame>
  <img alt="Voice Termination flow diagram: inbound voice received, SIP traffic sent to UC SBC, UC sends SIP traffic back to Telegent SBC, Telegent sends SIP traffic to SIM device and terminates the call on the SIM device" />
</Frame>

***

## Voice Termination – Forked Device Example

### Step 1: Inbound INVITE sent first to UC partner for inbound ringing with Identity header

```text theme={null}
INVITE sip:+13852213180@104.42.190.204 SIP/2.0
Via: SIP/2.0/UDP 13.83.167.160:5060;branch=z9hG4bK1a78.87ff9873.0
Max-Forwards: 64
From: <sip:+12164015165@13.83.167.160>;tag=mavodi-__stsxvrswsxw__0-80-ad-7-0-70003-0-0-0-1766076149-_155985-bb2ec
To: <sip:+13852213180@104.42.190.204>
Call-ID: 0A58AC142435-cb5-dd85f700-aca53b-69442ef5-bb1ab
CSeq: 1 INVITE
Contact: <sip:13.83.167.160;did=a67.a4a089d7>
P-Early-Media: supported
Supported: path,replaces,100rel
Allow: ACK,BYE,CANCEL,INFO,INVITE,MESSAGE,NOTIFY,OPTIONS,PRACK,REFER,UPDATE
P-Asserted-Identity: <sip:+12164015165@172.57.117.36;user=phone>
Content-Type: application/sdp
Content-Length: 268
Session-Expires: 1800;refresher=uas
Identity: eyJhbGciOi... [truncated]
```

### Step 2: INVITE forked to alternate branch (e.g. SIM/OTT app)

```text theme={null}
INVITE sip:+13852213180@13.83.167.164 SIP/2.0
Via: SIP/2.0/UDP 13.83.167.160:5060;branch=z9hG4bK1a78.87ff9873.1
Max-Forwards: 64
From: <sip:+12164015165@13.83.167.160>;tag=mavodi-__stsxvrswsxw__0-80-ad-7-0-70003-0-0-0-1766076149-_155985-bb2ec
To: <sip:+13852213180@104.42.190.204>
Call-ID: 0A58AC142435-cb5-dd85f700-aca53b-69442ef5-bb1ab
CSeq: 1 INVITE
Contact: <sip:13.83.167.160;did=a67.a4a089d7>
P-Early-Media: supported
Supported: path,replaces,100rel
Allow: ACK,BYE,CANCEL,INFO,INVITE,MESSAGE,NOTIFY,OPTIONS,PRACK,REFER,UPDATE
P-Asserted-Identity: <sip:+12164015165@172.57.117.36;user=phone>
Content-Type: application/sdp
Content-Length: 268
Session-Expires: 1800;refresher=uas
Identity: eyJhbGciOi... [truncated]
```

<Frame>
  <img alt="Voice Termination forked flow diagram: inbound voice received, SIP traffic sent to UC SBC, UC sends SIP traffic back to Telegent SBC and rings OTT devices, Telegent sends SIP traffic to SIM device, and the call terminates on whichever device answers" />
</Frame>

<Info>
  If the OTT branch answers first, Telegent sends `CANCEL` to the other forked INVITE branch. This stops ringing on the remaining destination and behaves like standard simultaneous ringing.
</Info>

***

## Voice Termination – Body Example

### Body samples

```text theme={null}
Message Body
    Session Description Protocol
        Session Description Protocol Version (v): 0
        Owner/Creator, Session Id (o): ccs-0-303-3 030031921555243 768119725 IN IP4 13.83.167.165
            Owner Username: ccs-0-303-3
            Session ID: 030031921555243
            Session Version: 768119725
            Owner Network Type: IN
            Owner Address Type: IP4
            Owner Address: 13.83.167.165
        Session Name (s): -
        Connection Information (c): IN IP4 13.83.167.165
            Connection Network Type: IN
            Connection Address Type: IP4
            Connection Address: 13.83.167.165
        Time Description, active time (t): 0 0
            Session Start Time: 0
            Session Stop Time: 0
        Media Description, name and address (m): audio 35508 RTP/AVP 0 100
            Media Type: audio
            Media Port: 35508
            Media Protocol: RTP/AVP
            Media Format: ITU-T G.711 PCMU
            Media Format: DynamicRTP-Type-100
        Bandwidth Information (b): AS:88
            Bandwidth Modifier: AS [Application Specific (RTP session bandwidth)]
            Bandwidth Value: 88 kb/s
        Media Attribute (a): maxptime:40
            Media Attribute Fieldname: maxptime
            Media Attribute Value: 40
        Media Attribute (a): rtpmap:0 PCMU/8000
            Media Attribute Fieldname: rtpmap
            Media Format: 0
            MIME Type: PCMU
            Sample Rate: 8000
        Media Attribute (a): rtpmap:100 telephone-event/8000
            Media Attribute Fieldname: rtpmap
            Media Format: 100
            MIME Type: telephone-event
            Sample Rate: 8000
        Media Attribute (a): fmtp:100 0-15
            Media Attribute Fieldname: fmtp
            Media Format: 100 [telephone-event]
            Media format specific parameters: 0-15
        Media Attribute (a): sendrecv
        Media Attribute (a): rtcp:35509
            Media Attribute Fieldname: rtcp
            Media Attribute Value: 35509
        Media Attribute (a): ptime:20
            Media Attribute Fieldname: ptime
            Media Attribute Value: 20
        [Generated Call-ID: 0A58AC142435-cb5-dd85f700-aca53b-69442ef5-bb1ab]
```

<Note>
  Need help or have questions? Contact [support@telegent.com](mailto:support@telegent.com)
</Note>