Submit a ticket My Tickets
Welcome
Login  Sign up

Document Upload via API

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


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. 


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



J
Jason is the author of this solution article.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.