What are `files`, `documents`, and `document_images`? (API)

There are two resources you can add to profiles:

  • files: You can attach these to task note or add them to a form answer. Files are made up of one or more images.
  • documents: You can use these as input to run checks (i.e. the Document verification or Company document verification check). When they are used as input to run checks, they're made up of one or more document_images.

    Documents can also be returned as output from checks (e.g. when the Company data check is used to assess financials). When they're returned as output, multiple related items can be bundled together in a single document (e.g. an ID and the liveness video used to support it). They may also have additional metadata returned by the data provider (e.g. an expiry date or the type of company financial report).
Files cannot be used to run checks.

Add `files` to a profile

Each file is a single image encoded in Base64. To add a file, make the following request and include the image in the request body.

The image size limit is 50MB. The following types are accepted: GIF, JPG, PNG, PDF, TIFF.
You can find free tools online to encode your images in Base64.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/files

Body parameters:

When you make the POST request, include the following parameters in the body:

Key

Value

Description

data

Required

String

See the sample request body below for a sample value.

The image, encoded in Base64.

Optionally, the Base64-encoded image can be a URI string.

name

Optional

String

Sample value: PEP Declaration Form

The file name.

If you do not send this parameter, the file name will be "Untitled" in the portal.

In this example, an image of a file icon is added to the profile's files.

Sample request body:

{    
"data": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAQAAABIkb+zAAABMUlEQVR4Ae3YsTFAURhE4ZUAkAKIFAhEkIpFoAIAOQAJ0IYEAIAS4C07b+acv4H9Zm50RURE9K061KdNXeqj4I0pUL3m9V54eoxQpSPb+Ahhwjg9QGjRqz7KTBixzg4QDmxzQ4RzE0Apwr0NECL4AAZCHhAgeAEBghcQIDxYAQGCFxAgeAEBghcQIHgBAYIXECA8WgEBghcQIHgBAYIXECB4AQHCkwvwO0K5ANJY2QHSWNkB0lge4LzCPQMAACB6AF4AAABQbsArAAAAyg14AwAAQPQAvAMAAKDcgA8AAAAAAAAAAIDfVgEAAIDwFe46Ov9ahTuNAs5UuPEoYFyF6wl+bb2pU4ZmY4ApWarVWej9V8lUk9b++XvlXYuql7VuDWlbV38+/VIb6v/e2yciIvoEBh6x5m3tSdoAAAAASUVORK5CYII=",
"name": "PEP Declaration Form"
}

Sample response:

{
"decrypted_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAQAAABIkb+zAAABMUlEQVR4Ae3YsTFAURhE4ZUAkAKIFAhEkIpFoAIAOQAJ0IYEAIAS4C07b+acv4H9Zm50RURE9K061KdNXeqj4I0pUL3m9V54eoxQpSPb+Ahhwjg9QGjRqz7KTBixzg4QDmxzQ4RzE0Apwr0NECL4AAZCHhAgeAEBghcQIDxYAQGCFxAgeAEBghcQIHgBAYIXECA8WgEBghcQIHgBAYIXECB4AQHCkwvwO0K5ANJY2QHSWNkB0lge4LzCPQMAACB6AF4AAABQbsArAAAAyg14AwAAQPQAvAMAAKDcgA8AAAAAAAAAAIDfVgEAAIDwFe46Ov9ahTuNAs5UuPEoYFyF6wl+bb2pU4ZmY4ApWarVWej9V8lUk9b++XvlXYuql7VuDWlbV38+/VIb6v/e2yciIvoEBh6x5m3tSdoAAAAASUVORK5CYII=",
"id": "a7a57663-8d1b-c45b-73e2-19616ce0ebe5",
"name": "PEP Declaration Form"
}

The file id is returned in the response. Keep note of this because you'll need it to retrieve the file from the profile.

Get `files` from a profile

To get a file from a profile, make the following request.

It is not possible to get files by making a GET request to the /profiles/{profile_id}/files endpoint. This is because all files are encrypted as soon as they are added to PassFort, and, for security reasons, PassFort's web-facing servers are not able to access this data.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/files/{file_id}

Sample response:

{
"decrypted_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAQAAABIkb+zAAABMUlEQVR4Ae3YsTFAURhE4ZUAkAKIFAhEkIpFoAIAOQAJ0IYEAIAS4C07b+acv4H9Zm50RURE9K061KdNXeqj4I0pUL3m9V54eoxQpSPb+Ahhwjg9QGjRqz7KTBixzg4QDmxzQ4RzE0Apwr0NECL4AAZCHhAgeAEBghcQIDxYAQGCFxAgeAEBghcQIHgBAYIXECA8WgEBghcQIHgBAYIXECB4AQHCkwvwO0K5ANJY2QHSWNkB0lge4LzCPQMAACB6AF4AAABQbsArAAAAyg14AwAAQPQAvAMAAKDcgA8AAAAAAAAAAIDfVgEAAIDwFe46Ov9ahTuNAs5UuPEoYFyF6wl+bb2pU4ZmY4ApWarVWej9V8lUk9b++XvlXYuql7VuDWlbV38+/VIb6v/e2yciIvoEBh6x5m3tSdoAAAAASUVORK5CYII=",
"id": "a7a57663-8d1b-c45b-73e2-19616ce0ebe5",
"name": "PEP Declaration Form"
}

Add `documents` and `document_images` to a profile

Each document is a collection of one or more images.

For example, a driver's license might have one image of the front of the license and one image of the back of the license.

To add a document to a profile, you need to:

  1. Add the document images to the profile's document_images.
  2. In the profile's documents array of objects, create a new object to represent the document. Add the images from document_images to the object when you create it.
When you add an image to a profile's document_images, there's no way to see it via the portal until you create the document object later.

1. Add the `document_images` to the profile

Each document_image is a single image encoded in Base64. To add an image, make the following request.

For each request, take note of the image ID returned in the response. You'll need it to create the document object in the next step.

The image size limit is 50MB. The following file types are accepted: GIF, JPG, PNG, PDF, TIFF.
You can find free tools online to encode your images in Base64.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/document_images

Body parameters:

When you make the request, include the following parameters in the body.

Key

Value

Description

data

Required

String

See the sample request body below for a sample value.

The image, encoded in Base64.

Optionally, the Base64-encoded image can be a URI string.

image_type

Whether this key is optional or required depends on the data provider you're using to run the Document verification or Company document verification check. For more information, see the guide for your check type.

String

FRONT, BACK, or FACE

If you do not send a value for this key, the value is set to FRONT automatically.

Whether the image represents the front of the document, the back of the document, or the individual's face.

In this example, an image of a file icon is added to the profile's document_images. The image id is returned in the response.

Sample request body:

{
"data": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAQAAABIkb+zAAABMUlEQVR4Ae3YsTFAURhE4ZUAkAKIFAhEkIpFoAIAOQAJ0IYEAIAS4C07b+acv4H9Zm50RURE9K061KdNXeqj4I0pUL3m9V54eoxQpSPb+Ahhwjg9QGjRqz7KTBixzg4QDmxzQ4RzE0Apwr0NECL4AAZCHhAgeAEBghcQIDxYAQGCFxAgeAEBghcQIHgBAYIXECA8WgEBghcQIHgBAYIXECB4AQHCkwvwO0K5ANJY2QHSWNkB0lge4LzCPQMAACB6AF4AAABQbsArAAAAyg14AwAAQPQAvAMAAKDcgA8AAAAAAAAAAIDfVgEAAIDwFe46Ov9ahTuNAs5UuPEoYFyF6wl+bb2pU4ZmY4ApWarVWej9V8lUk9b++XvlXYuql7VuDWlbV38+/VIb6v/e2yciIvoEBh6x5m3tSdoAAAAASUVORK5CYII=",
"image_type": "FRONT"
}

Sample response:

{
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"image_type": "FRONT",
"upload_date": "2019-10-03 14:05:19"
}

In this next example, an image of a face icon is added to the profile's document_images. Again, the image id is returned in the response.

Sample request body:

{
"data": "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAQAAABIkb+zAAAFDklEQVR4Ae3bQ5glSRSG4e+Wcdu2bdu2bdvdu0FrtGtjbNv7tm3bNmNWoziVHTdVWfU89/23cTJzkYw8QVRUVFRUlIfK0ItZLOUXNnGIizzlARc5yEZ+Zgkz6UEpMqQsDOZ9zqDM4QTv0p9UMowarOY+ymZus5IqBCyBQWxEucg6+hNHIHIxl0soD3KOl8lOugoximsoD3OZ4aSbymxC+ZB1VMB/9OQhyqfcpzO+iuENlCGPWMvbzKADNShCEskUpjodmcFq1vLIWL+QED5J4RcU1jnMXFqQyIsk0Zx5HEZhnR9Iwgd52GG5y+u8TmXsqMybXEdZZAs58VgpTlo+VyeQjBMpTLDc6lGK46EinEch85xlJONGKkt5jkLmNAW9O3lOoJA5STO80Mxi+4fIhQeS2I1C5jvCeCXMVyhktpOAaytQIk8ZgdeG8xQlsgSXOqFE7tEaP7TmHkqkLS7klbc67lMLv9TioXxLIheOfYoS6Yqf+qFEPsSh5iiRBfhtAUqkIQ4kclxs6HdC+C3E72K/B4nHtknyvkyY9BDmkNj3eGyKE8/e55QnvVQUT+cTxGHLSJSWlaSnVWL/w7BDvPDeIDtSIpM5hkJxjMkkYmCjLgc3xAlsQ1OUlleQCnLgf2MOUBDBcd0r4hiaErGPtNI7hNGF2CB2sYEQgsO67NzRRn1EhFLF8/BNpFEoGUYhOK57UxvzgFQi0ktsviSCxczEZgTHdaXFqF5EZIl4qZXgHkqGu0jO67Zro5YSkV1a2RwkuGs+ENd1s7VRe8Asp9h4FZAs5kQ3ITmvqyLG5cSolXgCAIFcxIB4nW+F0USt5BvSFpPm7TAGyU3d19rIiRgt1krmYqUQ+/43ch+FkNzVzdWOZjFGf2olA7GWyKR/XgkmkYjktm6gdjR/YiLmIOoQpNra0ezGRMyVlSBIJcRclGC67nMTpNxiFtZEfEokEaQk7WieYSJm8BMIUoL4+2B0NUOfQlcxOpGhL+ITme02Wsf2bVQ8yAYRpEHa0fxh/2tgPkGab/9VYrJW8i1B+kY7mkkYtZWv08ERkyttMMqF0lIVqTLK41RGqipGhcFsj1Y023ixu88fEX1S7iIiy8VfW9Pku/s0A6Stzn449YtoWgV+Q3mU3wGppNNplVQeICe2pLzcRHmQa+RFkhNbD0klQh+LqcXsgDQA5UEGAJKcWvyAiLUQO5kL5svMUWaTtrliZBMiFuKIVnyTHOYdOcirpC27OD0P+feDYzxPUA7ymPFYWSlGD8eWOM6JX0zVsVKfyw665Opjpar4LjxPHDZNEbvcQxgrufUL35CPyI2VMPvE+EnYFs8xm79ZW4gdp519tMBaCPmMP0gcDrRw8KO7GV/xGOuz/mtamF+gRRrg0CcokT6YZKENc/mTnZzhIQ84y27+ZB5tCGPSK83TzbHcyIvzIXXxSx1ks8cVcuNCW5TIbd/abW6jRFr70/A0PLM0PEESO1HIfEoYr2S1uAlvIwkP5OW4RdNfU7zQlJPeNv1JRThn0Xa5xHXb5RJz26W/ja8nmRhE46v3rcdVMlrrsZTCH8bm7+YeNH//TBI+ieEtzC/Ja1n9T/t9CskU4d/2+8eG6ucsIISv+vAgcy2AkKpktiUoUogx3Mh8i4DkMqwrKA9ynlfIQSASGOLydFrLQOIIWE3eyWxLEaWsDLKxGPQ9sRg0wyhDT2057kMucpBNfizHjYqKioqK+gugEYUfpUhYBwAAAABJRU5ErkJggg==",
"image_type": "FACE"
}

Sample response:

{
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"image_type": "FACE",
"upload_date": "2019-10-03 14:08:12"
}

2. Create the `document` object

Make the following request to create an object in the profile's documents array of objects. Send the image(s) you uploaded to the profile's document_images in the previous step.

Forgot to take note of the image ID(s) in the previous step? Make a request to the /profiles/{profile_id}/document_images endpoint. The document_images array of objects is returned. Learn more in the Developer Resources for Get list of document images.

Take note of the document id returned in the response. You'll need the document id to run the check later.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_data/documents
This endpoint updates a part of the profile's collected_data. The main request to update collected_data is documented in the guide to Sync profile data with your system data and in the API resources for Update collected data. Note that, unlike the main request to update collected_data, the request above does not use ETags.

Body parameters:

When you make the request, include the following parameters in the body.

Key

Value

Description

category

Required

String

Depends on the task and data provider you're using to run the Document verification or Company document verification check. For more information, see the guide for your check type.

This field is used by the data provider to understand how to treat the document.

document_type

Required

String

Depends on the task and data provider you're using to run the Document verification or Company document verification check. For more information, see the guide for your check type.

The type of document you're creating (e.g. a passport, a driving license, etc).

images

Required

Array of objects

See the sample request body below for a sample value.

Array of objects where each object corresponds to one image from the profile's document_images.

images.id

Required

String

Sample value: ec1565b6-82c7-0577-8b3a-94462b67c97a

The unique identifier for a document image.

In this example, we'll create a document object for a passport that's made up of the FRONT and FACE images we added to the profile's document_images earlier. The document id is returned in the response.

Sample request body:

{
"category": "PROOF_OF_IDENTITY",
"document_type": "PASSPORT",
"images": [
{
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a"
},
{
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9"
}
]
}

Sample response:

{
"category": "PROOF_OF_IDENTITY",
"document_type": "PASSPORT",
"id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
"images": [
{
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"image_type": "FRONT",
"upload_date": "2019-10-08 14:20:02"
},
{
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"image_type": "FACE",
"upload_date": "2019-10-08 14:20:02"
}
]
}

Get `documents` and `document_images` from a profile

`documents`

To get a document from a profile, make the following request.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_data

Sample response:

{
"documents": [
"category": "PROOF_OF_IDENTITY",
"document_type": "PASSPORT",
"id": "9a92b3c5-e804-06bc-cccc-6b3b43ea2a7a",
"images": [
{
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"image_type": "FRONT",
"upload_date": "2019-10-08 14:20:02"
},
{
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"image_type": "FACE",
"upload_date": "2019-10-08 14:20:02"
}
]
],
"entity_type": "INDIVIDUAL",
"personal_details": {...}
}

The response returns everything in the profile's collected_data. The documents are returned in the documents object.

`document_images`

To get all document images from a profile, make the following request.

Request endpoint:

POST https://api.passfort.com/4.0/profiles/{profile_id}/document_images

Sample response:

{
{
"id": "ec1565b6-82c7-0577-8b3a-94462b67c97a",
"image_type": "FRONT",
"upload_date": "2019-10-08 14:20:02"
},
{
"id": "5562c4e4-4d12-b16a-a151-7c9eed6816e9",
"image_type": "FACE",
"upload_date": "2019-10-08 14:20:02"
}
}


How did we do?


Powered by HelpDocs (opens in a new tab)