Add documents

Process Flow

To understand where adding documents fits into the workflow, please reference the full sequence diagram.

Base URL

The table below shows the Base URL to be used with the endpoints mentioned in this guide.

Environment	Base URL
Staging:	`https://api.staging.informediq-infra.com`
Production:	`https://api.informediq.com`

Full Example Request

Once the application has been registered, it is time to provide the supporting documents. The below code block shows a full example request payload for the call to associate documents with an application. The following sections provide details on the elements of the request payload.

{
  "image_files": [
    "file1.pdf",
    "file2.pdf",
    "file3.pdf"
  ]
}

Request Components

Endpoint

You will append the following endpoint to the base URL to associate documents with your application:

/v1/consumer/applications/<unique-Informed-app-id>/documents

tip

The <unique-Informed-app-id> needs to be the application_id described in the synchronous response section of the app registration guide.

So to put it all together, you will make a POST call to the following URL with a request payload similar to the one shown above:

https://api.staging.informediq-infra.com/v1/consumer/applications/<unique-Informed-app-id>/documents

If you later receive additional documents to associate with a particular application, you can repeat the process described in this guide to add those documents to that app.

Image files

The image_files section of the API request is where you will include the names of all the images that you want to send to Informed for this particular application.

The most common files types are supported:

PDF (paginated)
TIFF (paginated)
jpg (non-paginated)
png (non-paginated)

warning

Please note that within any single request, the image_files list must contain all unique filenames.

{
  "image_files": [
    "file1.pdf",
    "file2.pdf",
    "file3.pdf"
  ]
}

Synchronous Response

This is the synchronous response that can be expected from sending a documents request.

2xx response
Non-2xx responses

{
  "request_id": "Informed request Id",
  "image_files":
  [
    {
      "file_reference_id": "file1.pdf",
      "file_id": "InformedFileReferenceId1",
      "url": "https://informed-techno-core-<env>-uploads.s3.amazonaws.com/123...",
      "expiration": "timestamp"
    },
    {
      "file_reference_id": "file2.pdf",
      "file_id": "InformedFileReferenceId2",
      "url": "https://informed-techno-core-<env>-uploads.s3.amazonaws.com/123...",
      "expiration": "timestamp"
    },
    {
      "file_reference_id": "file3.pdf",
      "file_id": "InformedFileReferenceId3",
      "url": "https://informed-techno-core-<env>-uploads.s3.amazonaws.com/123...",
      "expiration": "timestamp"
    }
  ]
}

Status	Error Message
400	`Application does not exist` This would occur if the `application_id` used in the `POST` call URL did not exist in the system.
400	`Input files must be unique` All image file names in the `image_files` list in a given call must be unique file names.

Upload the Physical Files

Now that you have told Informed the file names of the images to be uploaded and Informed has provided the corresponding pre-signed URL's to use for each file by name, it is time to connect the two by making api calls to upload your physical files to the pre-signed URL's.

danger

There is no guarantee that the file upload URL's (typically AWS S3 pre-signed URL's) will remain exactly the same for all future time. Informed reserves the right to use whatever infrastructure is most secure and efficient.

If you are trying to whitelist the upload URL's, at the current time, as Amazon AWS pre-signed URL's, they will have a base domain of amazonaws.com, so the most restrictive that you should make your whitelist is *.amazonaws.com.

How you do this will depend somewhat on your own architecture and setup, but as a general rule of thumb, you can work backwards from something like this simple curl call:

curl --upload-file "~/pathTo/file1.pdf" "<provided pre-signed URL>"

info

Some partners have found that Postman introduces a problem when trying to do the PUT call to upload files to the supplied URL. Postman appears to merge form header information into the file data, thus "corrupting" the image header, causing the image processing to fail. We have not seen this issue with either curl or other programmatic networking libraries. If you have problems testing the Informed platform using Postman, please reach out to your Informed professional services rep.

You will need to loop through the items in the image_files node in the synchronous response and using the file_reference_id and associated url, upload the file to that URL using a PUT call.

warning

Image files should not exceed 80 MB in size for a single file. The image dimensions cannot be larger than 9000 by 9000 pixels, and the image width/height can not be smaller than 100 pixels.

Additionally, uploading a paginated image file with more than 150 pages in a single file, regardless of whether it falls under the 80 MB size limit or not, will result in degradation of service due to the way that the system processes at a page level.

Please note that the pre-signed AWS S3 URL's have some inherent security features based on AWS S3 and our platform:

WRITE-ONLY - they cannot be used to retrieve anything
WRITE-ONCE - they are one-time use only
They have an expiration of 1 hour

If you were to write the same file (or a different file) to the same URL prior to its expiration, you will not receive an error message. However, the platform will ignore all subsequent uploads to a given URL during its life time.

warning

Because the pre-signed URL's are one-time use only, if you were to mistakenly upload the wrong file to a pre-signed_URL, then you would need to repeat the process in order to receive a new pre-signed URL.

Ignore Files

Sometimes a file may be uploaded that you end up not wanting to include in the mix for verifications. We do not allow you to delete documents but we do allow you to "ignore" documents. Any document that has been ignored will not be considered when verifications are run.

Call to ignore

Follow the steps below to ignore a specific document.

Endpoint

Append the following endpoint to the base URL and do a PATCH call:

/v1/consumer/applications/<unique-Informed-app-id>/documents/<document id>/metadata

Body

The body of your PATCH call needs to be the following:

{
  "document_grouping": "ignored_docs"
}

Synchronous response

If your request was successful, you will receive a synchronous response like that shown below:

{
  "success": true,
  "request_id": "34814e79-0663-4296-87ba-cbcdc411ac78"
}

Extractions

You will also receive the normal asynchronous response for extractions for the file containing the ignored document.

Note the following highlighted lines in the example below:

the data_action is update instead of create
the metadata section has a document_grouping element now, showing that it is part of the ignored_docs group

{
  "event_type": "extractions",
  "application_id": "fd203541-dfbc-4276-af7f-0f57e986a373",
  "application_reference_id": "test-20250322-x1001",
  "documents": {
    "paystub": [
      {
        "data_action": "update",
        "document_id": "9fe1e436-d24c-47b9-9908-b09e2518e871",
        "document_label": "Paystub",
        "file_ids": [
          "e9efecd1-1b41-40fc-88aa-614f9c1927ed"
        ],
        "file_reference_ids": [
          "file1.pdf"
        ],
        "file_sources": [
          "api"
        ],
        "metadata": {
          "document_grouping": "ignored_docs",
          "document_id": "9fe1e436-d24c-47b9-9908-b09e2518e871"
        },
        "url": "https://informed-...",
        "extracted_data": {...},
        "updated_at": "2025-03-23T01:55:23Z"
      }
    ]
  }
}

Verifications

As always, when any document actions finish processing, verifications will be run against the aggregate of documents associated with the application. If the ignored document had been used to satisfy any verification, it will no longer be considered available to satisfy the verification. Unless there is another satisfactory document to satisfy that verification, the status of the verification will change to missing.

Call to un-ignore

If for some reason you later change your mind and want to include a previously ignored document in the mix for verifications, you can un-ignore the document by following the steps below.

Endpoint

Append the following endpoint to the base URL and do a PATCH call:

/v1/consumer/applications/<unique-Informed-app-id>/documents/<document id>/metadata

Body

The body of your PATCH call needs to be the following:

{
  "document_grouping": ""
}

Synchronous response

If your request was successful, you will receive a synchronous response like that shown below:

{
  "success": true,
  "request_id": "34814e79-0663-4296-87ba-cbcdc411ac78"
}

Extractions

You will also receive the normal asynchronous response for extractions for the file containing the now un-ignored document.

Note the following highlighted lines in the example below:

the data_action is once again update instead of create
the metadata section still has a document_grouping element, but now its value is an empty string, showing that it is no longer part of the ignored_docs group

{
  "event_type": "extractions",
  "application_id": "fd203541-dfbc-4276-af7f-0f57e986a373",
  "application_reference_id": "test-20250322-x1001",
  "documents": {
    "paystub": [
      {
        "data_action": "update",
        "document_id": "9fe1e436-d24c-47b9-9908-b09e2518e871",
        "document_label": "Paystub",
        "file_ids": [
          "e9efecd1-1b41-40fc-88aa-614f9c1927ed"
        ],
        "file_reference_ids": [
          "file1.pdf"
        ],
        "file_sources": [
          "api"
        ],
        "metadata": {
          "document_grouping": "",
          "document_id": "9fe1e436-d24c-47b9-9908-b09e2518e871"
        },
        "url": "https://informed-...",
        "extracted_data": {...},
        "updated_at": "2025-03-23T01:55:23Z"
      }
    ]
  }
}

Verifications

As always, when any document actions finish processing, verifications will be run against the aggregate of documents associated with the application. The previously ignored document will now be considered available to satisfy any relevant verification.

Process Flow​

Base URL​

Full Example Request​

Request Components​

Endpoint​

Image files​

Synchronous Response​

Upload the Physical Files​

Ignore Files​

Call to ignore​

Endpoint​

Body​

Synchronous response​

Extractions​

Verifications​

Call to un-ignore​

Endpoint​

Body​

Synchronous response​

Extractions​

Verifications​

Process Flow

Base URL

Full Example Request

Request Components

Endpoint

Image files

Synchronous Response

Upload the Physical Files

Ignore Files

Call to ignore

Endpoint

Body

Synchronous response

Extractions

Verifications

Call to un-ignore

Endpoint

Body

Synchronous response

Extractions

Verifications