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.

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

Insufficient funds
Your account balance is too low to process the request.
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" 
}

Getting request info

Retrieve information about request its requestId

Response fields

mccmnc string

The identifier of the mobile network resolved by the phone number prefix.
country string

The Country ISO-code resolved by the phone number prefix.
status string

The Request transport status (for example: SENT, DELIVERED, REJECTED, ...).
payload key-value

Source http parameters of the request.

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

Response Example

{
  "id": "xxxxxxxxxxxxxx",
  "product": "verify.sms",
  "number": "+91638651000",
  "mccmnc": "405871",
  "network": "Jio",
  "country": "IN",
  "status": "DELIVERED",
  "createdAt": 1551007102495,
  "payload": {
    "number": "+916386535610",
    "method": "sms",
  }
}

Update Request Info

This method allows setting a goal of a target request.

PARAMETERS

goal string

Goal name(f.e: NUMBER_VERIFIED, LINK_OPENED).

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

Callbacks (webhooks)

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.

Common request statuses

SENT

Message has been sent to the provider without errors.
DELIVERED

Message has been successfully sent and delivered.
UNDELIVERED

Message/Request has been sent to the provider, but has failed to deliver.
REJECTED

Impossible to perform the request. Please contact support for information.

Callback message example

{
    "requestId": "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65",
    "number": "+37200911211",
    "mccmnc": "282002"
    "status": "ANSWERED",
    "sipStatus": 200,
    "timestamp": 1656666364
    "callCreatedAt": 1656666328,
    “callRingStartedAt”: 1656666334,
    "callAnsweredAt": 1656666347,
    "callEndedAt": 1656666364,
    "billable": true,
    "duration": 17
}

Verification

The process of verification consists of two steps. At the first step you request verification by providing us users' phone numbers and desired verification method. As a response you get a requestId to follow the verification process. At a second step you provide us with verification code (PIN) received from users.

Definition

POST https:///v1/verify

Create verification request

There are three verification methods available:

call - this method will initiate a phone call to a provided user number. In this case the verification code will be 4 to 6 trailing digits in a phone number we called from.

sms - this method initiates sending of an SMS message containing a numeric code (PIN).

voice - this method initiates a voice (PIN-2-Speech) call to provided user number during which our robot will dictate the numeric code.

Parameters

number string, REQUIRED

User phone number that needs to be verified in the E.164 format
method string, REQUIRED

Method that will be used for verification. One of the following: sms, voice, call.
from string, optional

Alphanumeric string to specify the SenderID for SMS. Your senderId's must be pre - validated by our support team.
language string, optional

Language for voice and sms methods. 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).
codeLength number, optional

Length of code (4, 5, or 6) that will be generated. The default value is 4.
ip network address, optional

Optionally you can pass user IP address for more accurate fraud prevention.

Request Example

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

Response Example

{
  "requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65" 
}

Check verification code

Verify user's phone number by providing verification code

Parameters

requestId string

The identifier of the verification request to check. This is the requestId you received in the /verify response.
code string

Verification code that was received by sms, call, or voice method.

# Check the phone number$ curl	-X POST https:///v1/verify/check \		-u "1efc292194c04e9b530:b0b6c43e9a75c51f" \		-d "requestId=XXXXXXXXXXXXXX"

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,
}

Messaging

This is a common API for message delivery to the selected channel.

Definition

POST https:///v1/messaging/{CHANNEL}

Send a Push notification

To Android (FCM) and iOS application. Make sure to implement the SDK in your app.

Parameters

number string

The number that the message should be sent to in E.164 format
text string

A body of the message being sent
title string, optional

Title for the push message
callbackUrl string, optional

The webhook endpoint the delivery receipt for this message is sent to.

Request Example

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

Send a Viber message

Send a direct message to Viber messenger.

Parameters

number string

The number that the message should be sent to in E.164 format
text string

The body of the message being sent
from string, optional

Sender id for the Viber message
callbackUrl string, optional

The webhook endpoint the delivery receipt for this message is sent to.
buttonCaption string, optional

The title of the button in the Viber message
buttonActionUrl string, optional

Action for the button
imageUrl string, optional

Link for an image

Request Example

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

Send an RCS message

Send a direct message to the RCS enabled device.

Parameters

number string

The number that the message should be sent to in E.164 format
text string

The body of the message being sent
callbackUrl string, optional

The webhook endpoint the delivery receipt for this message is sent to.

Request Example

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

Message Failover

Chain of messages (Push > Viber/Whatsapp/etc > SMS).
If a phone number is verified in the app, we will deliver a message via Push notification (it’s free). If there is no app verification or the app is no longer installed, we will deliver the message via Messenger or SMS.

Request Example

curl -XPOST https:///v1/messaging/failover \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d '{
    "number": "+18800000000",
    "flow": [
        {
            "type": "push",
            "message": {
                "title": "Hello",
                "text": "Your order #29211 received"
            },
            "failover": {
                "wait": 30,
                "condition": "delivered"
            }
        },
        {
              "type": "viber",
              "message": {
                "from": "Hello",
                "text": "Your order #29211 received"
              },
              "failover": {
                "wait": 120,
                "condition": "read"
              }
            },
        {
            "type": "sms",
            "message": {
                "from": "Hello",
                "text": "Your order #29211 received"
            }
        }
    ]
}'

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.

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.

Request Example

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

Response Example

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

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!"