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.

PUT
  **https://services.comapi.com/WebApi/Verify/*{requestId}*/validate**

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

PropertyTypeDescription
requestId*stringThe verify request id returned from Verify.

Body

PropertyTypeDescription
code*stringA string containing the verification code to check.

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.

PropertyDescription
requestId*A globally unique identifier for the verify request. This is used to refer to the request in calls.
phoneNumber*The phone number the code was sent to, in international format.
status*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.
numberStatus*The status of the phone number at the time the code was sent to it.
created*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.
verifiedThe date the code was verified. This is a UTC time in ISO 8601 format, for example, 2015-10-21T13:28:06.419Z.

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

PropertyDescription
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.
Learn more in Error Codes.
details*A human-readable description of the validation failure.

Response examples

Validate a matching code

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;
}