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. 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
}
]
}
]