Create and Send Code

Send a verification code to a mobile number.

The Verify method allows you to send a verification code to an international or local phone number.



to*stringThe phone number to send to. This should be in international format (e.g. 447123123456), or if countryIsoCode is specified, in local format (e.g. 07123123456)
from*stringA string containing the from value. This can be either: Numeric: between 2-15 characters, permitted characters 0-9 Alphanumeric: between 2-11 characters 0-9, a-z, A-Z, hyphen, underscore, full-stop and space e.g. MAYFLOWER. If no originator is set this will automatically assign a default number so that the recipient may reply to the message. If you have purchased a dedicated number this can be used as the originator
countryIsoCodestringAn optional country in ISO 3166-1 alpha-3 format. If specified, the to field can contain a number in local format, e.g. GBR would allow 07123123456
bodystringAn optional message to use. If not specified, the default message of Your verification code is {{code}} will be sent. If overriding, you must include a {{code}} placeholder. You can optionally include {{validMinutes}} to insert the number of minutes the code is valid for.
validUntilDateTimeA date time specifying when the code is valid until and how long we should try to deliver the message for. This must be a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z


The response format varies depending on the HTTP status code. If the call was successful (HTTP 202 - Created), a VerifyCode object is returned:

requestId*A globally unique identifier for the verify request. This is used to refer to the request in subsequent calls to validate codes
phoneNumber*The phone number the code was sent to in international format
status*The status of the verification. In this case it can be one of the following:
CodeNotVerified - The code was sent, but has not yet been verified
CodeNotSent - The code was not sent due to the phone number being dead.
numberStatus*The status of the phone number. this can be one of the following
On - The phone is on
Off - the phone is off
Dead - The phone number is dead
NotProvisioned - The phone number is not on a mobile network, e.g. it is a landline
created*The date the request was created. This is a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z

Invalid parameters were supplied

If there is a problem with the parameters passed to the method, a HTTP 400 - Bad Request status is returned and the body of the response is an array of ValidationFailure objects.

ValidationFailure Object

propertyThe property that the validation failure applies to, or empty if the failure applies to the entire submitted payload.
failureCode*A string containing a short machine readable failure code. See Error Codes for more details.
details*A human readable description of the validation failure.

Response Examples

Send a verification code to a phone number

curl -X POST -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "from": "Test",
    "to": "447979080215"
}' ''


  "requestId": "0bd57dc3-580c-4c1d-8aee-2ff79bd8633c",
  "phoneNumber": "447979080215",
  "status": "CodeUnverified",
  "numberStatus": "On",
  "created": "2016-02-23T11:10:14.552Z"

Request with a bad phone number supplied

curl -X POST -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "from": "Test",
    "to": "4479790802150"
}' ''


    "property": "from",
    "failureCode": "ToInvalid",
    "details": "from is not valid. No value was specified."

Request without an authorization header

curl -X POST -H "Content-Type: application/json" -d '{
    "from": "Test",
    "to": "4479790802150"
}' ''


No authorization header supplied or invalid username or password


var body = new[]
      from = "Test",
      to = "447979080215"

var client = new RestClient("");
var request = new RestRequest(Method.POST);
request.Authenticator = new HttpBasicAuthenticator(userName, password);
IRestResponse response = client.Execute(request);
curl -X POST -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "from": "Test",
    "to": "447979080215"
}' ''
HttpResponse<String> response ="")
  .header("content-type", "application/json")
  .header("cache-control", "no-cache")
  .basicAuth(userName, password)
  .body("{\n    \"from\": \"Test\",\n    \"to\": \"447979080215\"\n}\n")
var messages = {
    "from": "Test",
    "to": "447979080215"

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "username": "#USERNAME#",
    "password": "#PASSWORD#",
  "processData": false,
  "data": messages

$.ajax(settings).done(function (response) {

$username = "#USERNAME#";
$password = "#PASSWORD#";

$request = new HttpRequest();

  'cache-control' => 'no-cache',
  'authorization' => 'Basic ' . base64_encode("$username:$password")
  'accept' => 'application/json',
  'content-type' => 'application/json'

    "from": "Test",
    "to": "447979080215",

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;