Create and Send Code

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

POST

https://services-cpaas.dotdigital.com/webapi/verify

Body

Property	Type	Description
`to`*	string	The 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`*	string	A 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
`countryIsoCode`	string	An 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
`body`	string	An 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.
`validUntil`	DateTime	A 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

Response

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

Property	Description
`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

Property	Description
`property`	The 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"
}' 'https://services-cpaas.dotdigital.com/webapi/verify'

Response

{
  "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"
}' 'https://services-cpaas.dotdigital.com/webapi/verify'

Response

[
  {
    "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"
}' 'https://services-cpaas.dotdigital.com/webapi/verify'

Response

No authorization header supplied or invalid username or password

Examples

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

var client = new RestClient("https://services-cpaas.dotdigital.com/webapi/verify");
var request = new RestRequest(Method.POST);
request.Authenticator = new HttpBasicAuthenticator(userName, password);
request.AddJsonBody(body);
IRestResponse response = client.Execute(request);

curl -X POST -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "from": "Test",
    "to": "447979080215"
}' 'https://services.comapi.com/webapi/verify'

HttpResponse<String> response = Unirest.post("https://services.comapi.com/webapi/verify")
  .header("content-type", "application/json")
  .header("cache-control", "no-cache")
  .basicAuth(userName, password)
  .body("{\n    \"from\": \"Test\",\n    \"to\": \"447979080215\"\n}\n")
  .asString();

var messages = {
    "from": "Test",
    "to": "447979080215"
}];

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://services.comapi.com/webapi/verify",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "username": "#USERNAME#",
    "password": "#PASSWORD#",
  },
  "processData": false,
  "data": messages
}

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

<?php

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

$request = new HttpRequest();
$request->setUrl('https://services.comapi.com/webapi/verify/sendcode');
$request->setMethod(HTTP_METH_POST);

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

$request->setBody('{
    "from": "Test",
    "to": "447979080215",
}');

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

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