The rest idvCheck api allows a client to submit details for screening checks, electronic kyc, electronic document verification and manual kyc using one api call.

The api is available on the following endpoints:

Table of Contents

  1. Token
  2. New Application
  3. Adding files to an application
  4. Amending Application
  5. Receiving the results of the verification process
  6. Requesting reposting of a result
  7. Pending Status
  8. Screening Checks
  9. Test Cases

Security

idvCheck uses JSON Web Tokens (JWT). JWT is an open, industry standard (RFC 7519) method for representing claims securely between two parties. A token needs to be generated and passed with every api call. A token is valid for 7 days

Apis

Token

This API returns a token which needs to be passed in header for other api calls

Post /api/Token

Example - Curl

  curl -X POST \
  https://stagingapi.idv.technology/rest/api/Token \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
"username": "UsernameSuppliedByIDV", "password": "PasswordSuppliedByIDV"
}'
            

Sample Data Returned

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImNsaWVudGVfYXBpdXNlciIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdXNlcmRhdGEiOiI4fDF8MnwzfDQiLCJuYmYiOjE1MjUxMjUzMDIsImV4cCI6MTUyNTczMDEwMiwiaWF0IjoxNTI1MTI1MzAyLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjUwMTkxIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDE5MSJ9.-I-VUGlGlX_nrRFTVTHPZJwj6Rez2MjJoQfBG8LJWog"

NewApp

This API is used to submit application details to idv for sanction checking, electronic kyc and/or manual kyc

Post /api/NewApp

Example - Curl

 curl -X POST \
  https://newapi.idv.technology/api/NewApp \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImNsaWVudGVfYXBpdXNlciIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdXNlcmRhdGEiOiI4fDF8MnwzfDQiLCJuYmYiOjE1MjYxNzA5NjksImV4cCI6MTUyNjc3NTc2OSwiaWF0IjoxNTI2MTcwOTY5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjUwMTkxIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDE5MSJ9.lGH9b878-uAoGnpMFpyZYohFLfYs4AVj-8h8qGn_BK0' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{ "messageid":"Test01150418",
  "title": "Mr",
  "name": "Peter",
  "surname": "Bloggs",
  "dob": "12 Aug 1956",
  "gender": "M",
  "countryoforigion": "France",
  "uniqueid": "ID01150418",
  "phone": [
    "01321233123",
    "12341234123"
  ],
  "mobile": [
    "01321233123",
    "12341234123"
  ],
  "email": [
    "[email protected]",
    "[email protected]"
  ],
  "udf": null,
  "addresslist": [
    {
      "addresstype":"Main Address",
      "line1": "199",
      "line2": "Main Street",
      "city": "London",
      "postcode": "WSD231",
      "county": "",
      "country": "United Kingdom",
      "countrycode": "UK"
    }
  ]
}
'
            

Field Format

Field Optional/Mandatory Occurance Data Type and Length Description
messageid Mandatory Single Valued String (36) Identifies the message. Must be unique per call.
mode Optional Single Valued Number 1|2|3|4|5 Mode
Title Optional Single Valued String (5) Salutation
Name Mandatory Single Valued String (50) Name
Surname Mandatory Single Valued String (50) Surname
Dob Optional Single Valued String dd MMM yyyy Date of Birth
Gender Optional Single Valued String (1) Gender
countryoforigion Optional Single Valued String (100) Country of Origion
uniqueid Mandatory Single Valued String (36) Identifies the application. Must be unique.
phone Optional Multi Valued String (20) One or more phone numbers for applicant
mobile Optional Multi Valued String (20) One or more mobile phone numbers for applicant
email Optional Multi Valued String (200) One or more email addresses for applicant
udf Optional Multi Valued String (100) One or more User Defined Fields for applicant
addresslist Mandatory Multi Valued Address One or more Address

Address Field Format

Field Optional/Mandatory Occurance Data Type and Length Description
Addresstype Optional Single Valued String (10) Type of Address
Line1 Mandatory Single Valued String (100) Address Line 1
Line2 Optional Single Valued String (100) Address Line 2
City Mandatory Single valued String (50) City
PostCode Optional Single valued String (20) Post Code
County Optional Single valued String (50) City
Country Optional Single valued String (50) Country
Countrycode Mandatory Single valued String (2) ISO ALPHA-2 CODE

Mode

You can optionally pass mode to the api. If the mode is not available for the client it will be ignored and the default mode will be applied.

mode Description
1Screening check only
2Screening check, electronic kyc, manual kyc
3Screening check, manual kyc
4Electronic kyc, manual kyc
5Manual kyc

Data Returned

The api can be set up using one of five modes. Depending on the mode in use the api will return a result out of a possible list.

Mode 1 - Screening check only

0020 Screening - No Match
0021 Screening - Requires Investigation

Mode 2 - Screening check, electronic kyc, manual kyc

0018 eKYC Approved
0019 eKYC Pending
0021 Screening - Requires Investigation

Mode 3 - Screening check, manual kyc

0020 Screening - No Match
0021 Screening - Requires Investigation

Mode 4 - Electronic kyc, manual kyc

0018 eKYC Approved
0019 eKYC Pending

Mode 5 - Manual kyc

0000 Successful submission.

For all modes

Any other code returned would signify that an error had occurred during the call of the service. An exhaustive list of codes is found here. Calling the idvcheck api also results in an aysynchrons call (postback) to the client. This call contains more details of the result. Information about this call can be found here.

List of codes returned by api

0000    Successful
0002    Operation Failed
0003    Data Incorrect
0004    Application already exists (value of UniqueId field was used before)
0007    Application does not exists  (Addfile or Updateapplication was submitted with a UniqueId field which was not sent previously)
0011    Application status does not allow to add file
0016    Invalid file extension
0017    Error Connecting to eKYC service
0018    eKYC Approved
0019    eKYC Pending
0020    Screening - No Match
0021    Screening - Requires Investigation
0022    Screening - Potential Match
0023    PEP - Potential Match
0024    Adverse Media - Potential Match
0029    Cannot complete eKyc
0030	Cannot add an encrypted document
0031    Electronic Document Verificiation Pass
0032    Electronic Document Verificiation Fail
0033    Electronic Document Verificiation queued for Manual Review

List of possible entires returned in data field by api

One or more of thes keywords can be returned when errorcode is 0021
sanction
warning
fitness-probity
pep
pep-class-1
pep-class-2
pep-class-3
pep-class-4
adverse-media
adverse-media-financial-crime
adverse-media-violent-crime
adverse-media-sexual-crime
adverse-media-terrorism
adverse-media-fraud
adverse-media-narcotics
adverse-media-general
Contents

AddFile

This API is used to add documents to an existing app created using the api call NewApp. There are two versions of the postfile api.

Post /api/postfile/messageid/uniqueid

curl -X POST \
  https://stagingapi.idv.technology/rest/api/postfile/Test0113050418/ID01140418 \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImNsaWVudGVfYXBpdXNlciIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdXNlcmRhdGEiOiI4fDF8MnwzfDQiLCJuYmYiOjE1MjYxNzA5NjksImV4cCI6MTUyNjc3NTc2OSwiaWF0IjoxNTI2MTcwOTY5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjUwMTkxIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDE5MSJ9.lGH9b878-uAoGnpMFpyZYohFLfYs4AVj-8h8qGn_BK0' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F '=@C:\Temp\file1.pdf' \
  -F '=@C:\Temp\file2.jpg'

Post /api/postfile/messageid/uniqueid/filetype/fileid

curl -X POST \
  https://stagingapi.idv.technology/rest/api/postfile/Test0113050418/ID01140418/bank_statement/32112 \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImNsaWVudGVfYXBpdXNlciIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdXNlcmRhdGEiOiI4fDF8MnwzfDQiLCJuYmYiOjE1MjYxNzA5NjksImV4cCI6MTUyNjc3NTc2OSwiaWF0IjoxNTI2MTcwOTY5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjUwMTkxIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDE5MSJ9.lGH9b878-uAoGnpMFpyZYohFLfYs4AVj-8h8qGn_BK0' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F '=@C:\Temp\file1.pdf' \
  -F '=@C:\Temp\file2.jpg'

Field Format

Field Optional/Mandatory Occurance Data Type and Length Description
messageid Mandatory Single Valued String (36) Identifies the message. Must be unique per call.
uniqueid Mandatory Single Valued String (36) Identifies the application that the files must be attached to. UniqueID must have been used in a NewApp Call .
Mandatory Multi Valued File One or more files that are to be appended to the application.
filetype Optional Single Valued String Type of file
FileId Optional Single Valued String An Id that the client wants to use to identify file.

List of codes returned by api

0000    Successful
0002    Operation Failed
0007    Application does not exists  (Addfilen was submitted with a UniqueId field which was not sent previously)
0011    Application status does not allow to add file
0016    Invalid file extension

Amending an Application

Once an application has been submitted, the following properties can be changed/added using the modiapp api call. Through this api one can change:

Note: uniqueid refers to the uniqueid of the app that needs to be amended.

curl -X PATCH \
  https://stagingapi.idv.technology/rest/api/modapp \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImNsaWVudGVfYXBpdXNlciIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvdXNlcmRhdGEiOiI4fDF8MnwzfDQiLCJuYmYiOjE1MjYxNzA5NjksImV4cCI6MTUyNjc3NTc2OSwiaWF0IjoxNTI2MTcwOTY5LCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjUwMTkxIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MDE5MSJ9.lGH9b878-uAoGnpMFpyZYohFLfYs4AVj-8h8qGn_BK0' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{ "messageid":"Test01150418",
  "title": "Mr",
  "name": "Peter",
  "surname": "Bloggs",
  "dob": "12 Aug 1956",
  "gender": "M",
  "countryoforigion": "France",
  "uniqueid": "ID01150418",
  "phone": [
    "01321233123",
    "12341234123"
  ],
  "mobile": [
    "01321233123",
    "12341234123"
  ],
  "email": [
    "[email protected]",
    "[email protected]"
  ],
  "udf": null,
  "addresslist": [
    {
      "addresstype":"Main Address",
      "line1": "199",
      "line2": "Main Street",
      "city": "London",
      "postcode": "WSD231",
      "county": "",
      "country": "United Kingdom",
      "countrycode": "UK"
    }
  ]
}
'

Receiving the results of the verification process

Once idvcheck processes an application a JSON document is posted to the client at a URL submitted to the project manager at integration stage. The JSON document will contain the data which was used during the verification stage together with the outcome of the verification. The outcome of the verification will be placed in field Decision. Decision can contain one of the following values:

Only some of the above values of Decision might be returned to the client depending on the service on offer.

The client should return an HTTP Response of 200 if the posting was successful or 500 in case of an error. If idvcheck receives a status other than 200 it will retry submission after a short period until a response of 200 is received.

{
   "title":"Mr",
   "name":"Peter",
   "surname":"Bloggs",
   "dob":"8/12/1956 12:00:00 AM",
   "gender":"M",
   "countryoforigion":"France",
   "uniqueid":"ID03230518",
   "phone":[
      "01321233123",
      "12341234123"
   ],
   "mobile":[
      "01321233123",
      "12341234123"
   ],
   "email":[
      "[email protected]",
      "[email protected]"
   ],
   "udf":[
      "ID illegible",
      "ID incorrect"
   ],
   "addresslist": [
    {
      "addresstype":"Main Address",
      "line1": "199",
      "line2": "Main Street",
      "city": "London",
      "postcode": "WSD231",
      "county": "",
      "country": "United Kingdom",
      "countrycode": "UK"
    }
  ],
   "decision":"Pending"
}        

For clients that request a decision for every file evaluated IDV will post the following json document:

{
   "UniqueId":"12221",
   "Fileid":"333",
   "Decision":"Approve",
   "Reason":"Approved"
}
    

Notes:

The list of possible decisions/reasons for files is the following:
DecisionReason
Non-compliant Document type is not listed as acceptable.
Incorrect Details within the document do not match with the application.
Illegible Quality of the document or image is insufficient to complete verification.
OutofDate Either the document has expired or is not dated within a specified time frame, ie no older than 3 months.
Approved Approved.
Fraud Fraud.
Refer We require input from Bitpay/ Passfort Client.
Fix There is a simple typo that needs to be approved before we can approve.

Pending Status

If the status sent back by idv is the Pending status, further information about the application can be obtained by checking the UDF fields. The UDF fields can contain one or more of:

Client can use the PostFile method (see AddFile) to send additional documentation for the application.

Screening Check

When an app hits screening checks after it has been verified, approved, IDV will post back a decision to the webhook. The decision will follow the following format:

{
   "title":"",
   "name":"Wade",
   "surname":"Wilson",
   "dob":"1/14/1980 12:00:00 AM",
   "gender":" ",
   "countryoforigion":"",
   "uniqueid":"6c7db9a7-435b-4c97-ee73-08d67c6d1035",
   "phone":[

   ],
   "mobile":[

   ],
   "email":[

   ],
   "udf":[
      "pep-class-1"
   ],
   "addresslist":[
      {
         "addresstype":null,
         "line1":"1 Secret Warehouse",
         "line2":"",
         "city":"NYC",
         "postcode":"10021",
         "county":"",
         "country":"USA",
         "countrycode":""
      }
   ],
   "decision":"Screening"
}
This post is identical to the one received when an app hits screening checks in the first check. The post contains the uniqueid. Client can use the uniqueid to identify the application and take the necessary steps. The screening hit which prompts this call to the webhook can be found in the UDF. In the example above the screening hit is pep-class-1.

Test Cases

The idv api provides two kinds of output. Every time an API is called an immediate reply is provided (synchronous Reply). The synchronous reply provides an immediate reply stating that an application was queued for processing, a file has been added to an app, the result of an electronic kyc or sanction checking (see api returns)

Since some operations are performed by manual agents a second asynchronous call is sent to the client once the document verfication process is completed (see Receiving the results of the verification process)

In order to facilitate the testing process the following test cases can be used. These test cases simulate the synchronous and asynchronous replies without involving a physical agent on the idv side. In this way integration can occur at a faster pace.

TEST # NAME SURNAME DOB ADDRESS 1 CITY POSTCODE COUNTRY Country Code UDF API Return Postback to webhook
1 Tony Starks 14 May 1970 10880 Malibu Point Florida 299735 USA US 0000 APPROVED
2 Clark Kent 21 Jun 1947 Daily Planet Metropolis 123456 USA US 0000 PENDING
3 Bruce Wayne 30 Apr 1980 Wayne Mansion Gotham City 456897 USA US 0000 PENDING - ID ok, POA out of date
3 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 3, simulating the posting of a valid POA. 0000 APPROVED
4 Peter Parker 17 Mar 1979 Forrest Hills, Queens NYC 11412 USA US 0000 PENDING - Missing back of ID, POA wrong format
4 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 4, simulating the posting of a valid POA. 0000 PENDING -ID incorrect
5 Bruce Banner 15 May 1955 Hulkbuster Base New Mexico 87102 USA US 0000 FRAUD
6 Matt Murdock 03 Sep 1974 Hells Kitchen NYC 10036 USA US 0000 EXPIRED
7 Diana Prince 25 Apr 1942 1 Kings Road London SW1 UK GB 0020  
8 Wade Wilson 14 Jan 1980 1 Secret Warehouse NYC 10021 USA US 0021 Screening
8 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 8, simulating the posting of a invalid ID. 0000 Pending
9 Linda Lee 11 Feb 1979 Midvale Orphanage Metropolis 12345 USA US 0021  
9 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 9, simulating the posting of a valid ID. 0000 Approved
10 Barry Allen 01/10/1956 1 Main Street Central City 98765 USA US   Screening - APPROVED AWAITING DOCS
11 Scott Summers 08/04/1987 1407 Graymalkin Lane NYC 12154 USA US   APPROVED - Screening OK
12 Remmy LeBeau 04 Aug 1984 100 New Tian California 1122 USA US 0000 PENDING - ID OK/ POA OUT OF DATE
13 Frank Castle 01 Feb 1974 Little Italy NYC 10012 USA US 0018 Approved
14 Ororo Munroe 01 May 1975 Harlem NYC 10027 USA US 0019 Pending
14 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 14, simulating the posting of a valid ID for sanction investigation. 0000 Approved
15 Overwood Inc 1609 Park Avenue Baltimore 21201 USA US 0000
15 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 15, passing bank_statement as file_type and any file id simulating the posting of an invalid bank statement. 0000 Pending
You will receive 2 postbacks. The first postback will simulate the invalidity of the bank statement. The second postback will place the app in pending status.
15 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 15, passing bank_statement as file_type and any file id simulating the posting of an valid bank statement. 0000 Approved
You will receive 2 postbacks. The first postback will simulate the validity of the bank statement. The second postback will place the app in approved status.
16 Shaun Murphy 1 Feb 1968 3000 Isabella Avenue Cincinnati OH 45208 USA US 0000 Pending
16 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 16, passing bank_statement as file_type and any file id simulating the posting of an invalid bank statement. 0000 Pending
You will receive 2 postbacks. The first postback will simulate the invalidity of the bank statement. The second postback will place the app in pending status.
16 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 16, passing bank_statement as file_type and any file id simulating the posting of an valid bank statement. 0000 Approved
You will receive 2 postbacks. The first postback will simulate the validity of the bank statement. The second postback will place the app in approved status.
17 Mike White 1 Feb 1978 3010 Isabella Avenue Cincinnati OH 45208 USA US 60376243 0018 Approved
18 Mike White 1 Mar 1978 3010 Isabella Avenue Cincinnati OH 45208 USA US 60376243 0019 Pending
UDF contains reason for failure in this case date of birth mismatch. dob_mismatch
OR18 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 18, passing identity as file_type and any file id simulating the posting of an valid identity document. 0000 Approved
You will receive 2 postbacks. The first postback will simulate the validity of the identity document. The second postback will place the app in approved status.
18 Perform a ModApp to change the Date of birth to 1 Feb 1978 simulating the correction of date of birth. 0018 Approved
You will receive a postback showing the app in approved status.
19 Mike White 1 Feb 1978 3000 Isabella Avenue Cincinnati OH 45208 USA US 60376243 0019 Pending
UDF contains reason for failure in this case date of birth mismatch. address_mismatch
OR19 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 19, passing identity as file_type and any file id simulating the posting of an valid identity document. 0000 Approved
You will receive 2 postbacks. The first postback will simulate the validity of the identity document. The second postback will place the app in approved status.
19 Perform a ModApp to change the Address to 3010 Isabella Avenue Cincinnati simulating the correction of Address 0018 Approved
You will receive a postback showing the app in approved status.
20 Mike White 1 Mar 1978 3010 Isabella Avenue Cincinnati OH 45208 USA US 123456789 0019 Pending
UDF contains reason for failure in this case SSN mismatch. ssn_mismatch
OR20 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 20, passing identity as file_type and any file id simulating the posting of an valid identity document. 0000 Approved
You will receive 2 postbacks. The first postback will simulate the validity of the identity document. The second postback will place the app in approved status.
20 Perform a ModApp to pass the 60376243 in the UDF field. This simulates the correction of SSN. 0018 Approved
You will receive a postback showing the app in approved status.
21 James Smith 1 Jan 1986 2423 St. James Street London SW1A1AA United Kingdom GB 0000
21 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 21, passing eDVPassport or eDVOther as file_type and any file id simulating the posting of a valid passport or valid driving license respectively. 0031 Approved
You will receive 2 postbacks. The first postback will simulate the approval of the document. The second postback will place the app in approved status.
22 John Johnson 1 Jan 1986 2423 St. James Street London SW1A1AA United Kingdom GB 0000
22 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 22, passing eDVPassport or eDVOther as file_type and any file id simulating the posting of an invalid passport or invalid driving license respectively. 0032 Expired
You will receive 2 postbacks. The first postback will refer to the document being incorrect. The second postback will place the app in expired status.
23 David Williams 1 Jan 1986 2423 St. James Street London SW1A1AA United Kingdom GB 0000
23 Perform an Add File call with any file refering to the same uniqueid used in initial call of test 23, passing eDVPassport or eDVOther as file_type and any file id simulating the posting of a passport or driving license respectively. 0033 Pending
You will receive 2 postbacks. The first postback will simulate the marking of the document as needing to be manually reviewed. The second postback will place the app in pending status.