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.

POST
  https://services.comapi.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.comapi.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.comapi.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.comapi.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.comapi.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;
}