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:

• Staging - https://stagingapi.idv.technology/rest/

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
1	Screening check only
2	Screening check, electronic kyc, manual kyc
3	Screening check, manual kyc
4	Electronic kyc, manual kyc
5	Manual 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

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"
    }
  ]
}
'

{
   "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"
}        

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

{
   "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"
}