What are files, documents, and document

What are `files`, `documents`, and `document_images` in 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 more document_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}/files

Body parameters:

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

Key

Value

Description

data

*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.

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

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 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 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 the next section.

To add an image, make the following request:

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 following sample request body 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"
}

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 previous request 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 relevant 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 relevant check type.	The type of document you're creating (e.g. a passport, a driving license, etc).
`images` *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 `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"
    }
}

In this section:

Using Passfort