Skip to content
On this page

W2 Data IDV Check 013

About the service

W2_DATA_IDVCHECK_013 is an identity verification service that uses physical documentation to verify an individual.

Product Code: W2-DATA-IDVCHECK-013

Does this service leave a credit search Footprint? No

Document Upload

Use of this service is a two-part process, in that before making a call to a bundle containing this service, any documents that are required must already be uploaded to our systems by using the DocumentUpload endpoint.

Details on this service method can be found in the "UploadDocument" section of this page.

Callback Preference

This service can take up to 24 hours but usually less than 2 hours to give a final response. This is because it involves a manual human intelligence task.

Because of this, details of how this response should be communicated need to be agreed with W2 during the onboarding process. The current options are:

  • Email
  • HTTP POST request to a specified endpoint (Formatted in XML or Json)

This preference must be agreed with W2 during the on-boarding process in order to use the service.

Request

Query Data

The following query data properties pertain to this service.

Property NameTypeOptional/MandatoryNotes
ForenameStringMandatory
SurnameStringMandatory
HouseNameStringMandatory if no HouseNumber given
HouseNumberStringMandatory if no HouseName given
PostcodeStringMandatory
DayOfBirthIntMandatory
MonthOfBirthIntMandatory
YearOfBirthIntMandatory(yyyy)
CountryIsoCountriesEnumMandatoryCannot be "None"
GenderStringOptionalMust be "M" or "F" if supplied
PhoneNumberStringOptional
MobileNumberStringOptional
FlatStringOptional
StreetStringOptional
CityStringOptional
CountyStringOptional

In addition, an image of the formal identification document must be sent using the UploadFile object, which sits alongside QueryData as part of the ServiceRequest object. It needs to contain the following fields:

Property NameTypeOptional/MandatoryNotes
UploadedFilesUploadedFile[]Mandatory

The UploadedFile object(s) needs to contain the following:

Property NameTypeOptional/MandatoryNotes
DocumentUIDGUIDMandatoryID of document
ServiceServiceEnumMandatoryThis must be set to W2_DATA_IDVCHECK_013

Query Options

The QueryOptions element is optional and is used for optional configuration options. This service uses two possible query options.

NamePossible ValuesDescription
DocumentCategoryID
Address
Both
ID indicates that the document is used for proof of identity (for example a passport) and the service will attempt to verify as such. Address indicates that this is used for proof of address (for example a utility bill) and will attempt to verify as such. If this field is left out then we will assume both.
VerificationActionID
POA
Either
Both
This value indicates the type of check that desired. ID indicates that a proof of identity check is required. POA indicates a proof of address check is required. Either indicates that verification of one or the other is required. Both indicates that both checks are required. This can be used when the type of document is unknown. If this is specified, any value in DocumentCategory will be ignored.

If 'ID', 'Either' or 'POA' are selected within the VerificationAction field then service is only billed once. 'Both' will bill twice as both documents have been verified uniquely.

If this field is left out then we will assume both.

ID documents are Passports, National ID cards, Driving license, Residence Permits. Any other document is not a proof of Identity.

Proof of Address is usually utilities or phone bills or  tax statements. Other kinds of bills may also be accepted.

Example request

json
{    
    "Data": {
        "Country": "GBR",
        "DayOfBirth": 1,
        "Forename": "Johnny",
        "HouseNumber": "44",
        "MonthOfBirth": 1,
        "Postcode": "CF36 5DJ",
        "Surname": "Testy",
        "YearOfBirth": 1990
    },
    "Files": [
        {
            "DocumentReference": "Test Image",
            "Id": "0FF8F8BA-F0BB-4B53-86D6-7185D9019269",
            "Service": "W2_DATA_IDVCHECK_013"
        }
    ]
}

Response

Immediate Response

The service will then immediately send back a W2_DATA_IDVCHECK_013 result, which is part of the ServiceResult object of the response.

Immediate response breakdown

The W2_DATA_IDVCHECK_013 result contains the following fields:

Property NameTypePossible Outcomes
CallIdStringThis will be a unique ID representing this request. This value is what will link this call to the final decision.
ErrorCodeString"0000" if no errors were encountered. Otherwise it will be an error code.
ErrorDescString"Successful" if the application was successfully submitted. Otherwise it will be a description of the error encountered.

More information on this object can be found in the class documentation here.

A corresponding ServiceTransaction is also sent with the following fields:

Property NameTypePossible Outcomes
ServiceServiceEnumAlways "W2_DATA_IDVCHECK_013"
ServiceInterpretResultServiceTransactionResultCategoryEnumAlways "NotApplicable"
ServiceTransactionResultServiceTransactionResultEnum"Success" if the application was successfully submitted. Otherwise it will be an error label, details on which can be found in Service Transaction Result Message
ServiceTransactionResultMessageString"Application successfully sent" if the application was successfully submitted. Otherwise it will be details of what went wrong
ServiceValidationDetailsServiceValidationResultDetailsNULL if QueryData passed validation, otherwise will be a collection of errors explaining why the QueryData is not valid
ValidationResultValidationResultEnum"Pass" if all validations conditions are met. Otherwise will be details on what needs to be changed in order to pass validation.

More information on this object can be found in the class documentation here. Note that this is a receipt for the request and not the final result. The final result is sent as a second response.

Example Immediate response

json
{
	"results": {
		"w2DataIdvcheck013Result": {
			"callId": "WSCR1C2B4A33C78D4355B93391F9C56BEDAV",
			"errorCode": "0000",
			"errorDesc": "Successful"
		}
	},
	"transaction": {
		"interpretResult": "Pass",
		"serviceCallReference": "37d86697-3cb3-4e1b-a14b-7723bc14768f",
		"serviceTransactions": [{
				"haltTriggered": false,
				"service": "W2_DATA_IDVCHECK_013",
				"serviceInterpretResult": "NotApplicable",
				"serviceTransactionResult": "Success",
				"serviceTransactionResultMessage": "Application Submitted Successfully.",
				"validationResult": "Pass"
			}
		]
	}
}

Final Response

Approximately 30 minutes after the initial request (this time will vary as it involves a manual human intelligence task), W2 will send a second response to the initial query, containing the final result. This result will be sent either by email or HTTP POST as request. The recipient email address / URL endpoint will have been agreed upon during the on-boarding process.

Email Response
If email was requested, an email will be sent out containing the Call ID of the initial request and the "Pass" or "Fail" result. It will look something like this:

Result Email
Subject: W2_DATA_IDVCHECK_013 Result
Dear [Company Name],
This is the final result of a call to W2_DATA_IDVCHECK_013 that you made at [Date Of Request],
Please see the result below.
CallID: [Call ID returned by first response]
Result: ["PASS" or "FAIL"]
Kind regards
W2 Global Data

POST Response

If a POST response was requested, a HTTP post request will be sent out containing a populated TransactionInformation object serialized into XML or Json.

The TransactionInformation object will be identical in structure to the one returned in the immediate response except that it also contains your ClientReference. However it will only contain a single ServiceTransaction which will be the final result of the W2_DATA_IDVCHECK_013 call.

This ServiceTransaction will have the following fields:

Property NameTypePossible Outcomes
ServiceServiceEnumAlways "W2_DATA_IDVCHECK_013"
Service Interpret ResultServiceTransactionResultCategoryEnum"Pass" or "Fail". This is the final result.
Service Transaction ResultServiceTransactionResultEnumAlways "Success"
Service Transaction Result MessageStringThis will be the Call ID value of the initial service response and, if the result was not a Pass, followed by the reason why after a semicolon, ie: "WSCRB0C3B15DA015454DBF94BD9C8BF660DA; ID expired"
Service Validation DetailsServiceValidationResultDetailsAlways NULL
Validation ResultValidationResultEnumAlways "NotApplicable"

The end result is that the resulting HTTP POST request will look something like this:

Result POST request
POST [Callback URL] HTTP/1.1
Content-Type: application/xml or application/json
Authorization: Basic [Network credential built from company name and API key - see note 1]
Host: [Callback URL host]
Content-Length: [Length of message]
Expect: 100-continue
[XML of TransactionInformation object]

Example TransactionInformation

xml
<TransactionInformation 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ServiceTransactions>
    <ServiceTransactionInformation>
      <Service>W2_DATA_IDVCHECK_013</Service>
      <ServiceTransactionResult>Success</ServiceTransactionResult>
      <ServiceTransactionResultMessage>
        WSCR1C2B4A33C78D4355B93391F9C56BEDAV
      </ServiceTransactionResultMessage>
      <ValidationResult>NotApplicable</ValidationResult>
      <HaltTriggered>false</HaltTriggered>
      <ServiceInterpretResult>Pass</ServiceInterpretResult>
      <ServiceHasFailedOver>false</ServiceHasFailedOver>
    </ServiceTransactionInformation>
  </ServiceTransactions>
  <ServiceCallReference>c391453f-4546-4306-a274-5520addc812f</ServiceCallReference>
  <InterpretResult>Not Applicable</InterpretResult>
  <ClientReference>123</ClientReference>
</TransactionInformation>
json
{
	"ServiceTransactions": [
		{
			"Service": "W2_DATA_IDVCHECK_013",
			"ServiceTransactionResult": "Success",
			"ServiceTransactionResultMessage": "64f7be75-299b-4ee0-a1be-fdb776acc2d1",
			"ValidationResult": "NotApplicable",
			"HaltTriggered": false,
			"ServiceInterpretResult": "Pass",
			"ServiceHasFailedOver": false
		}
	],
	"ServiceCallReference": "57f27731-902c-44b8-b28c-0a5382f7484d",
	"InterpretResult": "NotApplicable",
	"ClientReference": "123"
}

Note 1: An authorization header is added to give customers the option to authenticate the request before accepting it. The credential is a network credential made up from the following:

  • Username: Name of company as it appears in Portal
  • Password: Company API key

The resulting value is constructed as follows (as described here):

  1. Username and password are combined into a string "username:password".
  2. The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line.

This will create something like:

Example Authorization Header
Basic VzI6cGl6emE=

Allowing the endpoint server to deny the request based on this credential if that is preferred.

"Refer" Result

Sometimes the result may not be a pass or a fail, but a "Refer".

A "Refer" result happens when there is something about the document that is preventing a final decision from being made. The most common cause of this is that the ID is expired or illegible.

If the result has been received via email, the reason is outlined below the result. Here is an example of what the email might look like:

Example of "Refer" Result Email
Subject: W2_DATA_IDVCHECK_013 Result
Dear Globex Corporation,
Further action required, please see below.
This is the final result of a call to W2_DATA_IDVCHECK_013 that you made on 15 January 2016 11:59:30,
Please see the result below.
CallID: WSCRB0C3B15DA015454DBF94BD9C8BF660DA
Result: Refer
Details: ID expired
This means that the submitted document is not adequate for a final decision to be made. A correct document will need to be submitted in order to get a final Pass / Fail decision.
This will require a slightly altered submission to W2_DATA_IDVCHECK_013 that contains the new document and references CallID: WSCRB0C3B15DA015454DBF94BD9C8BF660DA. To find out how to do this, please see the "Refer Result" section on this page: http://developer.w2globaldata.com/Documentation/W2DataIdvcheck013Service/#ReferResult
For further details on this result, please login to https://portal.idvcheck.com using the details given during on-boarding.
Kind regards
W2 Global Data

If the result has been received via postback, the reason is given next to the unique ID in the ServiceTransactionResultMessage field of the ServiceTransactionInform object. It is separated from the ID with a semi-colon. Here is an example of what the post request might look like:

Example of "Refer" Result Post

xml
<TransactionInformation 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:xsd=" http://www.w3.org/2001/XMLSchema">
  <ServiceTransactions>
    <ServiceTransactionInformation>
      <Service>W2_DATA_IDVCHECK_013</Service>
      <ServiceTransactionResult>Success</ServiceTransactionResult>
      <ServiceTransactionResultMessage>
        WSCRB0C3B15DA015454DBF94BD9C8BF660DA;ID expired
      </ServiceTransactionResultMessage>
      <ValidationResult>NotApplicable</ValidationResult>
      <HaltTriggered>false</HaltTriggered>
      <ServiceInterpretResult>Inconclusive</ServiceInterpretResult>
      <ServiceHasFailedOver>false</ServiceHasFailedOver>
    </ServiceTransactionInformation>
  </ServiceTransactions>
  <InterpretResult>NotApplicable</InterpretResult>
</TransactionInformation>
json
	"transaction": {
		"interpretResult": "NotApplicable",
		"serviceCallReference": "37d86697-3cb3-4e1b-a14b-7723bc14768f",
		"serviceTransactions": [{
				"haltTriggered": false,
				"service": "W2_DATA_IDVCHECK_013",
				"serviceInterpretResult": "Inconclusive",
				"serviceTransactionResult": "Success",
				"serviceTransactionResultMessage": "WSCRB0C3B15DA015454DBF94BD9C8BF660DA;ID expired",
				"validationResult": "NotApplicable"
			}
		]
	}
Example of "Refer" Result Post
POST https://www.globexcorporation.com/services/callbackservice.svc HTTP/1.1
Content-Type: application/xml
Authorization: Basic VzI6cGl6emE=
Host: www.globexcorporation.com
Content-Length: 869
Expect: 100-continue

What To Do In The Event of a "Refer" Result

To complete the verification, a replacement / corrected document will need to be uploaded that satisfies the requirements needed for a final decision to be made.

To do this, follow these steps:

  1. Upload a replacement / corrected document to W2 systems using the UploadDocument API method.

  2. Make a new call to W2_DATA_IDVCHECK_013 with the DocumentUID of the newly uploaded document inserted into UploadedFiles array and add a query option with the key uniqueid and the value as the unique ID of the original call. Query data is not necessary for this request.

This will re-open the process for this document, and the new result will come through via email / postback in the same way as the original result. If the new result is also a "refer", this process can be repeated until the document is verified.

Could I Send A New Application With The Corrected Document Instead Of Doing The Above?

It is not recommended to send a new application in the event of a refer, as this will incur a second charge. Using the method described above will not incur any further charges and is the recommended course of action in the event of a refer result.

10. Sandbox

Example Request

To use sandbox the following example request can be used.

Remember to include the W2 provided API key in the Authorization Header.

json
{
    "Bundle": "W2_DATA_IDVCHECK_013",
    "Data": {
        "Forename": "Louie",
        "Surname": "Ellis",
        "HouseNameNumber": "92",
        "DayOfBirth": 19,
        "MonthOfBirth": 2,
        "YearOfBirth": 1944,
        "Country": "GBR",
        "Postcode": "PE12 0WS"
    },
    "Options": {
        "Sandbox": "true"
    },
    "ClientReference": "your-client-reference"
}

Sandbox Cases

PASS Test Case

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a PASS:

FieldValue
ForenameLouie
SurnameEllis
HouseNameNumber92
PostcodePE12 0WS
DayOfBirth19
MonthOfBirth2
YearOfBirth1944
CountryGBR

FAIL Test Case

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a FAIL:

FieldValue
ForenameRiley
SurnameDavies
HouseNameNumber4
PostcodeGU4 4UF
DayOfBirth27
MonthOfBirth2
YearOfBirth1974
CountryGBR

REFER Test Case "ID EXPIRED"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "ID EXPIRED":

FieldValue
ForenameMegan
SurnameBrookes
HouseNameNumber98
PostcodeRG19 9DW
DayOfBirth9
MonthOfBirth8
YearOfBirth1979
CountryGBR

For more details on what a "Refer" result means, please see here

REFER Test Case "ID ok, POA illegible"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "ID ok, POA illegible":

FieldValue
ForenameOlivia
SurnameWheeler
HouseNameNumber82
PostcodePO38 4UU
DayOfBirth4
MonthOfBirth2
YearOfBirth1940
CountryGBR

REFER Test Case "POA ok, ID invalid"

If the following details are set, the application will successfully submit, and when the final result comes through via POST / email it will be a REFER due to "POA ok, ID invalid":

FieldValue
ForenameJayden
SurnameEdwards
HouseNameNumber42
PostcodePL12 8XY
DayOfBirth1
MonthOfBirth5
YearOfBirth1982
CountryGBR

Finalising a REFER result

In a real world situation you would want to upload a second document in response to a "Refer" result as described in the link above.

This can also be done in sandbox mode for this call. Simply make a request without any query data, and a query option value of uniqueid set to value "WSCRA055F2C9FC32415FB4D189488108F4EB" (still with the sandbox query option set).

The ServiceTransactionInformation object will return the same as above, with the following difference:

xml
<ServiceTransactionResultMessage> Successfully Re-submitted Application. 
                                  (This call was generated using sandbox mode) </ServiceTransactionResultMessage>

IDV Response Codes

Reason CodeDescription
Approve/FixAn easy fix is required to approve the application, for example a typo, or incorrect DOB.
ExpiredApplication has been marked as expired, due to duplicate application or inactivity.
FraudThe ID document has been identified as fraudulent.
ID and POA DiscrepancyThe ID document and the proof of address document are not showing the same information.
ID and POA IllegibleID and POA documents are of poor quality or cannot be read. Screenshots, photocopies or black & white images are not acceptable.
ID and POA IncorrectID and POA documents are non-compliant or do not match registration detail.
ID ExpiredID document has expired.
ID Expired, POA OKThe proof of address document is approved but the ID document has expired.
ID IllegibleID document is of poor quality or cannot be read. Screenshots, photocopies or black & white images are not acceptable.
ID Illegible, POA OKThe proof of address document is approved but the ID document is not legible enough for a final decision to be made.
ID IncorrectID document is not in the applicant’s name.
ID Incorrect DetailsThe ID document is showing information known to be incorrect.
ID Incorrect, POA Non-compliantThe ID document is not a recognised valid form of ID and the proof of address is non-compliant.
ID Non-compliantID document is non-compliant - voter and tax cards are not acceptable, for example
ID Non-compliant, POA OKThe proof of address is approved but the ID document is non-compliant
ID OK, POA IllegibleThe ID document is approved but the proof of address is not legible enough for a final decision to be made.
ID OK, POA Non-compliantThe ID document is approved but the proof of address is non-compliant.
ID OK, POA Out of DateThe ID document is approved but the proof of address is out of date.
ID, POA InvalidBoth the ID document and the proof of address are invalid.
Missing dom photo page or POA stampSub-reason code for Russia, Ukrainian and Belarus applications.
Missing back of IDPOI document is missing image of the back of ID document.
No MatchNo record of the individual can be found.
POA IllegiblePOA document is of poor quality or cannot be read. Screenshots, photocopies or black & white images are not acceptable.
POA IncorrectPOA document is not in the applicant’s name or there is an address mismatch.
POA Incorrect DetailsThe proof of address contains information known to be incorrect.
POA Internet CopyPOA document is either a screenshot or printed out electronic document. Please request original PDF document or photo of original document.
POA Non-compliantPOA document is non-compliant - mobile bills and insurance documents are not acceptable, for example.
POA OK, ID InvalidThe proof of address is approved but the ID document is not recognised as a valid ID document.
POA Out of DatePOA document is outside of the acceptable date range.
POA Out of Date rangeThe proof of address is out of the specified date range.
POA Wrong FormatPOA document file has been converted/altered, please ask the customer for the original file.
Suspicious DocsPOI and/or POA are high risk.
ReferApplication referred for further clarification or additional documents.