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:
  • Create an account and authenticate
  • 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.1/oauth/token 
{
  "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 Account

Create your main account to organize subscribers and numbers. API Call: POST /accounts/create 
{
  "AccountName": "My MVNO Business",
  "AccountType": "MVNO",
  "BillingEmail": "[email protected]",
  "AdminEmail": "[email protected]"
}
Save the AccountId - you’ll use this when creating subscribers.

​
Step 3: Create Message Route

Message routes define how SMS/MMS messages are delivered to your system. This is required for ALL subscribers. API Call: POST /message/routes 
{
  "RouteName": "Primary Message Route",
  "RouteUrl": "https://your-webhook-url.com/messages",
  "RouteType": "POST",
  "RouteEnabled": true,
  "DeliveryReports": 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 5.

​
Step 4: 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 /voice/routes 
{
  "RouteName": "Primary SIP Trunk",
  "RouteType": "Trunk",
  "VoiceUrl": "sip:your-sip-domain.com",
  "RouteEnabled": true
}
Save the CallRouteId (also called CRID) if you created one.

​
Step 5: 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 /numbers/availability 
{
  "NumberType": "mobile",
  "MessageType": "p2p",
  "MessageEnabled": true,
  "VoiceEnabled": true,
  "PageNumber": 1,
  "AreaCode": "801",
  "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 6: Provision Phone Number

Now let’s activate the phone number you selected. API Call: POST /numbers/provision 
{
  "OrderId": "TEST-ORDER-001",
  "PhoneNumber": "+13105551234",
  "NumberType": "mvno",
  "MessageType": "p2p",
  "MessageRouteId": "MRID-12345678-abcd-1234-5678-abcdef123456",
  "VoiceRouteId": "CRID-87654321-dcba-4321-8765-fedcba987654",
  "MessageEnabled": true,
  "VoiceEnabled": true
}
Save the PhoneNumber and TNID for the next step.

​
Step 7: Create Subscriber

Finally, create the end user who will use this phone number. API Call: POST /subscribers/create 
{
  "Name": "John Smith",
  "Email": "[email protected]",
  "Password": "SecurePass123!",
  "AccountId": "AID-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "PhoneNumbers": ["+13105551234"],
  "Role": "Subscriber"
}
Save the SubscriberId

​
Step 8: Test Your Setup

Send a test SMS message to verify everything is working. API Call: POST /message/send 
{
  "From": "+13105551234",
  "To": "+13105559999",
  "Message": "Hello! This is a test message from my new Telegent number."
}

​
🎉 Success!

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

Account Created

✅ An Account created
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

Parental Controls

Configure AI Guardian features for family accounts

Subscriptions

Create subscription-based billing

Webhooks

Set up delivery reports and inbound message handlers

​
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 AccountId returned from the account creation step (Step 2).

​
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
Last Updated: December 5, 2025