FAQ
Short answers to the questions we hear most. Every answer links to the page with the details.
Getting started
How do I get started with OmaxTelecom APIs?
Follow Getting started: copy your credentials from OmaxTelecom Console, get an access token and make your first call. It takes a few minutes.
Where can I find my API credentials?
Sign in to OmaxTelecom Console and open the API settings. You need the Client ID and the Client Secret.
What authentication do the APIs use?
OAuth 2.0 client credentials. Exchange your Client ID and Client Secret for an access token at POST https://api.omaxtelecom.com/auth/token, then send it on every request:
Authorization: Bearer <access_token>
The same token works for every OmaxTelecom API. Getting started has code samples in curl, Node.js and Python.
An API answers 403 although my token is valid. Why?
Each API has to be enabled for your organization. The error code tells you what is missing — for example MCC_MNC_DISABLED, PHONE_VALIDATION_DISABLED or BILLING_NOT_CONFIGURED. Contact support@omaxtelecom.com to enable it.
Can I test without sending real traffic?
The SMS API has a test mode: messages go through the whole API — charging, statuses and webhooks — but are simulated and never reach a phone. Support switches your account between test and live mode. You can also try any endpoint in this portal with Test Request; those are real requests to your account.
What are the rate limits?
The SMS API returns RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response, and Retry-After with a 429. For other APIs, contact support if you plan high volumes.
SMS and OTP
How do I send SMS messages?
Get an access token, then call the SMS API:
- one message —
POST /messages
- one text to up to 10,000 numbers —
POST /messages/bulk
- a one-time code —
POST /otp/send
Sends require an Idempotency-Key header, so a retry never sends a message twice.
How do I know whether a message was delivered?
Every message has a status that follows the operator's delivery report: queued, sent, delivered, undelivered, failed, rejected or expired. Subscribe to webhooks to receive a signed event when a message is sent, delivered, failed or expired, or read GET /messages/{id}.
Can I receive incoming SMS?
Not with the SMS API — it sends messages and reports their delivery. To receive SMS, use a number from the Phone Numbers API; inbound messages reach you by webhook (phone_numbers.sms.received) or by email.
Which countries can I send SMS to?
GET /pricing lists the destinations available to you and your price for each. Contact support if a destination you need is missing.
How do one-time codes work?
POST /otp/send creates a 6-digit code, sends it by SMS and returns a verification_id. POST /otp/verify checks the code the user typed. The code is valid for 5 minutes by default (ttl_seconds from 30 to 3600), works once and allows 5 attempts. Your own text goes in template and must contain {code}. Details are in the OTP API guide.
SIM and eSIM
Bappy API or Telkor API — which one do I need?
- Bappy API — you sell ready-made eSIM and SIM data plans to your customers. Each card is a Link; you create it with a plan and top it up. Billing and provisioning are handled for you.
- Telkor API — you run your own SIM inventory: you define coverages and plans yourself, manage links on your SIMs and run bulk jobs on thousands of SIMs.
How do I activate a SIM?
- Bappy:
POST /links with a plan_id. You get the eSIM install details right away.
- Telkor:
POST /links for one SIM, or POST /sims/bulk-provision for many, optionally with plan_ids.
Can I see how much data a SIM has used?
Yes. In Bappy, GET /links/{identifier} shows live usage per plan. In Telkor, every link and activation has usage, and GET /org/cost shows the monthly usage and cost.
Billing and account
How do I check my balance?
In OmaxTelecom Console, or with the API you use: GET /wallet (SMS), GET /organization/balance (Bappy) or GET /org/balance (Telkor).
How do I top up?
In the billing section of OmaxTelecom Console. Contact support if you need a different payment method.
Errors and support
What should I do when I get an error?
- Read the error code in the response — branch on the code, not on the message.
- Look the code up in the Errors section of the API's page.
- On
401, get a new access token and retry once.
- If the problem continues, contact support.
Which errors are common to all APIs?
| Status |
Meaning |
400 |
The request is malformed |
401 |
The access token is missing, invalid or expired |
402 |
Your wallet balance is too low |
403 |
The API or the action is not enabled for your organization |
404 |
The resource does not exist |
422 |
A field is invalid — the response says which |
429 |
Too many requests — wait for Retry-After seconds |
5xx |
A temporary problem on our side — retry later |
Which programming languages can I use?
Any language that can make HTTP requests. Every endpoint in this portal shows ready-to-copy code for curl, JavaScript, Python, PHP, Ruby and more.
Need help?
Email support@omaxtelecom.com. Tell us which endpoint you called, when, and what the response was — including its request_id if it has one. Never send your Client Secret or access token.
Console