Work with files, documents, and document_images using the 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.Note
Files cannot be used to run checks.
documents: You can use these as input to run checks, for example, the Document verification or Company document verification check. When they are used as input to run checks, they're made up of one or moredocument_images.Documents can also be returned as output from checks, for example, 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, for example, an ID and the liveness video used to support it. They may also have additional metadata returned by the data provider, for example, an expiry date or the type of company financial report.
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}/filesBody parameters:
When you make the POST request, include the following parameters in the body:
Key | Value | Description |
*Required string | See the following sample request body for a sample value. | The image, encoded in Base64. Optionally, the Base64-encoded image can be a URI string. |
Optional string | Sample value: | 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
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.
To get a file from a profile, make the following request:
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:
Add the document images to the profile's
document_images.In the profile's
documentsarray of objects, create a new object to represent the document. Add the images fromdocument_imagesto the object when you create it.
When you add an image to a profile's document_images, there's no way to see it using the portal until you create the document object later.
Add the document_images to the profile
Each document_image is a single image encoded in Base64. 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.
For each request, take note of the image ID returned in the response. You'll need it to create the document object in Create the document object.
To add an image, make the following request:
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/document_imagesBody parameters:
When you make the request, include the following parameters in the body.
Key | Value | Description |
*Required string | See the following sample request body for a sample value. | The image, encoded in Base64. Optionally, the Base64-encoded image can be a URI string. |
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 |
If you do not send a value for this key, the value is set to | 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"
}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 section.
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/documentsThis 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 reference for Update collected data. Note that, unlike the main request to update collected_data, the previous request does not use ETags.
Body parameters:
When you make the request, include the following parameters in the body.
Key | Value | Description |
*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 relevant check type. | This field is used by the data provider to understand how to treat the document. |
*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 relevant check type. | The type of document you're creating, such as a passport, a driving license, and so on. |
*Required array of objects | See the following sample request body for a sample value. | Array of objects where each object corresponds to one image from the profile's |
*Required string | Sample value: | 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
Get documents from a profile
To get a document from a profile, make the following request.
Request endpoint:
POST https://api.passfort.com/4.0/profiles/{profile_id}/collected_dataSample 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.
Get document_images from a profile
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_imagesSample 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"
}
}