Validate Code

The Validate method allows you to check the validity of a verification code entered by a user and that was generated by the Verify method.

Note that the requestId generated when sending a code is single use only and is discarded when one of the following conditions is met:

• the code is validated correctly.
• the maximum number of 5 incorrect validation attempts is exceeded.
• the code expires.

Subsequent attempts to verify a requestId will act as if the requestId does not exist and a 204 No Content status will be returned.

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    string
  </td>

  <td>
    The verify request id returned from [Verify](ref:rest-verify-create)
  </td>
</tr>

Body

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    string
  </td>

  <td>
    A string containing the verification code to check
  </td>
</tr>

Response

The response format varies depending on the HTTP status code.

RequestId was recognised

An HTTP 200 OK is returned with the body of the response containing a VerifyCode object which contains a status property that describes whether the code validated successfully, and if not, the reason why.

  <th>
    Description
  </th>
</tr>

  <td>
    A globally unique identifier for the verify request. This is used to refer to the request in calls
  </td>
</tr>

<tr>
  <td>
    <code>phoneNumber</code><span class="required">\*</span>
  </td>

  <td>
    The phone number the code was sent to in international format
  </td>
</tr>

<tr>
  <td>
    <code>status</code><span class="required">\*</span>
  </td>

  <td>
    The status of the code. This can be one of the following:

    * CodeVerified - The code was correct
    * CodeNotVerified - The code was not correct
    * CodeLocked - The code has been locked due to too many unsuccessful attempts to validate.
    * CodeExpired - The code has expired
  </td>
</tr>

<tr>
  <td>
    <code>numberStatus</code><span class="required">\*</span>
  </td>

  <td>
    The status of the phone number at the time the code was sent to it.
  </td>
</tr>

<tr>
  <td>
    <code>created</code><span class="required">\*</span>
  </td>

  <td>
    The date the code was sent to the phone. This is a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z
  </td>
</tr>

<tr>
  <td>
    <code>verified</code>
  </td>

  <td>
    The date the code was verified. This is a UTC time in ISO 8601 format, e.g. 2015-10-21T13:28:06.419Z
  </td>
</tr>

RequestId was not recognised

An HTTP status of 204 No Content is returned

Invalid parameters were supplied

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

ValidationFailure Object

  <th>
    Description
  </th>
</tr>

  <td>
    The property that the validation failure applies to, or empty if the failure applies to the entire submitted payload.
  </td>
</tr>

<tr>
  <td>
    <code>failureCode</code><span class="required">\*</span>
  </td>

  <td>
    A string containing a short machine readable failure code. See [Error Codes](ref:rest-verify-error-codes) for more details.
  </td>
</tr>

<tr>
  <td>
    <code>details</code><span class="required">\*</span>
  </td>

  <td>
    A human readable description of the validation failure.
  </td>
</tr>

Response Examples

Validate a matching code

curl -X GET -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "code": "12345"
}' 'https://services-cpaas.dotdigital.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate'

Response - Code was verified

{
  "status": "CodeVerified"
}

Response - Code was not recognised

{
  "status": "CodeNotVerified"
}

Response - Request Id not recognised

No code supplied

curl -X GET -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "code": ""
}' 'https://services-cpaas.dotdigital.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate'

Response

[
  {
    "property": "verifyCode",
    "failureCode": "CodeEmpty",
    "details": "verifyCode cannot be null or empty"
  }
]

Request without an authorization header

curl -X GET -H "Content-Type: application/json" -d '{
    "code": "12345"
}' 'https://services-cpaas.dotdigital.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate'

Response

No authorization header supplied or invalid username or password

Language Examples

Guid requestId = new Guid("0D5C94D4-DF1F-4FC8-82D2-1F64EA548704");
var body = new
{
  code = "12345"
};

// Use RestSharp to call API
var client = new RestClient(string.Format("https://services-cpaas.dotdigital.com/webapi/verify/{0}/validate", requestId);
client.Authenticator = new HttpBasicAuthenticator(userName, password);

var request = new RestRequest();
request.AddJsonBody(body);
IRestResponse response = client.Post(request);

curl -X GET -H "Content-Type: application/json" -user #USER#:#PASSWORD# 
}' 'https://services.comapi.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate'

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

HttpResponse<String> response = Unirest.get("https://services.comapi.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate")
  .header("content-type", "application/json")
  .basicAuth(username, password)
  .asString();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://services.comapi.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate",
  "method": "GET",
  "headers": {
    "content-type": "application/json",
    "username": "#USERNAME#",
    "password": "#PASSWORD#",
  },
  "processData": false
}

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

<?php

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

$request = new HttpRequest();
$request->setUrl('https://services.comapi.com/webapi/verify/55569B50-785F-4865-9769-ED1E21CF6A88/validate');
$request->setMethod(HTTP_METH_GET);

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

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

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