API Quick Start Guide - Telegent mPaaS

Overview

This guide walks you through the complete process of setting up your first Telegent number, configuring messaging and voice routes, and creating a subscriber. By the end, you’ll have sent your first test message!

What You’ll Build:

Authenticate with the API
Set up message and voice routing
Provision a phone number
Create a subscriber
Send a test message

Number provisioning flow — step-by-step diagram from authentication through to verifying a provisioned number

Prerequisites

API Credentials

You’ll need an AccountKey and AccountSecret from your Telegent representative

API Tool

Postman, cURL, or any HTTP client for making API requests

Step 1: Authenticate

All API calls require a Bearer token. Get yours first by authenticating with your credentials. API Call: POST /v1.0/oauth2/tokens

curl --request POST \
  --url https://api.telegent.com/v1.0/oauth2/tokens \
  --header 'Content-Type: application/json' \
  --data '{
    "AccountKey": "YOUR_ACCOUNT_KEY",
    "AccountSecret": "YOUR_ACCOUNT_SECRET",
    "ApiEndpoint": "https://api.telegent.com/v1.0/numbers/provision"
  }'

Response:

{
  "token": "abcdeghijklmnopqrstuvwxyz...................",
  "successful": true,
  "tokenExpiry": "05/02/2025 06:36:13 PM"
}

ApiEndpoint scopes the token to a specific endpoint URL for security. Generate a separate token for each endpoint you call.

Save this token! You’ll need it in the Authorization: Bearer header for all subsequent requests.

Step 2: Create Message Route

Message routes define how SMS/MMS messages are delivered to your system. This is required for ALL subscribers. API Call: POST /v1.0/message/routes

{
  "RouteName": "Main SMS Webhook",
  "MessageUrl": "https://apiendpoint.com",
  "MessageUrlMethod": "POST",
  "MessageRouteEnabled": true,
  "MessageAuthenticationType": "Basic",
  "MessageUsername": "admin",
  "MessagePasswordToken": "passwordORbearerToken",
  "CallbackMessageUrl": "https://apiendpoint.com",
  "CallbackMessageUrlMethod": "POST",
  "CallbackMessageAuthenticationType": "Basic",
  "CallbackMessageUsername": "admin",
  "CallbackMessagePasswordToken": "password",
  "InboundBypass": true,
  "OutboundBypass": true,
  "IntelligentRouteEnabled": true,
  "AccountId": "AID-eab92510-1040-45a5-bb9c-0bad9272f89d"
}

Save the MessageRouteId (also called MRID) - required for number provisioning.

Without a message route, you cannot provision numbers! Make sure this is set up before moving to Step 4.

Step 3: Create Voice Route (Optional - MVNO Only)

Voice routes define where inbound calls are directed. Only required if you’re offering voice services. API Call: POST /v1.0/voice/routes

{
  "RouteName": "Main SIP Trunk",
  "RouteType": "Trunk",
  "VoiceUrl": "https://domain.com",
  "VoiceUrlMethod": "POST",
  "VoiceAuthenticationType": "Basic",
  "VoiceUsername": "admin",
  "VoicePasswordToken": "passwordORbearerToken",
  "CallbackVoiceUrl": "https://apiendpoint.com",
  "CallbackVoiceUrlMethod": "POST",
  "TrunkIp1": "20.87.87.87",
  "TrunkIp2": "20.87.87.86",
  "TrunkPort1": "5061",
  "TrunkPort2": "5060",
  "TrunkTransport1": "UDP",
  "TrunkTransport2": "TCP",
  "TrunkUri1": "https://pstn.joonto.com",
  "TrunkUri2": "https://pstn2.joonto.com",
  "TrunkEnabled1": true,
  "TrunkEnabled2": false,
  "Trunk1Priortiy": 10,
  "Trunk1Weight": 10,
  "Trunk2Priortiy": 20,
  "Trunk2Weight": 20,
  "HeaderManipulation": "HMI8802029",
  "EnableSipRefer": true,
  "TransferCallerId": "Transferee/Transferor",
  "SymmetricRtp": true,
  "EnableTrpSecureTrunk": true,
  "EnablePstnTransfer": true,
  "IpWhitelist": [{"IpAddress": "20.20.10.10"}, {"IpAddress": "20.20.10.20"}],
  "CnamLookup": true,
  "TerminationUriSubdomain": "client",
  "EnableCallStreaming": true,
  "WssUri": "wss://192.67.88.2",
  "IntelligentRouteEnabled": true,
  "RouteEnabled": true,
  "AccountId": "AID-1e8939ab-3f3c-4db1-89d7-956d80fd793j"
}

Save the CallRouteId (also called CRID) if you created one.

Step 4: Check Available Phone Numbers

Before provisioning a number, check what’s available in your desired area. This endpoint returns a count of available numbers and the areas where they’re available. API Call: POST /v1.0/numbers/availability

{
  "NumberType": "mobile",
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": true,
  "PageNumber": 1,
  "AreaCode": "201",
  "ZipCode": ""
}

Field Notes

NumberType

"mobile" or "voip" — note: when provisioning a number, the valid values are "mvno", "iot", or "voip"

MessageType

"a2p" or "p2p"

AreaCode & ZipCode

AreaCode: 3-digit area code (leave blank "" for all available area codes and zipcodes)
ZipCode: 5-digit zip code (if area code unavailable, system looks at zipcode)
Note: You can input both, but AreaCode searches first if included. If both are blank/NULL, randomized results are returned.

PageNumber

Pagination limits 10,000 per page

Response Fields

ResultsTotal: Total count of available numbers in the searched area
AvailableNumberAreas: Array of areas with available numbers
NGP: Number Gateway Provider
AreaCode: Area code where numbers are available
Zipcode: Zip code where numbers are available

Review the ResultsTotal count to confirm numbers are available in your desired area before provisioning.

Step 5: Create Subscriber

Create the end user who will use the phone number. API Call: POST /v1.0/subscribers/create

{
  "Name": "Jerome User 4",
  "Email": "jerome4@joonto.com",
  "PhoneNumbers": ["+1234567890"],
  "Role": "Subscriber",
  "Password": "1234567890",
  "AccountId": "AID-eab92510-1040-45a5-bb9c-0bad9272f89d"
}

Save the SubscriberId

Step 6: Provision Phone Number

Now provision a phone number in your desired area. API Call: POST /v1.0/numbers/provision

{
  "NumberType": "iot",
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": false,
  "DataEnabled": true,
  "MessageRouteId": "MRID-73af1e73-d7b3-4696-bdd9-5b407c96fc8a",
  "VoiceRouteId": "CRID-4dec6beb-3985-444b-8c06-8baa70dc145",
  "AreaCode": "201",
  "ZipCode": "84043",
  "ICCID": "8901240397190195850",
  "ProductType": "Sms+Data",
  "AssignedSubscriberId": "TSUID-1234567999"
}

Save the PhoneNumberAssigned and PhoneNumberId for the next step.

ProductType options: Sms-Only, Data-Only, Sms+Data, Sms+Data+Voice. ICCID and AssignedSubscriberId are optional.

Step 7: Test Your Setup

Send a test SMS message to verify everything is working. API Call: POST /v1.0/message/outbound

curl --request POST \
  --url https://api.telegent.com/v1.0/message/outbound \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "To": [{"Number": "+18015737111"}],
    "From": "+18018018011",
    "Body": "Hello there!!!"
  }'

Response:

{
  "MessageId": "TMID-00348008102307aK01",
  "Direction": "Outbound",
  "Type": "p2p",
  "Cost": 0.0045,
  "Status": "Queued",
  "To": [{"Number": "+18015737111"}],
  "From": "+18018018011",
  "Body": "Hello there!!!",
  "CreatedOn": "16:45:59 MST 2025-01-23"
}

🎉 Success!

You’ve completed your first setup! You now have:

Authenticated

✅ Successfully authenticated with the API

Routes Configured

✅ Message and Voice routes configured

Number Provisioned

✅ A phone number provisioned

Subscriber Active

✅ A subscriber with an active number

Message Sent

✅ A test message sent

What’s Next?

Now that you have the basics working, explore these advanced features:

Add Data Limits

Set data caps or throttling for IoT and mobile data plans

Port-In Numbers

Transfer phone numbers from other carriers

Create Packages

Build service plans to offer to customers

Subscriptions

Create subscription-based billing

Key Concepts

Phone Number Formats

All phone numbers use E.164 format: +<country_code><number>Examples:

US: +18015551234
UK: +442071234567

Message Types

A2P (Application-to-Person): Business messaging to consumers
P2P (Person-to-Person): Individual messaging between users

Number Classifications

MVNO: Mobile virtual network operator numbers (full mobile service)
IoT: Internet of Things capable numbers (data-focused)
VoIP: Voice over IP numbers

Token Scoping

Each token is scoped to a specific ApiEndpoint URL for security. Generate a separate token for each endpoint you call. Tokens expire at the time specified in tokenExpiry — request a new one using the same credentials when expired.

Common Issues & Solutions

401 Unauthorized

Solution: Check that your Bearer token is correct and included in the Authorization header.

MessageRouteId is required

Solution: You must create a Message Route (Step 3) before provisioning numbers. Message routes are required for ALL subscribers.

Phone number already in use

Solution: The number you selected was claimed by another user. Check availability again and select a different number.

Email already exists

Solution: Each subscriber email must be unique across the entire platform. Try a different email address.

Invalid AccountId

Solution: Make sure you’re using the correct AccountId provided by your Telegent representative.

API Base URL

All endpoints use this base URL:

https://api.telegent.com/v1.0

Example full endpoint:

https://api.telegent.com/v1.0/subscribers/create

Rate Limits

Standard tier: 50 requests per minute
Enterprise tier: Contact support for custom limits

Need Help?

Full Documentation

Complete API reference with all endpoints

Support

Visit our support portal for help and resources

Last Updated: April 27, 2026

Getting Started

Documentation Index

​Overview

​Prerequisites

API Credentials

API Tool

​Step 1: Authenticate

​Step 2: Create Message Route

​Step 3: Create Voice Route (Optional - MVNO Only)

​Step 4: Check Available Phone Numbers

​Field Notes

​Response Fields

​Step 5: Create Subscriber

​Step 6: Provision Phone Number

​Step 7: Test Your Setup

​🎉 Success!

​What’s Next?

Add Data Limits

Port-In Numbers

Create Packages

Subscriptions

​Key Concepts

​Common Issues & Solutions

​API Base URL

​Rate Limits

​Need Help?

Full Documentation

Support

Overview

Prerequisites

Step 1: Authenticate

Step 2: Create Message Route

Step 3: Create Voice Route (Optional - MVNO Only)

Step 4: Check Available Phone Numbers

Field Notes

Response Fields

Step 5: Create Subscriber

Step 6: Provision Phone Number

Step 7: Test Your Setup

🎉 Success!

What’s Next?

Key Concepts

Common Issues & Solutions

API Base URL

Rate Limits

Need Help?