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

{
  "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 Boomware 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 Boomware support for information.
{
  "requestId": "wp9RPWDGZkskBrVeTc4lgNCc4e79fc65",
  "number": "37200911211",
  "status": "DELIVERED",
  "timestamp": 1551007102495
}

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.

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

Number Insight

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

Number Lookup checks against first-party numbering sources and provides real-time feedback, keeping your database clean.

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
}

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

Messaging

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

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

Send a Push notification

To Android (FCM) and iOS application. Make sure to 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
    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.
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
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.
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.

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

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.
  • callbackUrl string, optional
    Platform sends event information asynchronously to this endpoint when call status changes.
curl -XPOST https:///v1/calls/flash \ -u "1efc292194c04e9b530:b0b6c43e9a75c51f" \ -d "number=+18800000000"

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

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