How to use a Number to send and receive SMS

With the numbers API, you are able to rent a new number and use it as the sender in your campaigns.

With numbers API, you get instant access to local phone numbers from across the world. You are able to:

Simply retrieve all the Routee available numbers, according to the country you desire.
Search among the available numbers for one that meets your needs.
Rent the number you wish with a small activation fee, by making a simple API call.
Send and receive text messages and calls. Track your inbound messages.
View and manage your numbers.
Cancel your number, when you no longer need it.
Don' t care about the expiration of your number since Routee automatically renews your number every month.

Example of how to use a number to send and receive SMS:

In this example, you will see how to rent a new number, use it and how to receive the inbound SMS messages.

To view all the available numbers according to the country you desire, you should send a request as below:

https://connect.routee.net/numbers/available?country=US

Your Header for all following requests should contain authorization and content type:

KEY	VALUE
Authorization	Bearer {access_token}
Content-Type	application/json

The country parameter of the request is required and should be in ISO alpha-2 format (e.g. US).
As response, you will receive all the available numbers for the specific country.

Now, you are able to select the number (MSISDN) and send a request to rent it as below:

https://connect.routee.net/numbers/my

The body parameters should be the below:

KEY	VALUE
msisdn	The phone number.
inboundSmsCallbackUrl	The defined callback URL that will receive the inbound messages.

The example request to rent a number is shown below:

curl -X POST \
  https://connect.routee.net/numbers/my/ \
  -H 'Authorization: Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023' \
  -H 'Content-Type: application/json' \
  -d '{ "msisdn": "+447123123456", "inboundSmsCallbackUrl": "http://my-inbound-sms-url.com" }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}");
Request request = new Request.Builder()
  .url("https://connect.routee.net/numbers/my/")
  .post(body)
  .addHeader("Authorization", "Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://connect.routee.net/numbers/my/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023");
request.AddParameter("undefined", "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/numbers/my/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import http.client

conn = http.client.HTTPConnection("connect.routee.net")

payload = "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}"

headers = {
    'Authorization': "Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023",
    'Content-Type': "application/json"
    }

conn.request("POST", "numbers,my,", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://connect.routee.net/numbers/my/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023'
request["Content-Type"] = 'application/json'
request.body = "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}"

response = http.request(request)
puts response.read_body

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://connect.routee.net/numbers/my/",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023",
    "Content-Type": "application/json"
  },
  "processData": false,
  "data": "{\n\t\"msisdn\": \"+447123123456\",\n\t\"inboundSmsCallbackUrl\": \"http://my-inbound-sms-url.com\"\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"Authorization": @"Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023",
                           @"Content-Type": @"application/json"};
NSDictionary *parameters = @{ @"msisdn": @"+306911111111",
                              @"inboundSmsCallbackUrl": @"http://example.org" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://connect.routee.net/numbers/my/"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"Authorization": @"Bearer b336c672-ce4b-4aa5-8386-7c2a60de3023",
                           @"Content-Type": @"application/json"};
NSDictionary *parameters = @{ @"msisdn": @"+447123123456",
                              @"inboundSmsCallbackUrl": @"http://my-inbound-sms-url.com" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://connect.routee.net/numbers/my/"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

After you rent a number, you are able to send SMS campaign using this number as sender.

When you want to send single SMS using your number, you will have to provide it as "from" parameter without the '+' before the number's country code!
Example for UK number: "from" : "447123123456"

Example:

https://connect.routee.net/sms

Your Header should contain authorization and content type:

KEY	VALUE
Authorization:	Bearer {access_token}
Content-Type:	application/json

The example request is shown below:

url --request POST \
  --url https://connect.routee.net/sms \
  --header 'authorization: Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4' \
  --header 'content-type: application/json' \
  --header 'Expect:' \
  --data '{ 
  "body": "A new game has been posted to the MindPuzzle. Check it out",
  "to" : "+306912345678",
  "from": "447123123456"
  }'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}");
Request request = new Request.Builder()
  .url("https://connect.routee.net/sms")
  .post(body)
  .addHeader("authorization", "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://connect.routee.net/sms");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4");
request.AddParameter("application/json", "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/sms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/sms/campaign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\n  \"body\": \"Hello, a new version of MindPuzzle is available. Check it out\",\n  \"to\" : [ \"+30697xxxxxxx\", \"+30694xxxxxxx\", \"+30693xxxxxxx\" ], \n  \"from\": \"447123123456\"\n  \n}",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e",
    "Cache-Control: no-cache",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import http.client

conn = http.client.HTTPSConnection("connect.routee.net")

payload = "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}"

headers = {
    'authorization': "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    'content-type': "application/json"
    }

conn.request("POST", "/sms", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://connect.routee.net/sms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4'
request["content-type"] = 'application/json'
request.body = "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}"

response = http.request(request)
puts response.read_body

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://connect.routee.net/sms",
  "method": "POST",
  "headers": {
    "authorization": "Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
    "content-type": "application/json"
  },
  "processData": false,
  "data": "{ \"body\": \"A new game has been posted to the MindPuzzle. Check it out\",\"to\" : \"+306912345678\",\"from\": \"447123123456\"}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer 12dc9fe4-7df4-4786-8d7a-a46d307687f4",
                           @"content-type": @"application/json" };
NSDictionary *parameters = @{ @"body": @"A new game has been posted to the MindPuzzle. Check it out",
                              @"to": @"+306912345678",
                              @"from": @"447123123456" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://connect.routee.net/sms"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

Now you will receive the inbound messages in defined callback URL as the following payload:

{
  "messageId": "700bbc09-0556-4e86-bad1-215a8020e111",
  "from": "+30697xxxxxxx",
  "to": "+447123123456",
  "message": "This is the actual body of the inbound message",
  "parts": 1,
  "originatingService": "Sms",
  "direction": "Inbound",
  "receivedDate": "2018-01-24T13:02:08Z"
}

Also, your inbound messages can be tracked through the SMS tracking resource.

Example:

https://connect.routee.net/sms/tracking

You can apply filters to receive the inbound messages for a specific time range as below.

curl -X POST \
  'https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00' \
  -H 'Authorization: Bearer 1f200887-d757-4f50-94a7-a08a882086ee' \
  -H 'Content-Type: application/json' \
  -d '[{"fieldName": "direction", "searchTerm": "Inbound"}]'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]");
Request request = new Request.Builder()
  .url("https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00")
  .post(body)
  .addHeader("Authorization", "Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

var client = new RestClient("https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e");
request.AddParameter("undefined", "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import http.client

conn = http.client.HTTPConnection("connect,routee,net")

payload = "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]"

headers = {
    'Authorization': "Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e",
    'Content-Type': "application/json"
    }

conn.request("POST", "sms,tracking", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e'
request["Content-Type"] = 'application/json'
request.body = "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]"

response = http.request(request)
puts response.read_body

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e",
    "Content-Type": "application/json"
  },
  "processData": false,
  "data": "[{\"fieldName\": \"direction\", \"searchTerm\": \"Inbound\"}]"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"Authorization": @"Bearer 099d1d57-7ac9-4d58-8a5c-b611d689ca4e",
                           @"Content-Type": @"application/json"};
NSDictionary *parameters = @[ @{ @"fieldName": @"direction", @"searchTerm": @"Inbound" } ];

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://connect.routee.net/sms/tracking?dateEnd=2018-01-24T23:59:59%2B03:00&dateStart=2018-01-23T00:00:00%2B03:00"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

You will get the following response:

{
    "content": [
        {
            "messageId": "dcc5776b-9490-4ccb-8038-05803404be9b",
            "to": "+447123123456",
            "groups": [],
            "body": "This is the actual body of the inbound message",
            "originatingService": "Sms",
            "parts": 1,
            "price": 0.03,
            "from": "+30697xxxxxxx",
            "direction": "Inbound",
            "receivedDate": "2018-01-24T13:02:08Z"
        },
        {
            "messageId": "8c08120d-b166-4fcc-a1a3-bc3cbf87308a",
            "to": "+447123123456",
            "groups": [],
            "body": "This is the actual body of the inbound message",
            "originatingService": "Sms",
            "parts": 1,
            "price": 0.03,
            "from": "+30694xxxxxxx",
            "direction": "Inbound",
            "receivedDate": "2018-01-24T08:20:34Z"
        }
    ],
    "totalElements": 2,
    "totalPages": 1,
    "last": true,
    "first": true,
    "numberOfElements": 2,
    "size": 20,
    "number": 0
}