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.

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.

Sample Authentication

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

Java
Kotlin

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()
}

Java Sample on GitHub

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

fun String.hashSHA256(): String {
    val bytes = this.toByteArray()
    val digest = MessageDigest.getInstance("SHA-256").digest(bytes)
    return digest.fold("", { str, it -> str + "%02x".format(it) })
}
fun buildSearchNumbersUrl(areaCode:String) : String{
    val requestId = getNonce()
    val hashParams = "$clientId$areaCode$requestId$secret"
    return "$baseUrl/numbers/list/$clientId" +
            "/areaCode/$areaCode/requestId/$requestId/hash/${hashParams.hashSHA256()}"
}
fun getNonce() : String {
    return UUID.randomUUID().toString();
}

Kotlin Sample on GitHub

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

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 --request POST \
  --url https://commercial.snrblabs.com/api/numbers/reserve \
  --header 'content-type: application/json' \
  --data '{ 
    "CustomerId" : 000000000, 
    "PhoneNumber" : "", 
    "AreaCode": "732",
    "Email" : "me@snrb.com",
    "RequestId" : "1233445679",
    "Hash" : "MyCalculatedSHA-256Hash"
}

OR

curl --header "content-type: application/json; charset=utf-8" \
    --request POST --url "http://commercial.snrblabs.com/api/numbers/reserve" \
    --data '{
        "CustomerId": "000000000", 
        "PhoneNumber":"+1735555555", 
        "AreaCode": "", 
        "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/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
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)

[
    {"PhoneNumber":"+17325555752","CreationDate":"2/18/2018 10:43:31 PM"},
    {"PhoneNumber":"+17325554729","CreationDate":"2/18/2018 11:14:11 PM"},
    {"PhoneNumber":"+17325551369","CreationDate":"2/18/2018 11:19:43 PM"},
    {"PhoneNumber":"+17325551810","CreationDate":"2/18/2018 11:27:30 PM"},
    {"PhoneNumber":"+17325552633","CreationDate":"2/19/2018 3:41:16 AM"},
    {"PhoneNumber":"+17325552680","CreationDate":"2/19/2018 3:44:06 AM"},
    {"PhoneNumber":"+17325552672","CreationDate":"2/19/2018 3:44:16 AM"},
    {"PhoneNumber":"+17325552686","CreationDate":"2/19/2018 4:00:29 AM"},
    {"PhoneNumber":"+17325552685","CreationDate":"2/19/2018 4:00:37 AM"},
    {"PhoneNumber":"+17325550648","CreationDate":"2/19/2018 6:37:57 PM"}
]

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.