Overview

The Boomware 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.

https:///v1

Authorization

API requests are protected with HTTP Basic authentication. The client sends HTTP requests with an Authorization header:

Authorization: Basic <BASE64_ENCODED_ACCESS_TOKEN>


To get your access token, please Contact support or use your 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 to define the reason of an error.

Common Errors
  • 1 HTTP 401
    Authentication required
    Wrong authentication token was provided in request header.
  • 2 HTTP 400
    Inactive account
    Your account is inactive. Please contact support.
  • 4 HTTP 429
    Too many requests
    You provided to many requests in a short period of time. Max allowed number of requests 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 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.
{
"errorCode" : 1,
"errorReason" : "Authentication required"
}

Verification

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

POST https:///v1/verify

Create verification request

There are three verification methods available:

call - this method will initiate a phone call to 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 SMS message containing a numeric code (PIN).

voice - this method initiates a voice (PIN-2-speech) call to provided user number in which our robot will dictate 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: sms, voice, call.
  • from string, optional
    Alphanumeric string to specify the SenderID for SMS. Your senderId's must be validated by our support before usage.
  • language string, optional
    Language for voice and sms methods. Default is en (supported: en, de, fa, es, fr, it, pt, ja, ru, sv).
  • 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.
curl -XPOST https:///v1/verify \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000" \ -d method=sms

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65"
}

Check verification code

Verify users 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"

Getting request info

Retrieve information about verification providing its requestId

# Extended information about the verification$ curl	-X POST https:///v1/verify/info \		-u "1efc292194c04e9b530:b0b6c43e9a75c51f" \		-d "requestId=XXXXXXXXXXXXXX"

SMS API

Send an outbound SMS from your account

Parameters
  • number string
    The number that the message should be sent to in E.164 format
  • text string
    The text of the message being sent
  • from string (optional)
    The name or number the message should be sent from. Alphanumeric senderId must be validated by our support before usage.
  • 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 from Boomware, inbound messages to that number are 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 for the 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,
}

Messaging

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

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

Send a Push notification

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

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
  • title string, optional
    Title for the push message
  • callbackUrl string, optional
    The webhook endpoint the delivery receipt for this message is sent to.
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 viber message
  • buttonActionUrl string, optional
    Action for the button
  • imageUrl string, optional
    Link for an image
curl -XPOST https:///v1/messaging/viber \ -u 1efc292194c04e9b530:b0b6c43e9a75c51f \ -d number="+18800000000"\ -d text="Your order #29211 received"

Message Failover

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

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

Voice API

Boomware's 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 specified number. The call ends automatically after timeout or an 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 SMS or our support before usage.
  • timeout number, optional
    Timeout in seconds after that the call should be terminated. The default value is 45
curl -XPOST https:///v1/calls/flash \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

{
"requestId" : "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65"
}

Make a Text-2-Speech call

When you send a POST request with the end user's phone number, Boomware sends a text to speech version of the message you specify.

Parameters
  • number string, REQUIRED
    Target User phone number in E.164 format
  • text string, REQUIRED
    A UTF-8 and URL encoded string of up to 2000 characters containing the message to be synthesized in the call or conversation.
  • from string, optional
    The endpoint number you are calling from. This number must be validated before.
  • language string, optional
    The voice parameter allows you to specify a voice to be used to speak your text to speech messag. Default is en.
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.





curl -XPOST https:///v1/calls/text \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000" -d "text=Your car has arrived"

Number Insight

Boomware's Number Insight API provides details about the validity, reachability and roaming status of a phone number, as well as give you details on how to format the number properly in your application.

There are three levels of Number Insight API available: Simple, Standard (HLR Request) and Advanced (SS7 direct Request).

GET https:///v1/insight/{LOOKUP_TYPE}

Lookup simple info

Retrieve Network information (MCC MNC) and local/international representations of a phone number by Def-Code database.

Lookup HLR info

Provides details about the validity, reachability and roaming status of a phone number.

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

{
     "networkCode": "214026",
     "networkName": "Vodafone Espana S.A.U.",
     "networkCountryName": "Spain",
     "networkCountryIso": "ES"
     "numberFormatted": "+34 710 00 00 00"
     "numberCountryIso": "ES",
     "numberCountryPrefix": "34"
}