Overview

The REST API is served over HTTPS, HTTP is not supported. All responses are returned in JSON format.
All responses include conforming HTTP status code.
All successful requests have codes HTTP 2XX.
All failed requests have codes HTTP 4XX/5XX.
You can pass parameters (request body) as application/json and as application/x-www-form-urlencoded.

https:///v1

Authorization

API requests are protected with HTTP Basic authentication. Clients send HTTP requests with an Authorization header:

Authorization: Basic <BASE64_ENCODED_ACCESS_TOKEN>


To get your access token, please Contact support or use developer console.

curl -XPOST https:///v1/sms \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

Errors

In case of failure all responses contain errorCode and errorReason fields which can help you define a reason of the error.

Common Errors
  • 1 HTTP 401
    Authentication required
    Wrong authentication token was provided in the request header.
  • 2 HTTP 400
    Inactive account
    Your account is inactive. Please contact support.
  • 4 HTTP 429
    Too many requests
    You provided too many requests in a short period of time. Max number of requests allowed is 30 per second.
  • 5 HTTP 401
    Inactive token
    Token you are currently using for request is inactive.
  • 6 HTTP 403
    Account not in live
    Contact support to activate your account.
  • 10 HTTP 400
    Invalid request
    Your request was formed incorrectly. Please see the documentation for details.
  • 11 HTTP 400
    Invalid number
    The number you provided is invalid or malformed. We accept phone numbers in international format (E.164). Please see the documentation for details.
  • 16 HTTP 400
    Sender not allowed
    Sender id for current type of request is not allowed
{
"errorCode" : 1,
"errorReason" : "Authentication required"
}

HLR lookup

HLR lookup API provides details about the network (MCC, MNC), validity, reachability and roaming status of a phone number.

The home location register (HLR) is a central database that contains details of each mobile phone subscriber that is authorized to use the GSM core network.

curl https:///v1/insight/hlr \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+47463562200" 

{
  "id": "A82f588e12b54ba1b6bd9a5969d51522",
  "product": "insight.hlr",
  "number": "+47463562200",
  "mccmnc": "242005",
  "network": "Mobile Norway",
  "country": "NO",
  "status": "DELIVERED",
  "createdAt": 1550975149131
}

Fraud Check

Use Fraud Check API to check if a phone number is a number that has not been used for fraud purposes, and to ensure it is affiliated with a base of prefixes of mobile networks.
The algorithm is based on data collected by LANCK TELECOM Fraud Management System that works with networks processing international traffic worldwide.

Check statuses
  • PASSED
    The number is mobile and is not found in the lists of fraudulent/suspicious numbers.
  • NOT_MOBILE_PREFIX
    The number is not mobile (the phone number prefix is not a mobile network prefix), but is not found in the lists of fraudulent/suspicious numbers.
  • SUSPICIOUS
    The number is marked as suspicious by traffic monitoring algorithms based on neural networks.
  • FRAUDULENT
    The number is found in the list of fraudulent numbers (was used in fraud purposes not a long time ago). We recommend you to block the use of that number.

Parameters
  • number string, REQUIRED
    Phone number that needs to be checked (should be sent in E.164 format)
POST https:///v1/insight/fraudcheck

curl -XPOST https:///v1/insight/fraudcheck \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"

{
    "status": "FRAUDLENT",
    "mobilePrefix": false
}

SMS API

Send an outbound SMS from your account

Parameters
  • number string
    The number on which the message should be sent in E.164 format
  • text string
    text of the message being sent
  • from string (optional)
    The name or number the message should be sent from. Alphanumeric senderId must be pre-validated by our support team.
  • callbackUrl string, optional
    The webhook endpoint the delivery receipt for this message is sent to.
POST https:///v1/sms

curl -XPOST https:///v1/sms \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Your order #29211 received"

Inbound SMS

If you rent one or more virtual numbers, inbound messages to these numbers will be sent to your webhook endpoint. When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response our API will resend the inbound message during next 24 hours.

POST https://yourdomain.com/webhook/inbound-sms

{
  "from": "447700900001",
  "to": "447700900000",
  "messageId": "fffeee-qqdqqq-gfrgrgr-vvvvvvv",
  "text": "Hello world",
  "timestamp": 1578787200,
  "parts": 1,
}

Voice API

Voice API makes it easy to make calls. Using this REST API, you can make outgoing programmable calls and query metadata about calls.

POST https:///v1/calls/{CALL_TYPE}

Make a Flash call

This method creates an outbound Call from a specified number. The call ends automatically after a timeout or a user answer. That means the call has no duration.

API method

POST /v1/calls/flash

Request Parameters
  • number string, REQUIRED
    Target User phone number in E.164 format
  • from string, optional
    The endpoint number you are calling from. This number must be validated by our support before usage. By default, from-number is generated by random and returned in the response.
  • code string, optional
    Last 4-6 digits of an auto-generated from-number.
    From-number is generated on the server side and returned in the response.
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.
Response Fields
  • requestId string, REQUIRED
    The unique request ID to identify the generated call.
  • from string, REQUIRED
    The from number (Caller ID) from which will be generated a call.
curl -XPOST https:///v1/calls/flash \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=18800000000"

curl -XPOST https:///v1/calls/flash \ -u '1efc292194c04e9b530:b0b6c43e9a75c51f' \ -H 'Content-Type: application/json' \
-d '{"number": "18800000000", "code": "1234"}'

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65" "from" : "37282329823"
}

Verification via incoming call

This API method reserves DID number for verification via incoming call.
Reservation expires in 1 minute (by default). Use callbackUrl parameter to get notification about an incoming call or poll GET method with request information.

API method

POST /v1/calls/incoming

Parameters

You can pass parameters as application/json or as application/x-www-form-urlencoded.

  • number string, REQUIRED
    Target User phone number in E.164 format
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.
curl -XPOST https:///v1/calls/incoming \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65, "didNumber" : "374444444444",
"expiresAt" : "1701792901"
}

Get incoming call info

Method returns current status of DID number reservation.
Can be polled in a cycle (each 5 seconds for example), as alternative using webhook (callbackUrl).

API method

GET /v1/calls/incoming/{requestId}

Response fields
  • didNumber string
    The number user should call to.
  • expiresAt number
    Time when this reservation expires (UTC time).
  • callReceivedAt number
    Incoming call receive time. Null if no call received yet. Calls from another numbers (not user prvided number) are ignored.
  • status string
    PENDING - Waiting for call from user
    DELIVERED - Valid call received in time
    EXPIRED - Request is expired (by default time for verification is 1 minute).
curl https:///v1/calls/incoming/xxxxxxxxxxxxxx \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f"

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65, "didNumber" : "374444444444",
"expiresAt" : "1701792901",
"status" : "DELIVERED",
"callReceivedAt" : "1701792922"
}
{
"errorCode" : 404,
"errorReason" : "Request not found or expired"
}

Make a Pin-2-Speech call

The server makes a call to deliver a Pin-code using voice message

Parameters
  • number string, REQUIRED
    Target User phone number in E.164 format
  • code string, REQUIRED
    Pin-code for the voice message (4-6 digits)
  • from string, optional
    The endpoint number you are calling from. This number must be pre-validated.
  • language string, optional
    The voice parameter allows you to specify a voice to be used to speak out your text-to-speech message. Default is en (supported: am, ar, az, bn, de, en, es, fa, fr, he, hi, hy, id, it, ja, ka, kk, km, ky, mg, mn, ms, my, ne, ps, pt, ru, si, sn, so, sv, sw, ta, tg, tk, uk, ur, uz, vi, zh).
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.





curl -XPOST https:///v1/calls/p2s \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000" -d "code=1234"

Make a Text-2-Speech call

The Server makes a call to deliver a text using voice message

Parameters
  • number string, REQUIRED
    Target User phone number in E.164 format
  • text string, REQUIRED
    Text that you would like to synthesize
  • from string, optional
    The endpoint number you are calling from. This number must be pre-validated.
  • language string, optional
    The voice parameter allows you to specify a voice to be used to speak out your text-to-speech message. Default is en. Also supported ru.
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.





curl -XPOST https:///v1/calls/t2s \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000" -d "text=Hi, i'm using API!"

Request status

The following sequence diagram shows the number verification flow by Flash/P2s Call.

Problem with loading diagram SVG.

Notify about success verification

This method has to be called when target user verification is completed successfully. If the current request is a flash call it will be terminated.
This API used to improve delivery quality.

PARAMETERS
  • goal string
    NUMBER_VERIFIED.
curl -XPOST https:///v1/requests/xxxxxxxxxxxxxx \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "goal=NUMBER_VERIFIED"

Callback (webhook) with request status

All API methods support callbackUrl parameter.
If you provide this one you receive callback (HTTP POST) to your URL with body in json/application format.
It is the request delivery receipt with the status.

Payload fields
  • requestId string
    The request ID.
  • number string
    The phone number.
  • sipStatus string
    The SIP status of call end.
  • status string
    SMS delivery status or call end status. It's a simplified text status mapped from SIP code or SMPP status. To get detailed call status sipStatus field.
  • billable boolean
    Will this request be billable or not.
    Notice!: The final invoice will be generated after vendor tariffication and could be different.
  • timestamp number
    Time of status update. Unixtime (UTC).
  • callCreatedAt number
    The time when a call was initiated. Unixtime (UTC).
  • callEndedAt number
    The time when a call was finished. Unixtime (UTC).
Common statuses
  • SENT
    Message or phone call request has been sent to the provider without errors.
  • REJECTED
    Impossible to perform the request. Request is not billable.
  • FAILURE, DECLINE, FORBIDDEN
    Call was declined (for details see sipStatus).
  • ANSWERED
    The call was answered by a user or by a robot (SIP 200).
  • TERMINATED
    The call has been ended by timeout (SIP 487).
  • UNAVAILABLE
    The phone number is not available (SIP 480).
  • BUSY_HERE
    Callee is busy or user cancels call (SIP 486).
  • DELIVERED
    SMS message has been successfully sent and delivered.
  • UNDELIVERED
    SMS message has been sent to the provider, but has failed to deliver.
{
    "requestId": "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65",
    "number": "+37200911211",
    "status": "ANSWERED",
    "sipStatus": 200,
    "timestamp": 1656666364
    "callCreatedAt": 1656666328,
    "callEndedAt": 1656666364,
    "billable": true
}