Enterprise Communications APIGet StartedReference
Reference
Select ProductPortal
Start typing to search…

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.

<div class="alert alert-success">
  <div class="label label-success">PUT</div> &nbsp; <strong>https://<span></span>services.comapi.com/WebApi/Verify/<em>{requestId}</em>/validate</strong>
</div>

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 five incorrect validation attempts is exceeded.
  • the code expires.

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

***

# Parameters

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>
      <th>
        Type
      </th>
      <th>
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>requestId</code><span class="required">*</span>
      </td>
      <td>
        string
      </td>
      <td>
        The verify request id returned from [Verify](ref:rest-verify-create).
      </td>
    </tr>
  </tbody>
</Table>

***

# Body

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>
      <th>
        Type
      </th>
      <th>
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>code</code><span class="required">*</span>
      </td>
      <td>
        string
      </td>
      <td>
        A string containing the verification code to check.
      </td>
    </tr>
  </tbody>
</Table>

***

# 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. This property describes whether the code validated successfully, and if not, the reason why.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>
      <th>
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>requestId</code><span class="required">*</span>
      </td>
      <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, for example, 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, for example, 2015-10-21T13:28:06.419Z.
      </td>
    </tr>
  </tbody>
</Table>

## 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

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>
      <th>
        Description
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>property</code>
      </td>
      <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.  
        *Learn more in [Error Codes](https://docs.cpaas.dotdigital.com/reference/rest-verify-error-codes).*
      </td>
    </tr>
    <tr>
      <td>
        <code>details</code><span class="required">*</span>
      </td>
      <td>
        A human-readable description of the validation failure.
      </td>
    </tr>
  </tbody>
</Table>

***

# Response examples

## Validate a matching code

```curl
curl -X GET -H "Content-Type: application/json" -user #USER#:#PASSWORD# -d '{
    "code": "12345"
}' 'https://services.comapi.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.comapi.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.comapi.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.comapi.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;
}