Documents are a core concept in the First AML platform. Individuals, Entities and Cases can all have a list of associated documents. Documents have a type, and in some cases may have other associated metadata.
A document contains a list of associated files, this allows a single document (such as an Identity document, like a drivers license) to have multiple associated files such as the front and back images, that belong to the single document.
Here is an example query fragment for retrieving a document and its associated files:
documents {
documentId
type
files {
fileId
fileExtension
fileTitle
contentsUrl
}
}
Downloading
To retrieve the contents of the file you must make an authenticated request to the contentsUrl property return in the response by passing in the Authorization: Bearer ... header, as you do with each /graphql endpoint request.
The contentsUrl url when fetched via a GET request may return a 30x redirect response, pointing to a new location. Your API client code needs to be configured to follow any redirects. However you do not have to pass the Authorization header to any of those subsequent redirect requests.
Uploading
You are able to add and upload files for a document using the mutations to add documents and files first and then by making a http POST to the url provided in the uploadUrl field of the file add response. The exact mutations to call differ in name but are overall very similar for individual and entity documents.
To begin the process of creating an individual doc make a post to the createIndividualDocument mutation
createIndividualDocument
Query
mutation CreateIndividualDocument($input: CreateIndividualDocumentInput!) {
createIndividualDocument(input: $input) {
__typename
... on IndividualDocumentInformation {
documentId
}
... on ValidationErrors {
errors {
message
fieldPath
}
}
}
}
Variables
{
"input": {
"caseId": 123,
"individualId": 456,
"documentTitle": "Jane Does Passport",
"countryCode": "nz",
"documentType": "PASSPORT",
"fields": [
{
"name": "number",
"value": "abc12345"
},
{
"name": "expiry",
"value": "2025-05-05"
}
]
}
}
The result of this invocation includes a document id that can be used in the addIndividualDocumentFile mutation.
addIndividualDocumentFile
Query
mutation AddIndividualDocumentFile($input: AddIndividualDocumentFileInput!) {
addIndividualDocumentFile(input: $input) {
__typename
... on AddIndividualDocumentFileResult {
file {
fileId
}
uploadUrl
}
... on ValidationErrors {
errors {
message
fieldPath
}
}
}
}
Variables
{
"input": {
"caseId": 123,
"individualId": 456,
"documentId": 33,
"fileTitle": "1st page of passports",
"fileExtension": ".jpg"
}
}
The result of this invocation includes an upload URL that can be posted to to upload the file. The post is a standard HTTP POST authenticated using your existing Bearer token.
Note: Entity documents currently only support 1 file per document.
Fields
A document may or may not have multiple data fields associated with it, these fields contain information such as the document number or expiry date. This information is used to drive things like verifications in the system and thus where required must be of the correct format.
The various fields are defined in the documentation for individual documents and entity documents. From time to time these will get updated to add or remove information required by the regulatory requirements of countries, support new features or expand coverage of countries.
The fields required are identified by a country code and a document type, and required fields for a document may change on a per country bases, for example an NZ drivers licence does require different fields to an AU drivers licence. In all cases the country code refers to the country of issue of the document not the country of residence of the individual to whom the document belongs.
If there is no specific field definition for the country in question there is a global document defintion for that type that will be applied. For example a drivers licence from Kazakhstan has no specific definition in the documentation and thus will use the global defintion for fields and validation.
