Skip to main content

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.

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

{
  "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"
    }
  ]
}

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.