Veridial Logo

REST API & Technical Documentation

Version 3.2 (27th July 2015)

Introduction

This document acts as a guide for software developers to describe how they may integrate the VerIDial two-factor authentication system into their applications and web based systems to provide a second layer of security.

Typical authentication mechanisms work by using a password (“something you know”) alongside a username. This is called single-factor authentication. Two-factor authentication adds to this by using either "something you own" or "something you are", whilst three-factor puts everything together. “Something you own” is usually a token or physical object in your possession whilst “something you are” is typically represented by finger print recognition or retina scanning.

The VerIDial system works by using a phone linked to the person being authenticated. This provides the "something you own" in the typical two-factor authentication scenario. It's also possible to use VerIDial on its own instead of a password, and although this is only single-factor it’s typically more secure due to the weakness of the average password. (Dinei & Cormac, 2007)

When using VerIDial, the person attempting to authenticate is required to enter a PIN number that is read out to them over a landline or mobile telephone, or sent as a text message or push notification to a mobile.

For applications where a lower level of security is required, or where other methods are not possible, the PIN can be sent to an email address.

There are two methods that can be used to integrate VerIDial.

Plugin

The simplest way to get VerIDial two-factor authentication up and running is by using our HTML iframe plugin that can be embedded into any website.

REST API

Rather than using the provided plugin the VerIDial system can be accessed directly over HTTPS via the REST API. This uses basic access authentication and provides methods to set up a call, SMS, push notification and email request, to request the status of an ongoing request, and to verify a PIN.

iframe Plugin

Using the iframe plugin

VerIDial Two Factor Authentication PIN entry
Figure 1 – Example of a page using the plugin

If you wish to use the iframe based plugin with your application, there is a simple sequence of events to follow.

Step 1 – Preconfigure the request

From within your application, use the REST API with your VerIDial credentials to initiate an IVR request to the appropriate API method: voice, SMS, push notification or email.

The request will return a token that you should pass to the plugin. This reference number can be used once only before expiring.

This is also the point at which you are billed for the verification attempt.

Step 2 – Embed the IVR iframe plugin

Within your application, reference the plugin as you would a normal iframe and pass the token from step 1 in addition to your own success and failure page URLs.


<iframe width="300" height="420" seamless="seamless" frameBorder="0" src="https://www.veridial.co.uk/plugin/?token=6884E7C7-690C-41E6-8551-5FFB202BDF75&pinSuccessUrl=http://mywebsite.com/PinSuccess.aspx&pinFailureUrl=http://mywebsite.com/PinFailure.aspx&pinLength=4&backgroundColour=black&foregroundColour=FFFFFF&highlightColour=00FF00">
</iframe>

You may change the colour of the VerIDial plugin by passing a foreground colour (used for text), a highlight colour (used for the PIN textbox) and a background colour. Colour values should be specified in hexadecimal RGB format as if they were embedded inside a style sheet without the hash symbol. e.g. FFBBCC. You can also use some standard named values (black, green, silver, gray, olive, white, yellow, maroon, navy, red, blue, purple, teal, fuchsia or aqua).

You may also instruct the plugin to auto submit after X number of key presses where X corresponds to the number of digits in the PIN you expect.

The iframe will auto update its visible status to the following values in order to provide user feedback. These correspond to a subset of the full status list.

  • Queued for Dialling
  • Dialling
  • Playing Instruction
  • Playing PIN
  • Hung Up
  • Bad PIN
Parameter Name Description Example
token Unique identifier for this request 6884E7C7-690C-41E6-8551-5FFB202BDF75
pinSuccessUrl Absolute URI pointing to success page http://mywebsite.com/PinSuccess.aspx
pinFailureUrl Absolute URI pointing to failure page http://mywebsite.com/PinFailure.aspx
pinLength Length of PIN (digits) 4
backgroundColour The background colour and the colour used for the text on the verify button 3E4F56
foregroundColour The colour used for normal text black
highlightColour The colour used to outline the PIN text box and to provide a background fill for the verify button FFBBCC

Step 3 – Handle success or failure

Success

When the user has successfully verified the PIN number, they will be redirected back to your success page. You should double check the status by using the REST API status command and the token.

Failure

If the verification fails for any reason (e.g. the user cancelled the request or the telephone number was engaged) the plugin will redirect the user to your failure page. You may check the reason for failure by using the REST API status command and the token.

If you wish to try again with a different telephone number or email address you must start from step 1 and you will be billed for each attempt.

REST API

Response format

The REST API supports both JSON and XML responses and will return data as per the format set in the Accept request-header, or if missing, the Content-Type of the request. Use the HTTP request headers “application/json” for JSON and “text/xml” for XML.

Request authentication

The HTTP request header to create each request must contain your API Installation ID and API key. This is done via the basic access authentication standard used by many other services and supported natively by most browsers (for testing and development). A header line should be added to the request as follows:

  1. The Installation ID and API key are combined in a single string separated by a colon "Installation ID: API key".
  2. The string is then base 64 encoded according to the RFC2045-MIME variant without the character limit.
  3. The string is appending to a line containing "Authorization Basic" after the space and added to the request.

Example:


Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

If a request fails authentication for any reason, a HTTP 401 Not Authorized response will be returned containing a WWW-Authenticate HTTP header. This will cause most browsers to request a username and password, useful for development and testing.

Some methods may be accessed by providing the request token, when this is the case, the authentication header is not required and we recommend you avoid adding it.

Errors

Whenever a request fails because incorrect parameters were passed or the request has failed for any reason, a HTTP 400 Bad Request will be returned with details of the error.

Example JSON response:


{
    StatusDescription = 'The number is not recognised as a valid phone number.',
    StatusCode = 1003
}

Dates

To avoid confusion with different date and time formats in use in different countries the VerIDial REST API always returns ISO 8601 compliant dates.

API methods

https://api.veridial.co.uk/app

HTTP Type: POST
Requires Authentication Header: Yes

This method creates a new app based request. The system will bill your account, schedule a push notification for immediate sending and return a globally unique token that can be used in subsequent API calls to retrieve information regarding this request such as the status and to verify an entered PIN.

Request
Field Name Type Mandatory or Optional Notes
Number String Mandatory The telephone number of the device you wish to receive the notification
Response
Field Name Type Notes
Token Guid A Globally unique identifier for this request

https://api.veridial.co.uk/sms

HTTP Type: POST
Requires Authentication Header: Yes

This method creates a new SMS based request. The system will bill your account, schedule an SMS for immediate sending and return a globally unique token that can be used in subsequent API calls to retrieve information regarding this request such as the status and to verify an entered PIN.

Request
Field Name Type Mandatory or Optional Notes
Number String Mandatory The telephone number of the mobile to text message
Response
Field Name Type Notes
Token Guid A Globally unique identifier for this request

https://api.veridial.co.uk/voice

HTTP Type: POST
Requires Authentication Header: Yes

This method creates a new IVR based request. The system will bill your account, prepare a voice dial and return a globally unique token that can be used in subsequent API calls to retrieve information regarding this request such as the status and to verify an entered PIN. The system will start dialling immediately once a successful request is made.

Request
Field Name Type Mandatory or Optional Notes
Number String Mandatory The telephone number of the landline or mobile to contact with the PIN.
Response
Field Name Type Notes
Token Guid A Globally unique identifier for this request

https://api.veridial.co.uk/email

HTTP Type: POST
Requires Authentication Header: Yes

This method creates a new email based request. The system will bill your account, schedule an email for immediate sending and return a globally unique token that can be used in subsequent API calls to retrieve information regarding this request such as the status and to verify an entered PIN.

Request
Field Name Type Mandatory or Optional Notes
EmailAddress String Mandatory The email address of the recipient of the PIN.
Response
Field Name Type Notes
Token Guid A Globally unique identifier for this request

https://api.veridial.co.uk/status

HTTP Type: POST or GET
Requires Authentication Header: No

This method uses the token to return the status of a request.

Request
Field Name Type Mandatory or Optional Notes
Token Guid Mandatory The globally unique identifier for this request
Response
Field Name Type Notes
StatusCode Int32 A code that identifies where in the request process the specified request currently is. Codes will vary according to the verification method being used
StatusDescription String A textual description of the current status of this request

https://api.veridial.co.uk/verify

HTTP Type: POST
Requires Authentication Header: No

This method uses the token to verify a PIN number.

Request
Field Name Type Mandatory or Optional Notes
Token Guid Mandatory The globally unique identifier for this request
Pin String Mandatory The PIN number that you wish to compare to the PIN sent to the user
Response
Field Name Type Notes
StatusCode Int32 A code that identifies where in the request process the specified request currently is. Codes will vary according to the verification method being used
StatusDescription String A textual description of the current status of this request

https://api.veridial.co.uk/cancel

HTTP Type: POST
Requires Authentication Header: No

This method uses the token to cancel a pending request. This does not stop the recipient from receiving the message or notification that has already been sent, but will terminate any ongoing call as well as prevent any future verification attempts.

Request
Field Name Type Mandatory or Optional Notes
Token String Mandatory The globally unique identifier for this request
Response
Field Name Type Notes
StatusCode Int32 A code that identifies where in the request process the specified request currently is. The code should state that the request has been cancelled
StatusDescription String A textual description of the current status of this request

https://api.veridial.co.uk/balance

HTTP Type: GET
Requires Authentication Header: Yes

This method returns your current balance of credit.

Response
Field Name Type Notes
Balance Int32 The remaining balance of credit in the account specified by the Installation ID passed in the basic access authentication header

https://api.veridial.co.uk/report

HTTP Type: GET
Requires Authentication Header: Yes

This method returns a summary of your requests as a list. If the optional parameters to filter by date are not present, the system will automatically send the last 20 requests. There is a restriction on the number of records returned; the system will not return more than 1000 requests in a single response.

Request
Field Name Type Mandatory or Optional Notes
StartDate DateTime Optional A start date to filter from
EndDate DateTime Optional An end date to filter to
Response
Field Name Type Notes
RequestDate DateTime A code that identifies where in the request process the specified request currently is. The code should state that the request has been cancelled
Number String The number authenticated
StatusCode Int32 A code that identifies where in the request process the specified request currently is. The code should state that the request has been cancelled
StatusDescription String A textual description of the current status of this request
Method String Voice, SMS or App
Fee Int32 The fee for this request

Status & Error Codes

Status Code IVR, Email, App or SMS Label Description
HTTP 401 ALL Bad Credentials Your Installation ID and/or API key are incorrect
HTTP 400 ALL Bad Request The request contained a bad parameter. Details of the error will be contained within the payload
1001 ALL Unknown Unknown error, contact VerIDial Support in the unlikely event you receive this error code
1002 ALL Bad Token The token supplied is invalid or not recognised
1003 ALL Bad Number The number is not recognised as a valid phone number
1004 ALL Insufficient Credit The installation has insufficient credit to service the request, please contact VerIDial Support to top up
1005 ALL Request Rejected The request has been rejected. The correct PIN was not entered and no further attempts remain
1006 ALL Request Verified The request has been successfully verified
1007 ALL Request Cancelled The request has been cancelled
1008 ALL Request Expired The request has expired due to the length of time taken to respond
1009 ALL Triggered Rate Limiter There have been too many attempts to this number or email. Please wait and try again later
1011 ALL Bad PIN Indicates an incorrect PIN has been entered, however more attempts are permitted
2001 Voice Call Setup A voice request has been created
2002 Voice Call Declined The person answering the call rejected the request
2003 Voice Queued for Dial The request is queued ready for dialing
2004 Voice Call Failed The call could not be connected
2005 Voice Dialling The system is now dialling
2006 Voice Line Engaged The line was engaged when dialling
2007 Voice No Answer The call was successfully placed, but not answered
2008 Voice Playing Instructions The instructions are now being read out
2009 Voice Playing PIN The PIN number is now being read out
2010 Voice Caller Hung-up The call terminated successfully
3001 SMS SMS Sent A text message containing a valid PIN has been sent to the recipient’s network provider
3002 SMS SMS Failed It has not been possible to send a text message to the device at this time
3003 SMS Not a Mobile The number requested is not a mobile number
4001 App Notification Sent A notification containing a valid PIN has been sent to the recipient’s device
4002 App Notification Failed It has not been possible to send a notification to the device at this time
4003 App Not Registered The number requested has no matching handset registered within the system
5001 Email Email Sent An email containing a valid PIN has been sent
5002 Email Email Failed It has not been possible to send an email to the recipient at this time
5003 Email Bad Email The email address is invalid

Print this page