Skip to main content

​
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

​
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 
{
  "AccountKey": "your-account-key-here",
  "AccountSecret": "your-account-secret-here"
}
Save this token! You’ll need it in the Authorization 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
}
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
}
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

"mobile" or "voip"
"a2p" or "p2p"
  • 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.
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": [""],
  "Role": "Subscriber",
  "Password": "1234567890",
  "AccountId": "AID-eab92510-1040-45a5-bb9c-0bad9272f89d"
}
Save the SubscriberId

​
Step 6: Provision Phone Number

Now let’s provision a phone number in your desired area with. API Call: POST /v1.0/numbers/provision 
{
  "NumberType": "iot",
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": false,
  "MessageRouteId": "MRID-73af1e73-d7b3-4696-bdd9-5b407c96fc8a",
  "VoiceRouteId": "CRID-4dec6beb-3985-444b-8c06-8baa70dc145",
  "AreaCode": "201",
  "ZipCode": "XXXXX",
  "ICCID": "8901240397190195850", //optional
  "ProductType": "data-only",
  "AssignedSubscriberId": "TSUID-1234567999" //optional subscriber-id to be assigned to number
}
Save the PhoneNumberAssigned and PhoneNumberId for the next step.

​
Step 7: Test Your Setup

Send a test SMS message to verify everything is working. API Call: POST /v1.0/message/outbound 
{
  "CampaignId": "JCID-dsuhofh3882",
  "To": [
    {"Number": "+18015737111"},
    {"Number": "+18014271919"}
  ],
  "From": "+18018018011",
  "Owner": "+18018018011",
  "Body": "Hello there!!!",
  "MmsMedia": [
    {"MediaUrl": "https://results2.com"},
    {"MediaUrl": "https://results.com"}
  ],
  "MmsBase64": [
    {"Base64": "dkjjkdflajdfjo3ji3jjljfkjaskjfad", "BaseType": "audio/wav"},
    {"Base64": "dkjjkdflajdfjo3ji3jjljfkjaskjfad", "BaseType": "video/mpg"}
  ]
}

​
🎉 Success!

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

Authenticated

✅ Successfully authenticated with the API
2

Routes Configured

✅ Message and Voice routes configured
3

Number Provisioned

✅ A phone number provisioned
4

Subscriber Active

✅ A subscriber with an active number
5

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

​
Common Issues & Solutions

Solution: Check that your Bearer token is correct and included in the Authorization header.
Solution: You must create a Message Route (Step 3) before provisioning numbers. Message routes are required for ALL subscribers.
Solution: The number you selected was claimed by another user. Check availability again and select a different number.
Solution: Each subscriber email must be unique across the entire platform. Try a different email address.
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

Email us at support@telegent.com, Bennet@telegent.com, or Vince@telegent.com
Last Updated: January 30, 2026