Vault API Introduction

ID Analyzer Vault is a secured document database with automatic multi-region replication and strong consistency, your data is safe and has a 99.999% availability guarantee, even when disasters strike. Storing documents and user information in the vault allows you to access the data anytime after successful user-onboarding, these data can be accessed via API or through web portal.

Key features:

  • Store up to 10,000,000 documents and personal data
  • Perform search on documents using keywords and operators
  • Perform search using image of a person and return matching document

Add Entry

There are two ways to add entry into vault:

  1. Core API and set vault_save as true
  2. DocuPass API and set vault_save as true

Entries saved will include all the information parsed and the document image.

Get Entry Content

When entries are added to the vault, both Core API and DocuPass API will return a vault entry identifier named vaultid. You can use the identifier to query the content of an entry in the vault by submitting an HTTP POST request to the following endpoint.

https://api.idanalyzer.com/vault/get
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
id String Vault entry identifier
Successful Response
{
    "success": 1,
    "data": {
        "id": "srGVDvSXxlM3mXgbr5DBP3lw3RXLgFDp",
        "createtime": "2020-05-18 15:49:01",
        "updatetime": "2020-05-18 15:49:01",
        "trustlevel": "0",
        "trustnote": "",
        "docupass_reference": null,
        "docupass_success": null,
        "docupass_failedreason": null,
        "docupass_customid": null,
        "documentNumber": "N123-4567-8888",
        "documentNumber_formatted": "N1234567888",
        "personalNumber": null,
        "firstName": "SAMPLE",
        "middleName": "MIDDLE",
        "lastName": "IDCARD",
        "fullName": "SAMPLE MIDDLE IDCARD",
        "firstName_local": null,
        "middleName_local": null,
        "lastName_local": null,
        "fullName_local": null,
        "dob": "1990-08-08",
        "issued": "2018-06-01",
        "expiry": "2028-06-01",
        "sex": "M",
        "height": "5'-10\"",
        "weight": "158 lbs",
        "hairColor": null,
        "eyeColor": null,
        "address1": "123 EXAMPLE ST",
        "address2": "SOMEPLACE, IL",
        "postcode": "60000",
        "placeOfBirth": null,
        "documentType": "D",
        "documentName": null,
        "vehicleClass": null,
        "restrictions": null,
        "endorsement": null,
        "email": null,
        "mobile": null,
        "landline": null,
        "issueAuthority": null,
        "issuerOrg_region_full": "Illinois",
        "issuerOrg_region_abbr": "IL",
        "issuerOrg_iso2": "US",
        "nationality_iso2": "US",
        "optionalData": "DD 00000000000000",
        "optionalData2": null,
        "customdata1": null,
        "customdata2": null,
        "customdata3": null,
        "customdata4": null,
        "customdata5": null,
        "block": "0",
        "image": [
            {
                "id": "2g9NV5a3OWjZ8AwiNqmxH6eLjtlCHZw9",
                "type": "0",
                "hash": "09c4cbe8bc057a735c47d053305f7523",
                "url": "https://objects.idanalyzer.com/v0_2g9NV5a3OWjZ8AwiNqmxH6eLjtlCHZw9.jpg",
                "createtime": "2020-05-18 15:49:01"
            }
        ]
    }
Failed Response
{
    "error": {
        "message": "Document not found",
        "code": 2002
    }
}
Fields

Check below for a list of fields contained in a vault entry. Note that a document may not contain information for every fields, hence some of the field value will be null.

Key Type Property Description
id String Read-only Vault entry identifier
createtime Timestamp (YYYY-MM-DD HH:MM:SS) Read-only Timestamp of entry creation in UTC
updatetime String (YYYY-MM-DD HH:MM:SS) Read-only Timestamp of last modification in UTC
trustlevel String Read/Write 0 Undetermined
1 Invalid document
2 Suspicious
3 Valid
. This score is calculated automatically if authentication is enabled.
trustnote String Read/Write Warnings associated with document validity.
docupass_reference String Read/Write Reference code to DocuPass session
docupass_success Integer Read/Write 0 or 1, whether the DocuPass verification succeeded or failed.
docupass_failedreason String Read/Write If DocuPass verification has failed, the reason why it failed.
docupass_customid String Read/Write customid passed when creating DocuPass verification.
documentNumber String Read/Write The unique identifier of the document (Passport No./Driver License No. etc)
documentNumber_formatted String Read-only Automatically generated string of documentNumber without any symbols, this field is useful for filtering results.
personalNumber String Read/Write A secondary identifier number on the document
firstName String Read/Write First name / Given name
middleName String Read/Write Middle name(s)
lastName String Read/Write Last name / Family name
fullName String Read/Write Full name (Updating other name fields will not update fullName)
firstName_local String Read/Write First name in local language
middleName_local String Read/Write Middle name in local language
lastName_local String Read/Write Last name in local language
fullName_local String Read/Write Full name in local language
dob Date (YYYY-MM-DD) Read/Write Date of birth
issued Date (YYYY-MM-DD) Read/Write Issue date
expiry Date (YYYY-MM-DD) Read/Write Expiry date
sex String Read/Write M Male
F Female
X Unspecified
height String Read/Write Height of person
weight String Read/Write Weight of person
address1 String Read/Write Address line 1
address2 String Read/Write Address line 2
postcode String Read/Write Address postcode
placeOfBirth String Read/Write Place of birth
documentType String Read/Write P Passport
D Driver's License
I Identity Card
V Visa
R Residence Card
O Other
documentName String Read/Write Name of document
vehicleClass String Read/Write Class of vehicles on driver's license
restrictions String Read/Write Driving restrictions
endorsement String Read/Write Driver license endorsement
hairColor String Read/Write Hair color
eyeColor String Read/Write Eye color
email String Read/Write User email address
mobile String Read/Write User mobile phone number
landline String Read/Write User landline phone number
issueAuthority String Read/Write Issue authority of document
issuerOrg_region_full String Read/Write Document issuer subregion/state. Example: California
issuerOrg_region_abbr String Read/Write Document issuer subregion/state abbreviation. Example: CA
issuerOrg_iso2 String Read/Write Document issued country code in ISO2. Example: US
nationality_iso2 String Read/Write Document holder nationality in ISO2. Example: US
optionalData
optionalData2
String Read/Write Extra unspecific data included in the document
customdata1
customdata2
customdata3
customdata4
customdata5
String Read/Write 5 custom strings that can be used to add custom memo to the entry
block String Read/Write If a document uploaded though Core API or DocuPass matches a blocked document, an error will be thrown.
0 No block
1 Block document number
2 Block firstname/lastname
3 Block both document number and firstname/lastname
image Array Read-only Contains a list of images associated with the entry.
id: Image identifier
type: 0 for document and 1 for person hash: MD5 hash of image
url: URL to the image
createtime: Time image was uploaded in UTC
Images can be updated through addimage and deleteimage functions.

List and Filter Entries

To list all the entries stored inside the vault or search for entries with specific values, send an HTTP POST request to the following endpoint.

https://api.idanalyzer.com/vault/list
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
Optional Parameters
Key Type Description
orderby String Name of the field used to order the result. (Default: createtime)
sort String ASC to sort results in ascending order, DESC to sort in descending order. (Default: ASC)
limit Integer (1 to 100) Number of vault entries to return. (Default: 10)
offset Integer Return list starting at a specific entry, for example, when limit=10, to access the third page of the results, use offset=20
filter Array of String To filter/search entries you need to construct filter statements and put them in an array, you can have 5 filter stataments per request. Each filter statement consists of 3 parts, a string starting with a field name, followed by an operator, and followed by a value. Note that all string operations are case-insensitive.
Fields
address1 address2 block createtime customdata1 customdata2 customdata3 customdata4 customdata5 dob documentName documentNumber documentNumber_formatted documentType docupass_reference docupass_success expiry firstName firstName_local fullName fullName_local height issueAuthority issued issuerOrg_iso2 issuerOrg_region_abbr issuerOrg_region_full lastName lastName_local middleName middleName_local nationality_iso2 optionalData optionalData2 personalNumber placeOfBirth postcode restrictions sex trustlevel trustnote updatetime vehicleClass weight
Operators
<: less than
<=: less than or equal to
=: equal to
>: greater than
>=: greater than or equal to
!=: not equal to
^: string starts with
~: string ends with
%: string contains
Values
Simply append the value after operator, equal to, not equal to and string contains operators support multiple values separated with |.
Examples
Search documents uploaded on 2020/05/08: ["createtime>=2020-05-08 00:00:00","createtime<2020-05-09 00:00:00"]
Search customers whose first name contains with 'JOHH': firstName%JOHH
Search all female customers: sex=F
Search all documents issued by CA, TX or IL: issuerOrg_region_abbr=CA|TX|IL
Tips
If you are submitting the POST request using x-www-form-urlencoded, you should use filter[] as the field name, you can have up to 5 filter[] fields with different filter statements.
Example JSON Request
{
    "apikey": "wzV1RrZaM3ajPFGJN9DqaMPuhYyHcnms",
    "limit": 50,
    "filter": ["createtime>=2020-05-08 00:00:00","createtime<2020-05-09 00:00:00"]
}
Successful Response

The response should include a list of entries and their full content.

{
    "limit": 10,
    "offset": 0,
    "nextoffset": 10,
    "total": 100,
    "items": [
        ...
    ]
}

If no entries are found, items list will be empty.

{
    "total": 0
    "items": []
}
Response Fields
Key Type Description
limit Integer current limit
offset Integer current offset
nextoffset Integer offset value for the next set of data. If the current set of data is the final set of data, this field will not be returned.
total Integer Total number of entries found.
items Array An array of entries found and their full content, identical to the contents returned by GET method.
Failed Response
{
    "error": {
        "message": "Invalid filter",
        "code": 2001
    }
}
Pagination

To query the next page of the result, simply use the nextoffset as your offset value, with all other parameters unchanged. If you are on the last page of data, nextoffset field will not be present. To get the total number of pages simply divide total by limit.

Update Entry

You can update the value of a single field or values of multiple fields in a vault entry by making HTTP POST request to:

https://api.idanalyzer.com/vault/update
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
id String Vault entry identifier
Field Parameters

Simply include the field key and value that you wish to update in your POST request. The field key should be one of the writable fields below:

address1 address2 customdata1 customdata2 customdata3 customdata4 customdata5 dob documentName documentNumber documentType docupass_reference docupass_success expiry firstName firstName_local fullName fullName_local height issueAuthority issued issuerOrg_iso2 issuerOrg_region_abbr issuerOrg_region_full lastName lastName_local middleName middleName_local nationality_iso2 optionalData optionalData2 personalNumber placeOfBirth postcode restrictions sex trustlevel trustnote vehicleClass weight

Example JSON Request

This example will update the first name to "JOHN" and set date of birth to "null".

{
    "apikey": "wzV1RrZaM3ajPFGJN9DqaMPuhYyHcnms",
    "id":"srGVDvSXxlM3sXgbr5DBP3lw3RXLgFDp",
    "firstName": "JOHN",
    "dob": null
}
Successful Response
{
    "success": 1
}
Failed Response
{
    "error": {
        "message": "Nothing to update",
        "code": 2003
    }
}

Delete Entry

You can delete a single vault entry by making HTTP POST request to:

https://api.idanalyzer.com/vault/delete

All images associated with the entry will also be deleted and no longer accessible.

Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
id String Vault entry identifier which you wish to delete
Successful Response
{
    "success": 1
}
Failed Response
{
    "error": {
        "message": "Document not found",
        "code": 2002
    }
}

Add Image

You can upload an image and add it to an existing vault entry by making HTTP POST request to:

https://api.idanalyzer.com/vault/addimage
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
id String Vault entry identifier which you wish to delete
type String Set the type of image: 0=document and 1=person
image String Base64-encoded image data
imageurl String Remote image URL
Successful Response
{
    "success": 1,
    "image": {
        "id": "Hx13aULZa1Aikq01yjtTeQGqwMEmPgym",
        "type": "0",
        "hash": "16b0e0b6ed97e9ea79cdd96fc8452e38",
        "url": "https://objects.idanalyzer.com/v5_Hx13aUL3a1Mikq51yjtTeQGqwMEmPgym.jpg",
        "createtime": "2020-05-25 13:01:19"
    }
}
Failed Response
{
    "error": {
        "message": "Invalid value 'image', based64-encoded image data expected.",
        "code": 5
    }
}

Delete Image

You can delete an image inside a vault entry by making HTTP POST request to:

https://api.idanalyzer.com/vault/deleteimage

Note that after an image is deleted, the URL to the image may still be accessible for a short-period of time due to caching.

Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
id String Vault entry identifier containing the image
imageid String id of the image to delete
Successful Response
{
    "success": 1
}
Failed Response
{
    "error": {
        "message": "Nothing to update",
        "code": 2003
    }
}

Face Search

Face search allows you to search the entire vault using an image of a person. To use face search feature, you must enable face search indexing under web portal, and train your vault datasets periodically.

https://api.idanalyzer.com/vault/searchface
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
image String Base64-encoded image data
imageurl String Remote image URL
Optional Parameters
Key Type Description
maxentry Integer Number of matching entries to be returned, between 1 to 10. (Default: 10)
threshold Float Customized identification confidence threshold, in the range of 0 to 1. (Default: 0.5)
Successful Response

If matching entries are found, a list of documents with full contents will be returned similar to the list command.

{
    "items": [
        ...
    ]
}
Failed Response
{
    "error": {
        "message": "Vault not trained.",
        "code": 2023
    }
}

Face Search Training

Before performing face search, you must issue a train command to train the document datasets inside your vault. You may also train your vault data through web portal.

The training task is asynchronous, training time depends on the number of vault entries and images. It could take from several seconds to an hour.

https://api.idanalyzer.com/vault/train
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
Successful Response
{
    "success": 1
}
Failed Response
{
    "error": {
        "message": "Vault is under training.",
        "code": 5001
    }
}

Training Status

Check whether vault training is still ongoing or has completed.

https://api.idanalyzer.com/vault/trainstatus
Required Parameters
Key Type Description
apikey String Your private API key is available under your account dashboard.
Successful Response
{
    "status": "succeeded",
    "startTime": "2020-10-02 15:45:03",
    "statusChangeTime": "2020-10-02 15:45:03",
    "lastSuccessTime": "2020-10-02 15:45:03",
    "error": null
}
Response Fields
Key Type Description
status String nottrained: Never trained
notstarted: Training is not running
running: Training is currently running
succeeded: Training succeeded
failed: Training failed
startTime String Time when last training was started in UTC.
statusChangeTime String Time for last status change in UTC.
lastSuccessTime String Time for last successful training in UTC.
error String Error message associated with failed training status.
Failed Response
{
    "error": {
        "message": "Face search feature is not enabled on your account",
        "code": 5001
    }
}