Skip to main content

Guide - Push / Pull Documents

Objective​

There is a mechanism for you to (a) consume documents which originate from the Incentify system (ie; "customer uploads") and (b) send documents to Incentify which originate from your internal system (ie; "internal team uploads"). Documents which originated from the Incenitfy system have passed a virus scan before they are made available over the API for you to consume.

Senario 1: Download a Document which Originated on Incentify​

First, you would need to consume a Document over the Incentify API which has no internal ID set (ie; has not been mapped to a document in your internal system since it does not yet exist there). This would most likely via the Delta mechanism in which you'd receive a Delta informing you a Document was added. You would then need to "consume" this document resource by requesting it from the Document endpoint, creating a corresponding "Document" on your internal system, and then associating your internal ID of that Document with the Incentify Document ID. To learn about the Delta mechanism, please refer to Guide - Syncing Changed Resources.

Now that you've synced document records Incentify is aware of the internal ID from your system for this document, so you can issue a GET - Download Link . Please note, while it is technically possible to call this endpoint with an Incentify ID, we strongly recommend creating a resource on your internal system, and associating the ID generated by you in your internal system with the Incentify ID.

This returns a single-use, Signed S3 URL which you may use to download the file onto your internal file system. File names are stored in Incentify's internal file system as a random hex hash, however you may wish to rename the downloaded file to match with the file name on the document resource, rather than the file name used on the Incentify block storage engine. This distinction may not matter for your internal file system so we leave the choice to you. Please note, if a user uploads a document from an incompatable file system (for example Windows vs *nix), the source file name may not be usable. However, the generated hex hash file name is compatable with all filesystems.

Senario 2: Upload Document which Originated on Your Internal System​

First, you would need to issue a POST - Upload Create . This is a mechanism for you to (a) tell Incentify the file extension you wish to upload and (b) get back in the response a signed S3 url which you can use to POST the binary file contents to in order to transmit the actual binary file. This upload POST response includes an upload_url (the signed S3 url to uplaod the file to) and the upload_id (which you will reference when you later create the document resource).

After successful upload of a file for a given upload ID/URL pair you would now issue a POST - Create Document with the document details, what the document is attached to, and most importantly, the upload_id from the previous step.