REST API

Authentication

HTTPS

All communication with SNRB Labs API is done through secure channels that use HTTP with SSL. In addition to using HTTPS, we also utilize the following three mechanisms to prevent unauthorized use of the API.

SHA-256 Hash

You will need to create a SHA-256 hash of the parameters passed in a particular API and your Secret Key. This hash needs to be passed in the API to the SNRB Labs server. The server will create a hash in a similar manner—if the created hash does not match the hash passed in the API, the API will be rejected due to authentication failure.

Sample Authentication

All examples are using the endpoint /api/numbers/list/{customerId}/areaCode/{areaCode}/requestId/{nonce}/hash/{hash value of customerId + areaCode + requestId}"

public static String getNumbersRequestUrl(String baseUrl, String clientId, String areaCode, String apiSecret){ 
    String requestId = getNonce();
    String hash = bin2Hex(createSHA256Hash(clientId + areaCode + requestId + apiSecret));
    return String.format("%s/numbers/list/%s/areaCode/%s/requestId/%s/hash/%s",
                baseUrl,
                clientId,
                areaCode,
                requestId,
                hash);
}
public static byte[] createSHA256Hash(String input){
    MessageDigest digest;
    try{
        digest = MessageDigest.getInstance("SHA-256");
        digest.reset();
        return digest.digest(input.getBytes());
    }catch(NoSouchAlgorithmExpcetion e){
        e.printStackTrace();
    }
}
public static String bin2hex(byte[] data){
    return String.format("%0" + (data.length * 2) + 'x', new BigInteger(1, data));
}
public static String getNonce(){
    return UUID.randomUUID().toString()
}

A sample Android app with this authentication code and API request is available on out Github page.

To create the hash, please concatenate all the parameters being passed in the API (in the order they are presented in this document), whether in the URL itself or in the JSON array. Add your Secret Key to the end of this string. Make sure there are no spaces or extra characters added between the parameters and/or the Secret Key when concatenating them. Create the SHA-256 hash of this string and pass it in the API.

Please note that this hashing mechanism ensures that your Secret Key never goes over the “wire.”

Nonce

We use a Request ID parameter in all the critical API calls. This is a unique and random identifier that should be used one time only. This ensures that an old API message cannot be used in “replay attacks.”

IP Address White-listing

Although not mandatory, we recommend that you use one server to invoke our APIs to communicate with our server(s). You can provide the IP address of this server to us. We will white-list this IP address and ignore API communication from all other IP addresses that use your Customer ID. Alternatively, instead of one IP address, you may provide us multiple IP addresses or a range of IP addresses that should be white-listed by us.

Common Terms & Definitions

BASE URL

All URLs referenced in this document have the following base:

https://commercial.snrblabs.com/api/

Customer ID

This is a unique identification assigned to a customer. This ID is used in the REST APIs to identify the customer making the request. The Customer ID will be provided to you when you open your account with SNRB Labs.

Secret Key

This is a unique string assigned to a customer. It is used for authentication purposes in the API. Please keep this Secret Key a secret! The Secret Key will be provided to you when you open your account with SNRB Labs.

Numbers API

Introduction

The REST APIs described on this page will help you manage your phone numbers. In particular, they will allow you to:

  • Get a list of available phone numbers in the area code of your choice
  • Reserve a phone number
  • Delete a phone number
  • Get a list of all phone numbers that belong to you
  • Get information about one of your phone numbers

Base URL

All URLs referenced in the Numbers API have the following base: https://commercial.snrblabs.com/api/v1/numbers/

LIST

Get a list of available phone numbers in the area code of your choice

curl --request GET \ 
    --header "Content-type" : "application/json" \
    --url "https://commercial.snrblabs.com/api/numbers/list/{CustomerId}/AreaCode/732/RequestId/1233445679/Hash/MyCalculatedSHA-256Hash"
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
AreaCode String A US area code in which you want to check for available phone numbers Yes
RequestId String A unique identifier for the request. This should be an arbitrary string of 24 or less characters that may only be used once. Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes

Successful Return: “200 OK” with the following JSON array

Parameter Description
Number An available number in your specified area code. Up to 10 phone numbers will be returned. If no numbers are available in the specified area code, the array may contain no entries.

Failure Returns

Code Description
401 Unauthorized Invalid Customer ID
403 Forbidden Hash authentication failure
406 Not acceptable The area code is invalid or no phone numbers are available in it
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

[
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682, 
    +19173528682  
]

RESERVE

Reserve a phone number so you can use it.

curl --header "content-type: application/json; charset=utf-8" \
    --request POST --url "http://localhost:54954/api/numbers/reserve" \
    --data '{
        "CustomerId": "000000000", 
        "PhoneNumber":"+1735555555", 
        "AreaCode": "732", 
        "RequestId": "1233445679", 
        "Hash":"MyCalculatedSHA-256Hash"
}'
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
PhoneNumber String An available number you want to reserve for your use. You should supply either Phone Number or Area Code in the API. If both are supplied, Phone Number will be used and Area Code will be ignored. If neither is supplied, an available number in any area code will be allocated and returned to you. No
AreaCode String A US area code in which you want your phone number. You should supply either Phone Number or Area Code in the API. No
RequestId String A unique identifier for the request. This should be an arbitrary string of 24 or less characters that may only be used once. Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes

Failure Returns

Code Description
401 Unauthorized Invalid Customer ID
403 Forbidden Hash authentication failure
406 Not acceptable Phone number not available (if a specific number was requested) or, if a specific area code was requested, the area code is invalid or no phone numbers are available in it
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

{
    "UserName":"1735555555",
    "Password":"pase4523","PhoneNumber":"+1732555555","UserId":0001,"UserToken":"aaaaaaa-1f03-4d13-9fc2-7ae7259eba8f"}

DELETE

Remove a number from your account

curl --request DELETE \
    --header "content-type: application/json; charset=utf-8" \
    --url "https://commercial.snrblabs.com/api/numbers/delete/{customerId}/number/+1732555555/requestId/1234456789/hash/MyCalculaedSHA-256Hash"
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
PhoneNumber String A number that you want to delete and remove from your account. Yes
RequestId String A unique identifier for the request. This should be an arbitrary string of 24 or less characters that may only be used once. Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes

Failure Returns

Code Description
401 Unauthorized Invalid Customer ID
403 Forbidden Hash authentication failure
406 Not acceptable Phone number does not belong to you
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

No Body

INVENTORY

Get a list of all phone numbers that belong to you

curl --header "content-type: application/json; charset=utf-8" --request GET \
     --url "https://commercial.snrblabs.com/api/numbers/inventory/1/page/1/quantity/10/query/+732/requestId/{requestId}/hash/MySHAHash"
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
Page Integer Used for pagination to indicate the page requested for querying the list of phone numbers. If no value is specified, the default is 0. Yes
Quantity Integer Used for pagination to indicate the size of each page requested for querying the list of phone numbers. If no value is specified, the default value is 25 (maximum value is 1000). Yes
Query String Used for seaching by entering a partial number (i.e. 917) No
RequestId String A unique identifier for the request. This should be an arbitrary string of 24 or less characters that may only be used once. Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes

Failure Returns

Code Description
401 Unauthorized Invalid Customer ID
403 Forbidden Hash authentication failure
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

[
    {
        "PhoneNumberId":"n-numberid6gjueysrzwybwia",
        "PhoneNumber":"+17324005446",
        "CreationDate":"10/5/2017 3:03:02 AM",
        "UserId":"999",
        "Sip":
            {
                "UserId":999,
                "SipId":"gvip-9999-9999",
                "SipUrl":"sip:gvip-9999-9999@evolution-dev.bwapp.bwsip.io",
                "SipPassword":"AH48AHA","EndpointId":"re-myendpointidfgs2kxr6mcq",
                "Domain":"rd-mydomaincwxu4drkkcfx6sgq",
                "Realm":"evolution-dev.bwapp.bwsip.io"},
                "NumberUserId":999,
                "TotalPages":1
    },
                                 {
        "PhoneNumberId":"n-numberidsecondzsyxyzwia",
        "PhoneNumber":"+17324005555",
        "CreationDate":"10/5/2017 4:13:45 AM",
        "UserId":"999",
        "Sip":
            {
                "UserId":1050,
                "SipId":"gvip-8888-8888",
                "SipUrl":"sip:gvip-8888-8888@evolution-dev.bwapp.bwsip.io",
                "SipPassword":"AH48AHA","EndpointId":"re-myendpointidsecond6mcq",
                "Domain":"rd-mydomaincsecondkcfx6sgq",
                "Realm":"evolution-dev.bwapp.bwsip.io"},
                "NumberUserId":1050,
                "TotalPages":1
    }
]

SMS Messaging API

Doc. Ver. 4

Introduction

The information provided on this page will help you send and receive SMS (text) messages using server-to-server REST APIs. In particular, it will allow you to:

  • Register for SMS delivery
  • Send a SMS message
  • Receive a SMS message
  • Get copies of SMS messages

Base URL

All URLs referenced in the SMS Messaging API have the following base: https://commercial.snrblabs.com/api/v2/sms/

REGISTER

Register for SMS delivery

curl --request POST \ 
        --header "content-type: application/json; charset=utf-8;"
        --url  "https://commercial.snrblabs.com/api/v2/sms/register"
        --data '{ 
                    "CustomerId" : 000000000, 
                    "Type":"1",
                    "CallbackUrl" : "https://myapi/messages/receive",
                    "DeliveryMode" : "1",
                    "UserName" : "user1@snrblabs.com",
                    "Password" : "PA$$W0RD12345"
                    "RequestId" : "1233445679",
                    "Hash" : "MyCalculatedSHA-256Hash",
               }'
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
Type Integer 0 – Push mechanism will be used 1 – Pull mechanism will be used Note: A valid CallbackUrl is required if the Push option is specified. Yes
RequestId String A unique identifier for the request. This should be an arbitrary string of 24 or less characters that may only be used once. Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes
CallbackUrl String Your callback URL for incoming SMS messages for your phone numbers. This should be a string of 256 or less characters. (This parameter is applicable only if Push mechanism is being used.) No
DeliveryMode String 0 – Deliver only received SMS 1 – Deliver both sent and received SMS If this parameter is missing, the “0” option is assumed. No
UserName String A string of 24 or less characters. (This parameter is applicable only if Push mechanism is being used.) No
Password String A string of 24 or less characters. (This parameter is applicable only if Push mechanism is being used.) No

Failure Returns

Code Description
400 Bad Request Parameter(s) missing or have invalid value
401 Unauthorized Invalid Customer ID
403 Forbidden Hash authentication failure
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

No Body

SEND

Send a SMS message

curl --request POST \ 
    --header "Content-type" : "application/json"
    --url https://commercial.snrblabs.com/api/v2/sms/send
    --data { 
                "CustomerId" : 000000000, 
                "To":"+19175551234",
                "From": "+17325559876",
                "Text": "Here is my message",
                "Hash" : "MyCalculatedSHA-256Hash"
            }
Parameter Type Description Mandatory?
CustomerId Integer Your Customer ID Yes
To String Recipient’s phone number Yes
From String Senders’s phone number Yes
Text String The text (SMS) message contents Yes
Hash String SHA-256 hash of Customer ID, Area Code, Request ID and your Secret Key Yes

Failure Returns

Code Description
400 Bad Request The "Text" field is blank (empty)
401 Unauthorized Invalid Customer ID
402 Payment Required Your account has no money
403 Forbidden Hash authentication failure
404 Not Found The "To" number is invalid
406 Not Acceptable The "From" Number does not belong to you
503 Service Unavailable API request from an IP address that is not white-listed
500 Internal Server Error Any other error

Successful Response (200 OK)

No Body

RECEIVE

Recieve SMS messages from our servers at the callback URL specified in registartion

Message is sent from our server to your callback URL as follows

curl --request POST \ 
    --header "Content-type" : "application/json"
    --url "http://yourdomain.com/your_callback_url"
    --data { 
                "To":"+19175551234",
                "From": "+17325559876",
                "Text": "Here is my message"
                "MessageId" : "a_unique_message_id",
                "DateTime"  : 2017-05-13T10:39:35Z,
                "Direction" : "In"
            }
Parameter Type Description Mandatory?
To String Recipient’s phone number Yes
From String Senders’s phone number Yes
Text String The text (SMS) message contents Yes
MessageId String A unique identifier of the message Yes
DateTime DateTime Date and time at which the message was received (in UTC format) Yes
Direction String Direction of message: In – A message that came from the telephone network to your number Out – A message that was sent from your number to the telephone network Yes
If UserName and Password parameters were provided in the REGISTER API, then this POST will include a standard Authorization header. This header will deploy basic authentication, and include Base64 encoded UserName and Password parameters.