Sign up Log In
NAV
http shell ruby php python csharp vb javascript go java

Introduction

Welcome to the Zensend API.

You can use our API to send SMS messages to phones or perform number insights for mobile numbers.

Zensend has language bindings in Shell and the following:

View code examples to the right of this page and select your programming language using the tabs at the top of the page.

Authentication

To authorize, use this code:

GET /v3/checkbalance HTTP/1.1
User-Agent: curl/7.30.0
Host: api.zensend.io
Accept: */*
X-API-KEY: api_key
# With shell, you can just pass the correct header with each request
curl "https://api.zensend.io" \
  -H "X-API-KEY: api_key"
require 'zensend'

client = ZenSend::Client.new("api_key")
<?php
$client = new ZenSend\Client("api_key");
?>
import zensend
client = zensend.Client("api_key")
using ZenSend;
var client = new Client("api_key");
Imports ZenSend
Dim client As Client = New Client("api_key")
var zensend = require('zensend');
var client = new zensend.Client("api_key");
import(
  "zensend"
)

client := zensend.New("api_key")
import io.zensend.*;

Client client = new Client("api_key");

Make sure to replace api_key with your API key.

Zensend uses API keys to allow access to the API. When you create an account an API key is automatically generated for you. You can register for a new account at our developer portal.

Zensend expects the API key to be included in all API requests to the server in a header that looks like the following:

X-API-KEY: api_key

Endpoints

Send SMS

POST /v3/sendsms HTTP/1.1
User-Agent: curl/7.30.0
Host: api.zensend.io
Accept: */*
X-API-KEY: api_key
Content-Length: 90

ORIGINATOR=SPINTOWIN&NUMBERS=447711122233,447722233344&BODY=Welcome%20to%20spin%20to%20win
HTTP/1.1 200 OK
connection: close
server: Cowboy
date: Fri, 24 Apr 2015 10:34:01 GMT
content-length: 107
content-type: application/json

{"success":{"txguid":"f8223367-64a8-4f97-856d-56d57432eaf9","numbers":2,"smsparts":1,"encoding":"gsm","cost_in_pence":2.3,"new_balance_in_pence":500.0}}
HTTP/1.1 400 Bad Request
connection: close
server: Cowboy
date: Fri, 24 Apr 2015 10:37:13 GMT
content-length: 63
content-type: application/json

{"failure":{"parameter":"NUMBERS","failcode":"INVALID_NUMBER"}}
curl "https://api.zensend.io/v3/sendsms" \
  -d ORIGINATOR=SPINTOWIN \
  -d NUMBERS=447711122233 \
  -d BODY=Welcome%20to%20spin%20to%20win \
  -H "X-API-KEY: api_key"

# with all the options

curl "https://api.zensend.io/v3/sendsms" \
  -d ORIGINATOR=SPINTOWIN \
  -d NUMBERS=447711122233 \
  -d BODY=Welcome%20to%20spin%20to%20win \
  -d TIMETOLIVE=100 \
  -d ORIGINATOR_TYPE=alpha \
  -d ENCODING=gsm \
  -H "X-API-KEY: api_key"

require 'zensend'

client = ZenSend::Client.new("api_key")
result = client.send_sms(originator: "SPINTOWIN", numbers: ["447711122233"], body: "Welcome to spin to win")

# with all the options

result = client.send_sms(originator: "SPINTOWIN", numbers: ["447711122233"], body: "Welcome to spin to win", timetolive_in_minutes: 100, originator_type: :alpha, encoding: :gsm)

puts result.numbers # => 1
puts result.parts # => 1
puts result.encoding # => "gsm"
puts result.tx_guid # => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
puts result.cost_in_pence # => 2.3
puts result.new_balance_in_pence # => 500.0

# handling errors

begin
  client.send_sms(originator: "SPINTOWIN", numbers: ["447711122233"], body: "Welcome to spin to win")
rescue ZenSend::ZenSendException => e
  puts e.http_code # http status code 
  puts e.failcode # zensend error code (might be null)
  puts e.parameter # the parameter the failcode is related to (might be nil)
rescue StandardError => e
  puts e # exception raised by net/http Errno::EHOSTUNREACH, Errno::ETIMEDOUT, Net::ReadTimeout, etc (http://ruby-doc.org/stdlib-2.2.2/libdoc/net/http/rdoc/Net/HTTP.html)
end

<?php
$client = new ZenSend\Client("api_key");

$request = new ZenSend\SmsRequest();
$request->body = "Welcome to spin to win";
$request->originator = "SPINTOWIN";
$request->numbers = ["447711122233"];
$result = $client->send_sms($request);

// with all the options

$request = new ZenSend\SmsRequest();
$request->body = "Welcome to spin to win";
$request->originator = "SPINTOWIN";
$request->numbers = ["447711122233"];
$request->timetolive_in_minutes = 100;
$request->originator_type = "alpha";
$request->encoding = "gsm";
$result = $client->send_sms($request);

print $result->numbers; // 1
print $result->sms_parts; // 1
print $result->encoding; // "gsm"
print $result->tx_guid; // "7CDEB38F-4370-18FD-D7CE-329F21B99209"
print $result->cost_in_pence; // 2.3
print $result->new_balance_in_pence; // 500.0

// handling errors

$request = new ZenSend\SmsRequest();
$request->body = "Welcome to spin to win";
$request->originator = "SPINTOWIN";
$request->numbers = ["447711122233"];


try {
  $result = $client->send_sms($request);
} catch (ZenSend\NetworkException $e) {
  print $e->curl_error; // the error code from curl (http://curl.haxx.se/libcurl/c/libcurl-errors.html)
  print $e->curl_message; // a readable message for the error code

} catch (ZenSend\ZenSendException $e) {
  print $e->http_code; // http status code 
  print $e->failcode; // zensend error code (might be null)
  print $e->parameter; // the parameter the failcode is related to (might be null)
}

?>
import zensend
client = zensend.Client("api_key")
result = client.send_sms(body = "Welcome to spin to win", originator = "SPINTOWIN", numbers = ["447711122233"])

# with all the options

result = client.send_sms(body = "Welcome to spin to win", originator = "SPINTOWIN", numbers = ["447711122233"], timetolive_in_minutes = 100, originator_type = "alpha", encoding = "gsm")

print result.numbers # 1
print result.sms_parts # 1
print result.encoding # "gsm"
print result.tx_guid # "7CDEB38F-4370-18FD-D7CE-329F21B99209"
print result.cost_in_pence # 2.3
print result.new_balance_in_pence # 500.0

# handling errors

import requests

try:
  client.send_sms(body = "Welcome to spin to win", originator = "SPINTOWIN", numbers = ["447711122233"])
except zensend.ZenSendException as e:
  print e.http_code # http status code
  print e.failcode # zensend error code (might be nil)
  print e.parameter # the parameter the failcode is related to (might be nil)
except requests.exceptions.RequestException as e:
  print e # details here: http://docs.python-requests.org/en/latest/user/quickstart/#errors-and-exceptions
except:
  print sys.exc_info()[0]
using ZenSend;

var client = new Client("api_key");
var result = client.SendSms(originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: new string[]{"447711122233"});

// with all the options

result = client.SendSms(originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: new string[]{"447711122233"}, originatorType: OriginatorType.Alphanumeric, timeToLiveInMinutes: 100, encoding: SmsEncoding.GSM);

Console.WriteLine(result.Numbers); // => 1
Console.WriteLine(result.SmsParts); // => 1
Console.WriteLine(result.Encoding); // => "gsm"
Console.WriteLine(result.TxGuid); // => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
Console.WriteLine(result.CostInPence); // => 2.3
Console.WriteLine(result.NewBalanceInPence); // => 500.0

// handling errors

try {
  client.SendSms(originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: new string[]{"447711122233"});
} catch (System.Net.WebException e) {
  Console.WriteLine(e); // see https://msdn.microsoft.com/en-us/library/system.net.webexception(v=vs.110).aspx
} catch (ZenSendException e) {
  Console.WriteLine(e.HttpStatus); // => http status code
  Console.WriteLine(e.FailCode); // => zensend error code (might be null)
  Console.WriteLine(e.Parameter); // => the parameter the failcode is related to (might be null)
}
var zensend = require('zensend');
var client = new zensend.Client("api_key");
client.sendSms({originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: ["447711122233"]}, function(error, response){
  console.log(response.tx_guid); // => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
  console.log(response.sms_parts); // => 1
  console.log(response.encoding); // => "gsm"
  console.log(response.numbers); // 1
  console.log(response.cost_in_pence); // 2.3
  console.log(response.new_balance_in_pence); // 500.0
});

// with all the options

client.sendSms({originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: ["447711122233"], originator_type: "alpha", time_to_live_in_minutes: 100, encoding: "gsm"}, function(error, response){
  console.log(response.tx_guid); // => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
  console.log(response.sms_parts); // => 1
  console.log(response.encoding); // => "gsm"
  console.log(response.numbers); // 1
  console.log(response.cost_in_pence); // 2.3
  console.log(response.new_balance_in_pence); // 500.0
});

// handling errors

client.sendSms({originator: "SPINTOWIN", body: "Welcome to spin to win", numbers: ["447711122233"]}, function(error, response){

  if (error != null) {
    if (error instanceof zensend.ZenSendError) {
      console.log(error.statuscode); // => http status code
      console.log(error.failcode);  // => zensend error code (might be undefined)
      console.log(error.parameter); // => the parameter the failcode is related to (might be undefined)
    } else {
      // http error. ie: ECONNREFUSED, etc
      console.log(error);
    }
  }
}


Imports ZenSend

Dim client As Client = New Client("api_key") 
Dim numbers() As String = {"447711122233"}
Dim result As SmsResult =  client.SendSms(originator:= "SPINTOWIN", body:= "Welcome to spin to win", numbers:= numbers)

'with all the options

result =  client.SendSms(originator:= "SPINTOWIN", body:= "Welcome to spin to win", numbers:= numbers, originatorType:= OriginatorType.Alphanumeric, timeToLiveInMinutes:= 100, encoding:= SmsEncoding.GSM)

Console.WriteLine(result.Numbers) ' => 1
Console.WriteLine(result.SmsParts) ' => 1
Console.WriteLine(result.Encoding) ' => "gsm"
Console.WriteLine(result.TxGuid) ' => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
Console.WriteLine(result.CostInPence) ' => 2.3
Console.WriteLine(result.NewBalanceInPence) ' => 500.0

' handling errors

Try

  Dim numbers() As String = {"447711122233"}
  Dim result As SmsResult =  client.SendSms(originator:= "SPINTOWIN", body:= "Welcome to spin to win", numbers:= numbers)
Catch e As System.Net.WebException
  Console.WriteLine(e) ' see https://msdn.microsoft.com/en-us/library/system.net.webexception(v=vs.110).aspx
Catch e As ZenSendException

  Console.WriteLine(e.HttpStatus) ' => http status code
  Console.WriteLine(e.FailCode) ' => zensend error code (might be null)
  Console.WriteLine(e.Parameter) ' => the parameter the failcode is related to (might be null)
End Try

import(
  "zensend"
  "log"
)

client := zensend.New("api_key")
response, error := client.SendSMS(&zensend.Message{
                     Body: "This is a test",
                     Originator: "Originator",
                     Numbers: []string{"447711122233"},
})

// with all the options

response, error := client.SendSMS(&zensend.Message{
                     Body: "This is a test",
                     Originator: "Originator",
                     Numbers: []string{"447711122233"},
                     OriginatorType: zensend.ALPHA,
                     TimeToLiveInMinutes: 100,
                     Encoding: zensend.GSM,            
})

log.Println(result.TxGuid) // => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
log.Println(result.SmsParts) // => 1
log.Println(result.Encoding) // => "gsm"
log.Println(result.Numbers) // => 1
log.Println(result.CostInPence) // => 2.3
log.Println(result.NewBalanceInPence) // => 500.0

// handling errors

response, error := client.SendSMS(&zensend.Message{
                     Body: "This is a test",
                     Originator: "Originator",
                     Numbers: []string{"447711122233"},
})

if error != nil {
  switch error := error.(type) {
    case zensend.ZenSendError:
      log.Println(error.StatusCode) // => http status code
      log.Println(error.FailCode) // => zensend error code (might be empty)
      log.Println(error.Parameter) // => the parameter the failcode is related to (might be empty)
    default:
      log.Println(error)
  }
}

import io.zensend.*;

Message message = new Message();
message.numbers = new String[]{"447711122233"};
message.body = "Welcome to spin to win";
message.originator = "SPINTOWIN";

Client client = new Client("api_key");

SmsResult result = client.sendSms(message);

// with all the options

message = new Message();
message.numbers = new String[]{"447711122233"};
message.body = "Welcome to spin to win";
message.originator = "SPINTOWIN";
message.originatorType = Message.OriginatorType.ALPHA;
message.smsEncoding = Message.SmsEncoding.GSM;
message.timeToLiveInMinutes = 100;
result = client.sendSms(message);


System.out.println(result.numbers); // => 1
System.out.println(result.smsParts); // => 1
System.out.println(result.encoding); // => "gsm"
System.out.println(result.txGuid); // => "7CDEB38F-4370-18FD-D7CE-329F21B99209"
System.out.println(result.costInPence); // => 2.3
System.out.println(result.newBalanceInPence); // => 500.0

// handling errors

try {
  client.sendSms(message);
} catch (IOException e) {
  System.out.println(e);
} catch (ZenSendException e) {
  System.out.println(e.httpCode); // => http status code
  System.out.println(e.failCode); // => zensend error code (might be null)
  System.out.println(e.parameter); // => the parameter the failcode is related to (might be null)
}

HTTP Request

POST https://api.zensend.io/v3/sendsms

Post Parameters

Parameter Default Description
BODY The body of the message. It is possible to send up to 160 gsm or 70 ucs2 characters in a single SMS message. If the BODY can’t be fit into a single message it will be automatically split into multiple messages. For gsm messages these parts will each contain up to 153 characters and for ucs2 encoding these messages will contain up to 67 characters. The maximum number of parts that can be generated is 8. If more are required an error will be generated.
ORIGINATOR The msisdn (or alpha originator) that this message will appear to come from. The maximum length of a alpha originator is 11 characters and msisdn orginators must be formated in international format. For example a UK msisdn would be in the format 447722233344.
ORIGINATOR_TYPE alpha Indicates whether the originator is a text originator (alpha) or a number (msisdn).
NUMBERS The numbers to send the message to. The maxmium number of numbers allowed is 100. The numbers must be international format. For example a UK number would be in the format 447722233344.
TIMETOLIVE 4320 Sets the validity period of the SMS message in minutes. Once the message can no longer be delivered through retries inside this period, then a ‘Delivery Failed DR’ will be returned to you. Minimum value: 10 minutes. Maximum value: 4320 minutes.
ENCODING Explicitly set the encoding of the message. If this is not specified the best encoding will automatically be chosen. If the message only contains GSM characters then GSM encoding will be used otherwise UCS2 encoding will be chosen. The encoding can be explicitly be set to ucs2 or gsm. If gsm encoding is selected and non-gsm characters are present they will be replaced with a question mark (?).

Failcodes

When there is a problem with the request a failcode will be returned and optionally the name of the parameter that caused the problem.

The following is a list of failcodes that might be generated.

Error Code Meaning
OUT_OF_RANGE A request parameter value can’t be accepted.
IS_EMPTY A mandatory request parameter is empty.
TOO_MANY_NUMBERS Too many numbers specified.
INVALID_NUMBER Number is incorrectly formatted.
TOO_MANY_CHARACTERS A request parameter is too long.
INVALID_CHARACTERS A request parameter has invalid chars

Encoding

SMS messages are encoded in either GSM or ucs2 encoding. A single gsm encoded message can take 160 characters while a ucs2 message can only take 70 characters. Some special gsm extended characters count for two characters. All strings sent to the API should be encoded in UTF-8 if a byte sequence is encountered that is not valid UTF-8 an ENCODING error will be returned.

Normal GSM Characters

!“#$%&’()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz¡£¤¥§¿ÄÅÆÇÉÑÖØÜßàäåæèéìñòöøùüΓΔΘΛΞΠΣΦΨΩ

Extended Characters (Cost 2)

^|{}€[~]</span>

Balance

GET /v3/checkbalance HTTP/1.1
User-Agent: curl/7.30.0
Host: api.zensend.io
Accept: */*
X-API-KEY: api_key
HTTP/1.1 200 OK
connection: close
server: Cowboy
date: Thu, 28 May 2015 14:19:25 GMT
content-length: 29
content-type: application/json

{"success":{"balance":500.0}}
curl "https://api.zensend.io/v3/checkbalance"
  -H "X-API-KEY: api_key"
require 'zensend'

client = ZenSend::Client.new("api_key")
balance = client.check_balance

puts balance # => 500.0 (balance in pence)
<?php
$client = new ZenSend\Client("api_key");
$balance = $client->check_balance();
echo $balance; # => 500 (balance in pence)
?>
import zensend
client = zensend.Client("api_key")
balance = zensend.check_balance()
print balance # => 500.0 (balance in pence)
using ZenSend;

var client = new Client("api_key");
var balance = client.CheckBalance();

Console.WriteLine(balance) // => 500.0 (balance in pence)
var zensend = require('zensend');
var client = new zensend.Client("api_key");
client.checkBalance(function(error, balance){
  console.log(balance); // => 500.0 (balance in pence)
});
Imports ZenSend

Dim client As Client = New Client("api_key")

Dim balance as Decimal = client.CheckBalance()

Console.WriteLine(balance) ' => 500.0 (balance in pence)
import(
  "zensend"
  "log"
)

client := zensend.New("api_key")
balance, error := client.CheckBalance()

log.Println(balance) // => 500.0 (balance in pence)
import io.zensend.*;
import java.math.*;

Client client = new Client("api_key");
BigDecimal balance = client.checkBalance();

System.out.println(balance) // => 500.0 (balance in pence)

This endpoint retrieves the current balance of the account in pence.

HTTP Request

GET https://api.zensend.io/v3/checkbalance

Prices

GET /v3/prices HTTP/1.1
User-Agent: curl/7.30.0
Host: api.zensend.io
Accept: */*
X-API-KEY: api_key
HTTP/1.1 200 OK
connection: close
server: Cowboy
date: Thu, 28 May 2015 14:19:25 GMT
content-length: 28
content-type: application/json

{"success":{"prices_in_pence":{"GB":100.0}}}
curl "https://api.zensend.io/v3/prices"
  -H "X-API-KEY: api_key"
require 'zensend'

client = ZenSend::Client.new("api_key")
prices = client.get_prices

puts prices # => {"GB"=>100.0} (price in pence)
<?php
$client = new ZenSend\Client("api_key");
$prices = $client->get_prices();
print_r($prices); // => Array
                  // (
                  //   [GB] => 100 (price in pence)
                  // )
?>
import zensend
client = zensend.Client("api_key")
prices = zensend.get_prices()
print prices # => {'GB': 100.0} (price in pence)
using ZenSend;

var client = new Client("api_key");
var prices = client.GetPrices();

Console.WriteLine(prices) // => System.Collections.Generic.Dictionary`2[System.String,System.Decimal]
Console.WriteLine(string.Join(";", prices.Select(x => x.Key + "=" + x.Value))) // => GB=100.0 (price in pence)
Imports ZenSend
Imports System.Collections.Generic

Dim client As Client = New Client("api_key")

Dim prices as Dictionary(Of String, Decimal) = client.GetPrices()

Console.WriteLine(prices) ' => System.Collections.Generic.Dictionary`2[System.String,System.Decimal]

var zensend = require('zensend');
var client = new zensend.Client("api_key");
client.getPrices(function(error, prices){
  console.log(prices); // => { GB: 100 } (price in pence)
});
import(
  "zensend"
  "log"
)

client := zensend.New("api_key")
prices, error := client.GetPrices()

log.Println(prices) // => map[GB:100] (price in pence)
import io.zensend.*;
import java.math.*;
import java.util.*;

Client client = new Client("api_key");
Map<String, BigDecimal> prices = client.getPrices();

System.out.println(prices) // => GB=100.0 (price in pence)

This endpoint retrieves the current prices in pence for sms messages based on destination country.

HTTP Request

GET https://api.zensend.io/v3/prices

Number Insight

GET /v3/operator_lookup?NUMBER=447711122233 HTTP/1.1
User-Agent: curl/7.37.1
Host: api.zensend.io
Accept: */*
X-API-KEY: api_key
HTTP/1.1 200 OK
connection: close
server: Cowboy
date: Fri, 24 Apr 2015 10:34:01 GMT
content-length: 107
content-type: application/json

{"success":{"mcc":"234","mnc":"34","operator":"eeora-uk","new_balance_in_pence":194.006,"cost_in_pence":2.0}}
HTTP/1.1 503 Service Unavailable
connection: close
server: Cowboy
date: Tue, 16 Jun 2015 10:16:44 GMT
content-length: 92
content-type: application/json

{"failure":{"failcode":"SYSTEM_FAILURE","new_balance_in_pence":190.006,"cost_in_pence":2.0}}
curl "https://api.zensend.io/v3/operator_lookup?NUMBER=447711122233"
  -H "X-API-KEY: api_key"
require 'zensend'

client = ZenSend::Client.new("api_key")
response = client.lookup_operator("447711122233")

puts response.mnc # => "34"
puts response.mcc # => "234"
puts response.operator # => "eeora-uk"
puts response.new_balance_in_pence # => 190.006
puts response.cost_in_pence # => 2.0
<?php
$client = new ZenSend\Client("api_key");
$response = $client->lookup_operator("447711122233");
echo $response->mnc; # => "34"
echo $response->mcc; # => "234"
echo $response->operator; # => "eeora-uk"
echo $response->cost_in_pence; # => 2.0
echo $response->new_balance_in_pence; # => 190.006
?>
import zensend
client = zensend.Client("api_key")
response = client.lookup_operator("447711122233")
print response.mnc # => "34"
print response.mcc # => "234"
print response.operator # => "eeora-uk"
print response.cost_in_pence # => 2.0
print response.new_balance_in_pence # => 190.006
using ZenSend;

var client = new Client("api_key");
var response = client.LookupOperator("447711122233");

Console.WriteLine(response.MNC); // => "34"
Console.WriteLine(response.MCC); // => "234"
Console.WriteLine(response.Operator); // => "eeora-uk"
Console.WriteLine(response.CostInPence); // => 2.0
Console.WriteLine(response.NewBalanceInPence); // => 190.006
Imports ZenSend
Dim client As Client = New Client("api_key")

Dim response as OperatorLookupResult = client.LookupOperator("447711122233")

Console.WriteLine(response.MNC) ' => "34"
Console.WriteLine(response.MCC) ' => "234"
Console.WriteLine(response.Operator) ' => "eeora-uk"
Console.WriteLine(response.CostInPence) ' => 2.0
Console.WriteLine(response.NewBalanceInPence) ' => 190.006
var zensend = require('zensend');
var client = new zensend.Client("api_key");
client.lookupOperator("447711122233", function(error, response){
  console.log(response.mnc); // => "34"
  console.log(response.mcc); // => "234"
  console.log(response.operator); // "eeora-uk"
  console.log(response.cost_in_pence); // => 2.0
  console.log(response.new_balance_in_pence); // 190.006
});
import(
  "zensend"
  "log"
)

client := zensend.New("api_key")
response, error := client.LookupOperator("447711122233")

log.Println(response.MNC) // => "34"
log.Println(response.MCC) // => "234"
log.Println(response.Operator) // => "eeora-uk"
log.Println(response.CostInPence) // => 2.0
log.Println(response.NewBalanceInPence) // => 190.006
import io.zensend.*;

Client client = new Client("api_key");
OperatorLookupResult response = client.lookupOperator("447711122233");

System.out.println(response.mnc) // => "34"
System.out.println(response.mcc) // => "234"
System.out.println(response.operator) // => "eeora-uk"
System.out.println(response.costInPence) // => 2.0
System.out.println(response.newBalanceInPence) // => 190.006

This endpoint looks up network information for a mobile phone number.

HTTP Request

GET https://api.zensend.io/v3/operator_lookup

Query Parameters

Parameter Description
NUMBER The numbers to lookup. The number must be international format. For example a UK number would be in the format 447722233344.

Failcodes

When there is a problem with the request a failcode will be returned and optionally the name of the parameter that caused the problem.

The following is a list of failcodes that might be generated.

Error Code Meaning
INVALID_NUMBER Number is incorrectly formatted.
DATA_MISSING The data was missing
UNKNOWN_SUBSCRIBER The subscriber is unknown
CALL_BARRED The service is restricted by the destination network
ABSENT_SUBSCRIBER_SM The subscriber is absent
UNEXPECTED_DATA_VALUE An unexpected data value in the request
SYSTEM_FAILURE A system failure occurred in the HLR lookup
FACILITY_NOT_SUPPORTED Short message facility is not supported
TELE_SERVICE_NOT_PROVISIONED SMS teleservice is not provisioned
HLR_REJECT The HLR request was rejected
HLR_ABORT The HLR (or some other entity) aborted the request. No response to the request was received
HLR_LOCAL_CANCEL No response for the HLR request was received
TIMEOUT No response to the request was received
REQUEST_THROTTLED Maximum ongoing requests exceeded
IMSI_LOOKUP_BLOCKED Request is blocked

Charging

All authenticated requests with a valid msisdn will result in a charge against your account. This API is different from the others in that it may return a cost_in_pence and new_balance_in_pence in the failure result as well as the success result.

Keyword Purchase

POST /v3/keywords HTTP/1.1
Host: api.zensend.io
User-Agent: curl/7.43.0
Accept: */*
X-API-KEY: api_key
Content-Length: 25
Content-Type: application/x-www-form-urlencoded

SHORTCODE=666&KEYWORD=NEW
HTTP/1.1 200 OK
connection: close
server: Cowboy
date: Tue, 17 May 2016 13:18:54 GMT
content-length: 66
X-Runtime: 0.037693
X-Request-Id: 2bda9da9-c48e-4840-a4d7-630a2d4a16be
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json; charset=utf-8

{"success":{"cost_in_pence":452.0,"new_balance_in_pence":3222.25}}
HTTP/1.1 400 Bad Request
connection: close
server: Cowboy
date: Tue, 17 May 2016 13:17:16 GMT
content-length: 63
X-Runtime: 0.632688
X-Request-Id: edc92850-7246-43d8-a70c-34b6b4255a35
Cache-Control: no-cache
Content-Type: application/json; charset=utf-8

{"failure":{"failcode":"KEYWORD_EXISTS","parameter":"KEYWORD"}}
curl -v -H X-API-KEY:api_key -d 'SHORTCODE=666&KEYWORD=NEWX' 'https://api.zensend.io/v3/keywords'
require 'zensend'

client = ZenSend::Client.new("api_key")
response = client.create_keyword(shortcode: "666", keyword: "NEW")

puts response.new_balance_in_pence # => 2770.25
puts response.cost_in_pence # => 452.0
<?php
$client = new ZenSend\Client("api_key");
$request = new ZenSend\CreateKeywordRequest();
$request->shortcode = "666";
$request->keyword = "NEW";

$response = $client->create_keyword($request);
echo $response->cost_in_pence; # => 452
echo $response->new_balance_in_pence; # => 190.006
?>
import zensend
client = zensend.Client("api_key")
response = client.create_keyword(shortcode = "666", keyword = "NEW")
print response.cost_in_pence # => 452
print response.new_balance_in_pence # => 190.006
using ZenSend;

var client = new Client("api_key");
var response = client.CreateKeyword(shortcode: "SHORTCODE", keyword: "NEW")

Console.WriteLine(response.CostInPence) // => 452
Console.WriteLine(response.NewBalanceInPence) // => 190.006
Imports ZenSend
Dim client As Client = New Client("api_key")

Dim response as CreateKeywordResult = client.CreateKeyword(shortcode:= "666", keyword:= "NEW")

Console.WriteLine(response.CostInPence) ' => 452
Console.WriteLine(response.NewBalanceInPence) ' => 190.006
var zensend = require('zensend');
var client = new zensend.Client("api_key");
client.createKeyword({shortcode: "666", keyword: "NEW"}, function(error, response){
  console.log(response.cost_in_pence); // => 452
  console.log(response.new_balance_in_pence); // 190.006
});
import(
  "zensend"
  "log"
)

client := zensend.New("api_key")
response, error := client.CreateKeyword(&zensend.CreateKeywordRequest{Shortcode: "666", Keyword: "NEW"})

log.Println(response.CostInPence) // => 2.0
log.Println(response.NewBalanceInPence) // => 190.006
import io.zensend.*;

Client client = new Client("api_key");
CreateKeywordRequest request = new CreateKeywordRequest();
request.shortcode = "666";
request.keyword = "NEW";

CreateKeywordResult response = client.createKeyword(request);

System.out.println(response.costInPence) // => 2.0
System.out.println(response.newBalanceInPence) // => 190.006

This endpoint creates keywords on a shortcode for receiving messages from phones.

HTTP Request

POST https://api.zensend.io/v3/keywords

Query Parameters

Parameter Description
SHORTCODE The shortcode to create the keyword on.
KEYWORD The keyword you want to create. Must not be a reserved keyword such as STOP/A-Z/Male/Female/0-9/Yes/No or contain the following characters: ’?!., ’
MO_URL Optional custom URL to send messages to. If not specified messages will be sent to the default URL on the account.
IS_STICKY Specifies whether the keyword is sticky to allow users to continue to send you messages after submitting the first keyword without specifying a keyword on subsequent messages.

Failcodes

When there is a problem with the request a failcode will be returned and optionally the name of the parameter that caused the problem.

The following is a list of failcodes that might be generated.

Error Code Meaning
NEED_PURCHASE A deposit is required on the account before purchasing a keyword.
INSUFFICIENT_FUNDS There is not enough credit on the account for the initial payment for the keyword
SHORTCODE_MISSING The shortcode does not exist
KEYWORD_EXISTS A keyword with the same name already exists
KEYWORD_RESERVED The keyword is a reserved name
INVALID_KEYWORD The keyword contains invalid characters
INVALID_URL The MO URL is invalid

Charging

The cost of keywords will be charged according to the pricing on our website. There will be an initial pro-rated charge in advance for the first month then each month will be charged in advance for the whole month.

Sub Account Creation

POST /v3/sub_accounts HTTP/1.1
Host: api.zensend.io
User-Agent: curl/7.43.0
Accept: */*
X-API-KEY: api_key
Content-Length: 25
Content-Type: application/x-www-form-urlencoded

NAME=my%20new%20subaccount
HTTP/1.1 201 Created
connection: close
Date: Thu, 01 Dec 2016 14:13:50 GMT
content-length: 66
X-Runtime: 0.045367
X-Request-Id: fc700a4a-5b7c-4166-bfba-3f60bb182150
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json; charset=utf-8

{"success":{"name":"my new subaccount","api_key":"new_api_key"}}
POST /v3/sub_accounts HTTP/1.1
Host: api.zensend.io
User-Agent: curl/7.43.0
Accept: */*
X-API-KEY: api_key
Content-Length: 25
Content-Type: application/x-www-form-urlencoded

NAME=my%20new%20subaccount
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: no-cache
X-Request-Id: e1b7389e-7c8b-47d7-a8e7-11fcd3892312
X-Runtime: 0.036441
Date: Thu, 01 Dec 2016 14:49:14 GMT
Connection: close

{"failure":{"failcode":"NAME_EXISTS"}}
curl -v -H X-API-KEY:api_key -d 'NAME=my%20new%20subaccount' 'https://api.zensend.io/v3/sub_accounts'

Sub accounts can be created dynamically using a POST request. There is a limit of 30 accounts per zensend user. Each request should contain a unique sub account name to be allocated. The response will include the given name and a new API KEY generated for the sub account.

Failcodes

When there is a problem with the request a failcode will be returned describing the error occurred.

The following is a list of failcodes that might be generated.

Error Code Meaning
NOT_MAIN_ACCOUNT_KEY Request needs to include the API KEY of your Main Account in the header
NAME_MISSING NAME parameter is missing in the submitted request
NAME_EXISTS A sub account with the given name already exists
QUOTA_REACHED Maximum number of sub accounts have already been created. Limit is 30
SYSTEM_FAILURE An internal error occurred

Callbacks

SMS Delivery Receipts

When a SMS is delivered to a handset or fails to be delivered a URL on your platform can be configured to receive the status of the message. This will be done using a POST request with the following parameters.

Post Parameters

Parameter Description
MONUMBER The msisdn for the delivery receipt in international format. For example a UK msisdn would be in the format 447722233344.
DESTINATION The ORIGINATOR from the SMS sending request.
STATUSCODE Indicates whether the SMS was delivered. If delivered will be DELIVERED otherwise indicates the error.
STATUSTEXT A human description of STATUSCODE.
GUID The tx_guid value from the SMS sending request. This can be used to match a request to the response.
STATUSTIME Timestamp when the DR was created in the format yyyyMMddHHmmss
PART If the SMS sending request created multiple parts then this indicates then this is the 1-based index indicating which part this receipt is for.
TOTAL_PARTS IF the SMS sending request created multiple parts then this indicates how many parts were created.
DURATION The amount of time in seconds between when the SMS request was submitted and when the DR was created.

The STATUSCODE will be one of the following values:

Code Description
DELIVERED MT message successfully delivered
INSUFFICIENT_FUNDS User didn’t have enough money
INVALID_MSISDN Mobile number not accepted by operator
INVALID_OPERATOR_SERVICE Request type not accepted by operator
INVALID_ORIGINATOR Originator not accepted by operator
OPERATOR_REJECTED Request not accepted by operator
OPERATOR_TIMEOUT Request not acknowledged by operator (May have been sent)
PERMANENT_OPERATOR_ERROR Request permanently failed by operator
PERMANENTLY_BARRED User is permanently barred from request type
SMSC_ERROR Operator SMSC encountered a processing error
TEMPORARY_BARRED User is temprorarely barred from request type
TEMPORARY_OPERATOR_ERROR Request temprorarely failed by operator
UNKNOWN_MSISDN Mobile number not known to operator
UNREACHABLE_MSISDN User mobile is switched off or absent
UNROUTABLE We can’t process the request due to a missing route
UNKNOWN_ERROR Something went wrong, - the request failed

Incoming Messages

When a phone sends a message to a keyword or a long number configured on your account they will be delivered to a URL configured on your platform. This will be done with a POST request with the following parameters:

Post Parameters

Parameter Description
MONUMBER The msisdn where the message came from in international format. For example a UK msisdn would be in the format 447722233344.
DESTINATION The shortcode or virtual mobile number this message was sent to.
RECEIVETIME Timestamp when the message was received in the format yyyyMMddHHmmss
GUID A unique ID that can be used to deduplicate requests from the platform.
BODY If the SMS message is not binary this will contain the message content. If the phone sent in a multipart message it is possible that this will contain more than 160 characters.
BINBODY If the SMS message is binary this will contain the binary content of the message hex encoded.
BINHEADER If the SMS message is binary and included a user data header this is the UDH value hex encoded.
PART If the SMS message was multipart and we failed to reassemble the message this is the 1-based index for the part number.
TOTAL_PARTS If the SMS message was multipart and we failed to reassemble the message this contains the total number of parts.
CSMS_REF If the SMS message was multipart and we failed to reassemble the message this is the ID used to correlate multiple parts.

Most customers will only be interested in MONUMBER, DESTINATION, RECEIVETIME, GUID and BODY the other parameters are included for handling edge cases.

We will try and reassemble multipart SMS messages received from phones. However, if this fails you may receive messages with PART/TOTAL_PARTS/CMS_REF parameters.

Errors

Error Code Meaning
400 Bad Request – The request is invalid
403 Unauthorized – The API key is incorrect or has been expired.
503 Service Unavailable – There was a problem processing the request.