The API documentation for this process can be found here.
Step 1 - Document Description
In this step, we're informing the Alloy API that we're going to be uploading an image. In return, the Alloy API is responding with a token that we can use to later identify the image in the Alloy environment.
A POST request will be sent to the /entities/<entity_token>/documents endpoint with the following body structure:
{ "name": "driver_license", "extension": "pdf", "type": "license", "note": "Uploaded from email customer sent", "note_author_agent_email": "john.doe@example.com" }
"name" : The name of the file itself.
"extension" : The filetype
"type" : The 'type' of document. Allowed types are [contract, license, passport, utility, other, internal]
"note": A space for notes on the document itself.
"note_author_agent_email": The email address of the agent making the note (this email must correlate with an Alloy account).
Once this request is successfully made, the response will look like this:
{ "document_token": "D-fu1WeoS2ywAROk1srtP9", "type": "license", "name": "driver_license", "extension": "pdf", "uploaded": false, "timestamp": 1497305164671, "approved": null, "approval_agent_email": null, "approval_timestamp": null, "notes": [ "note": "Uploaded from email customer sent", "note_author_agent_email": "john.doe@example.com", "created_at": 1497305164671, "updated_at": 1497305164671 ] }
The "document_token" from this response will be used in the followup call to upload the document itself to Alloy.
Step 2 - Document Upload
A PUT request will be sent to /entities/<entity_token>/documents/<document_token> in order to upload the file itself to the API. The request needs to contain the file-stream. To do so, a header of:
{"content-type" : "application/octet-stream"}
must be passed with the image attached as a binary attachment.
The response to the PUT request will be identical to the response from the previous POST with one primary difference; the "uploaded" field will now be true.
{ "document_token": "D-fu1WeoS2ywAROk1srtP9", "type": "license", "name": "driver_license", "extension": "pdf", "uploaded": true, "timestamp": 1497305164671, "approved": null, "approval_agent_email": null, "approval_timestamp": null, "notes": [ "note": "Uploaded from email customer sent", "note_author_agent_email": "john.doe@example.com", "created_at": 1497305164671, "updated_at": 1497305164671 ] }
Your document will now be viewable in the Alloy dashboard.
A GET request to /entities/<entity_token>/documents/<document_token> will allow you to download the document itself.
A GET request to /entities/<entity_token>/documents will return a list of all documents attached to an entity. The response body is formatted as follows:
[ { "document_token": "D-nqMK4l4Ppxs3QaEEZVTL", "type": "license", "name": "John_license", "extension": "jpg", "uploaded": true, "timestamp": 1497294976617, "approved": null, "approval_agent_email": null, "approval_timestamp": null, "notes": [ { "note": "Uploaded via web interface", "note_author_agent_email": "john.doe@example.com", "created_at": 1497294986800, "updated_at": 1497294986800 } ] }, { "document_token": "D-kn8sXlOgcEwTuUi5HVEU", "type": "utility", "name": "John_utility_bill", "extension": "pdf", "uploaded": true, "timestamp": 1497294520121, "approved": true, "approval_agent_email": "john.doe@example.com", "approval_timestamp": 1497294656014, "notes": [ { "note": "Uploaded from email with customer", "note_author_agent_email": "john.doe@example.com", "created_at": 1497294656014, "updated_at": 1497294656014 }, { "note": "I've reviewed and approved this document", "note_author_agent_email": "john.doe@example.com", "created_at": 1497294664571, "updated_at": 1497294664571 } ] } ]