Working with Documents¶
The application container allows you to access individual documents in various ways. Each document contains metadata on aspects of the document, including the following:
Document Status – the overall result of the document.
Document Fields – the data read from the document.
Machine-Readable Zone (MRZ) – the machine-friendly data found at the bottom of many documents.
Document Feedback Properties – properties which summarise the various checks that have been carried out.
External Services Data – the system will sometimes send data to external services for additional checks, for example Amberhill.
Image Data - information about images submitted for the document.
Document Fields¶
A document stores a number of internal data fields and most fields can be accessed as shown below:
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [
{
"DataType": 0,
"DisplayName": "Document Number",
"DocumentId": "...",
"FieldValueDate": null,
"FieldValueString": "XN5007316",
"Name": "VI Document Number",
"SourceId": 2
},
{
"DataType": 0,
"DisplayName": "Firstname",
"DocumentId": "...",
"FieldValueDate": null,
"FieldValueString": "Lauren",
"Name": "VI Firstname",
"SourceId": 2
},
],
"DocumentId": "...",
"DocumentName": "Passport"
}
]
}
}
There may be multiple instances of certain fields, when comparing the DocumentField.DisplayName property.
This is because the given data can be in multiple places within a document, or may have been manually input.
The DocumentField.SourceId property specifies the source of the data. The API gives higher values for
DocumentFieldSource for the more trusted sources. For example, Manual = 5, whereas Human-Readable Zone (Hrz) = 1.
The DocumentField.Name field always begins with a two or three letter code for the source of the field.
Examples include “VI Firstname” for the first name read from the MRZ and “VIZ Firstname” for the
first name read from the HRZ.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// get field by field name
console.log('first name:', doc.getField(Document.FIELD_FIRSTNAME).getValue());
// get field value by field name (equivalent to the line above)
console.log('first name:', doc.getFieldValue(Document.FIELD_FIRSTNAME));
});
See the Document.getField() or Document.getFieldValue() methods.
While Document.getField() returns meta information about the document
field (including its value), Document.getFieldValue() is more
convenient if all you needed is the field’s value to start with.
The most useful Display Names are those listed below:
Actual Display Name |
Description |
|---|---|
|
Number of document. |
|
User first name. |
|
User middle name. |
|
User surname. |
|
Date of birth. |
|
Gender. |
|
Document expiry date. |
The TrustID Javascript API provides a number of shortcut helper methods on the
Document() class in order to conveniently access most commonly used
document fields. For example, to access the document holder’s first name we
could have used the corresponding convenience helper method
Document.getFirstname() as the following example demonstrates:
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// shortcut to get the document holder's first name
console.log('first name:', doc.getFirstname());
});
The TrustID Javascript API provides a short list of declared field names, such
as Document.FIELD_FIRSTNAME. However, the TrustID Cloud supports a
wide range of different fields which are outside of the scope of this
documentation.
Field |
Actual Display Name |
Helper Method |
|---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
Document Properties¶
A number of additional data elements are encoded as separate property fields on the object
itself, such as DocumentType, IssuingCountry or Nationality.
In the following sections, a number of these property fields are described for various aspects of a document.
The following gender information is supported by the TrustID Cloud:
Display Name |
Internal Encoding |
Attribute |
|---|---|---|
Male |
|
|
Female |
|
|
Transgender |
|
|
Unspecified |
|
|
Unknown |
|
Display Name |
Internal Encoding |
Attribute |
|---|---|---|
Male |
|
|
Female |
|
|
Transgender |
|
|
Unspecified |
|
|
Unknown |
|
Document Type¶
The TrustID Cloud distinguishes different document types including passport, national identity card or driving licence.
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"DocumentName": "Passport",
"DocumentType": 0
}
]
}
}
To find the underlying type of the document, examine the Document.DocumentType property.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// document type
console.log('document type (encoded):', doc.DocumentType);
console.log('document type (display):', doc.getDocumentTypeDisplay());
console.log('isPassport:', doc.isPassport());
console.log('isVisa:', doc.isVisa());
console.log('isIdentityCard:', doc.isIdentityCard());
console.log('isDrivingLicence:', doc.isDrivingLicence());
console.log('isSupportingDocument:', doc.isSupportingDocument());
// supporting document?
if (doc.isSupportingDocument()) {
console.log('type of supporting document:', doc.SupportingDocumentName);
}
});
The Document()
class provides a number of methods that are related to the document type:
Document Name¶
A more specific way to distinguish the type of document is by examining the “DocumentName” property. This allows you, for example, to distinguish between an “ID Card” and a “Biometric Residence Permit”.
**Request**
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"DocumentName": "Passport",
"DocumentType": 0
}
]
}
}
To find the specific type of the document, examine the Document.DocumentName property.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// document type
console.log('type of document:', doc.DocumentName);
});
Issuing Country and Nationality¶
The issuing country of the document and the nationality of the document holder are both encoded by additional data which provides information about the country.
The following example shows a data structure for a country:
{ Name: "Germany", // display name Mrz: "DEU", // MRZ encoding AltMrz: "D", // alternative MRZ encoding EU: true, // EU membership UK: false, // UK membership }
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"DocumentName": "Passport",
"DocumentType": 0,
"IssuingCountry": {
"AltMrz": null,
"EU": true,
"Mrz": "IRL",
"Name": "Ireland",
"UK": false
},
"Nationality": {
"AltMrz": null,
"EU": true,
"Mrz": "IRL",
"Name": "Ireland",
"UK": false
}
}
]
}
}
To find the country that issued the document, use Document.IssuingCountry and
for the nationality of the holder use Document.Nationality.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// issuing country
console.log('issuing country:', doc.IssuingCountry);
console.log('issuing country (display):', doc.getIssuingCountryDisplay());
// nationality
console.log('nationality:', doc.Nationality);
console.log('nationality (display):', doc.getNationalityDisplay());
});
For example, to present the name of the issuing country for a document, you may
simply refer to doc.IssuingCountry.Name. Alternatively you may use the
Document.getIssuingCountryDisplay() and
Document.getNationalityDisplay() helper methods.
Machine-Readable Zone (MRZ)¶
Some documents may have an MRZ and a number of document properties are related to this type of information:
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"Mrz": "P<IRLOSULLIVAN<<LAUREN<<<<<<<<<<<<<<<<<<<<<<\nXN50073162IRL8805049F2309154<<<<<<<<<<<<<<<6",
"MrzCharacterCount": 44,
"MrzImageType": 3,
"MrzLineCount": 2,
"MrzSameLength": true
}
]
}
}
While the Document.Mrz property contains the entire MRZ
string that was read from the document, other properties provide
additional information about properties of the MRZ. For example,
Document.MrzCharacterCount provides the number of characters per
line and Document.MrzLineCount gives the number of lines.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// MRZ-related information
console.log('MRZ:', doc.Mrz);
console.log('character count per line:', doc.MrzCharacterCount);
console.log('count of lines:', doc.MrzLineCount);
console.log('all lines same length:', doc.MrzSameLength);
});
While the Document.Mrz property contains the entire MRZ
string that was read from the document, other properties provide
additional information about certain properties of the MRZ. For example,
Document.MrzCharacterCount provides the number of characters per
line and Document.MrzLineCount gives the number of lines.
See also
The TrustID Cloud performs a number of validation checks on document data related to all document data in general and to the MRZ in particular. The following section gives more information on so-called feedback properties.
Document Feedback Properties¶
The TrustID Cloud provides a number of feedback properties for various aspects of a document. A feedback property usually represents a fact or an outcome of a validation process on the document data itself. A good example is whether the document is in date or has expired.
Feedback properties are designed to be presentable to users of the system as a list of established fact or outcome of the validation process that the TrustID Cloud carries out based on the information presented by the document.
A number of different sets of feedback properties are available; all represent a list of feedback properties and work in the same way but they contain different sets of feedback properties, grouped by different aspects.
Document.GeneralDocumentProperties- general document feedback properties that are most important to determine the correctness of a document.Document.MrzValidationProperties- feedback properties related to the validation of the MRZ.Document.MissingFieldsProperties- feedback properties related to missing information about the document or the document holder.Document.DocumentResultsSummary- short list of most important feedback questions an operator supplied.
Document.GeneralDocumentProperties- general document feedback properties that are most important to determine the correctness of a document.Document.MrzValidationProperties- feedback properties related to the validation of the MRZ.Document.MissingFieldsProperties- feedback properties related to missing information about the document or the document holder.Document.DocumentResultsSummary- short list of most important feedback questions an operator supplied.
The following example demonstrates how feedback properties can be enumerated and presented:
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"GeneralDocumentProperties": [
{
"ErrorMessage": null,
"Name": "Photo matches applicant (User)",
"Value": true,
"ValueUndefined": false
},
{
"ErrorMessage": null,
"Name": "Document in date",
"Value": true,
"ValueUndefined": false
},
{
"ErrorMessage": null,
"Name": "Document details complete",
"Value": true,
"ValueUndefined": false
},
{
"ErrorMessage": null,
"Name": "Amberhill Check",
"Value": true,
"ValueUndefined": false
}
]
}
]
}
}
Notable properties are:
DocumentFeedback.Name- the name or description of the fact or outcome that each feedback property represents, for example, whether the document has expired or not.DocumentFeedback.Value-trueif the corresponding outcome or fact that the feedback property represents, holds true; otherwise, it does not hold true.DocumentFeedback.ValueUndefined- “true” if the outcome of the test is a warning. This could be if the test could not be carried out for some reason, for example the “Amberhill Check” could not be carried out as a connection the Amberhill service could not be made. It could also be because the test is not considered a failure, but also did not pass. For example, “Expiration Date” was not valid as the document is out of date, but it is also not a fail, as an expired document of the particular type is valid.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// general document properties
for (var i = 0; i < doc.GeneralDocumentProperties.length; i++) {
var feedback = doc.GeneralDocumentProperties[i];
console.log(feedback.Name, ': ', feedback.Value);
}
});
Notable properties are:
FeedbackProperty.Name- the name or description of the fact or outcome that each feedback property represents, for example, whether the document has expired or not.FeedbackProperty.Value-trueif the corresponding outcome or fact that the feedback property represents, holds true; otherwise, it does not hold true.FeedbackProperty.ValueUndefined- “true” if the outcome of the test is a warning. This could be if the test could not be carried out for some reason, for example the “Amberhill Check” could not be carried out as a connection the Amberhill service could not be made. It could also be because the test is not considered a failure, but also did not pass. For example, “Expiration Date” was not valid as the document is out of date, but it is also not a fail, as an expired document of the particular type is valid.
See also
See the FeedbackProperty() class reference for
more information about feedback properties.
Document-level Custom Fields¶
A number of custom fields can be configured on document-level. Custom fields must be declared through the TrustID Cloud configuration first in order to use them.
All custom fields related to a document can be accessed via the
Document.CustomFields property and a number of helper methods are
available related to custom document fields:
Request
POST {{server}}/VPE/dataAccess/retrieveDocumentContainer/
Content-Type: application/json
{
"DeviceId": "device-id",
"SessionId": "...",
"ContainerId": "..."
}
Response
{
"AccessDenied": false,
"Message": "Operation executed successfully.",
"SessionExpired": false,
"Success": true,
"Container":
{
"Documents": [
{
"CreatedAt": "/Date(...)/",
"CustomFieldDictionary": [],
"CustomFieldKeys": [],
"DocumentFields": [],
"DocumentId": "...",
"CustomFieldDictionary": [
{
"Key": "OptionalReference",
"Value": {
"DataType": 0,
"DisplayName": "Reference",
"Help": null,
"Index": 0,
"PropertyName": "OptionalReference",
"Required": false,
"Value": null,
"Values": ""
}
}
],
"CustomFieldKeys": [
"OptionalReference"
],
}
]
}
}
To access all custom fields for a given document, examine the Document.CustomFieldDictionary.
var api = new TVS.Api();
api.login('username', 'password').then(function() {
// retrieve document container for the given containerId(guid)...
return api.retrieveDocumentContainer(containerId);
}).then(function(application) {
// examine first document in application
var doc = application.Documents[0];
// custom document fields
console.log('has custom fields:', doc.hasCustomFields());
console.log('custom field values:', doc.getCustomFieldValues());
console.log('custom fields (display):', doc.getCustomFieldValuesDisplay());
// accessing meta information (including value)
for (var i = 0; i < doc.CustomFields.length; i++) {
var field = doc.CustomFields[i];
console.log('display name:', field.DisplayName);
console.log('internal name:', field.PropertyName);
console.log('value:', field.getValue());
console.log('isTextField:', field.isTextField());
console.log('isDateField:', field.isDateField());
console.log('isDropDownField:', field.isDropDownField());
console.log('hasHelp:', field.hasHelp());
if (field.hasHelp()) console.log('help:', field.Help);
if (field.isDropDownField()) console.log('allowed values:', field.getValues());
}
});
See the CustomField() class reference
for more information about document-level custom fields.