API Reference

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.

API Endpoint

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.

Request Example

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

Example of Error response

{
  "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.

Request Example

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

Response Example

{
  "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)

Definition

POST https:///v1/insight/fraudcheck

Request Example

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

Response Example

{
    "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.

Definition

POST https:///v1/sms

Request Example

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.

Definition

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

Example body

{
  "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.

Definition

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.

Request Example (application/x-www-form-urlencoded)

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

Request Example (application/json)

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

Response Example

{
  "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/verify/did

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.
ivrConfirmation boolean, optional

Set to true if need additional confirmation via IVR. The user will need to enter a one-digit confirmation code.
ivrMessage string, optional

The text of the voice message that will be played for the user. If confirmation is required, a digit will be added at the end.

Request Example

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

Response Example

{
  "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/verify/did/{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).

Request Example

curl https:///v1/verify/did/xxxxxxxxxxxxxx \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f"

Response Example (200 OK)

{
  "requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65,  "didNumber" : "374444444444",
  "expiresAt" : "1701792901",
  "status" : "DELIVERED",
  "callReceivedAt" : "1701792922"
}

Error Example (404 Not found)

{
  "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.

Request Example

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.

Request Example

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.

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.
estimatedCost boolean

Estimated cost (if available) in the currency of contract.
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.

Callback message example

{
    "requestId": "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65",
    "number": "+37200911211",
    "status": "ANSWERED",
    "sipStatus": 200,
    "timestamp": 1656666364
    "callCreatedAt": 1656666328,
    "callEndedAt": 1656666364,
    "billable": true
}