Documate is now Gavel! Read more about why we’re excited about this rebrand.

API and Other Integrations

Integrate Documate with your favorite apps and services. The API is available to users under the Enterprise plans.

General API

Authentication:

Authentication with the api is done via X-Api-Key header:

X-Api-Key:  <YOUR_DOCUMATE_API_KEY>
Create Workflow Session with Data:

Method: POST

Content-Type: application/json

Path: /api/documate/v1/interviews/<interview_name>/new 

Path Parameters:

interview_name: The url encoded, case sensitive name of the interview that we are creating a new session and inserting data into.

Request Body:

variables: a JSON object where the keys are variable names and the values are the values. All values of the object should be a string/number representing the variable they are setting with the exception of the following special variables/data types:

  • Date variables need to be in ISO8601 format.
  • Note: variables/parameters in the wrong format (e.g., dates in the wrong format) will be ignored.
  • Multi Select fields are arrays of strings matching the choices in your multi-select question.
  • Strings that do not match an option in the multi-select question will be ignored.
  • Repeating Items:
  • ~Repeating item values can be set as "itemname”: [{“attributename”: "item 1 attribute value"}, {“attributename”: “item 2 attribute value”}].
  • ~Optional repeating items with no items can be set as “itemname”: []
  • hsl_review_answers - Set this to true or use the "Skip the final review page" workflow setting to skip the “Please review your answers” page.
  • ~If all workflow variables are present in the request, the continuation_url will present the document download page.
  • ~If all workflow variables are not present in the request, the continuation_url will prompt for the missing data and skip the review page, directing to the document download page when missing values are entered.
  • ~Setting hsl_review_answers to true will switch on the "Skip the final review page" workflow setting and skip the final review page in all cases.
  • ~Note: We recommend using the "Skip the final review page" workflow setting instead of hsl_review_answers whenever possible.
Example:

For a workflow named: My Documate Workflow with the following data types for variables:

  • my_date_variable: Date
  • ~firstname: Text
  • ~lastname: Text
  • ~age: Number
  • my_repeating_item: Repeating Item
  • ~repeating_name: Text
  • ~repeating_age: Number
  • my_multi: Multi Select

POST /api/documate/v1/interviews/My%20Documate%20Workflow/new HTTP/1.1
Host: yourdomain.documate.org
X-Api-Key: YOUR_DOCUMATE_API_KEY
Content-Type: application/json  

{    
  "variables": {      
    "my_date_variable": "2021-05-01T23:02:02.098Z",      
    "firstname":  "John",           
    "lastname":  "Doe", 
    "age": 35
    "hsl_review_answers": true,
     "my_repeating_item": [
      {
        "repeating_name": "Item 1",
        "repeating_age": 1
      },
      {
        "repeating_name": "Item 2",
        "repeating_age": 2
      }
    ],
    "my_multi":["name of option", "name of other option"]
  }  
}
Response:
{      
    "continuation_url": "https://yourdomain.documate.org/run/playground6/My%20Documate%20Workflow/?session=TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a",
    "session_id": "TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a"  
}
Retrieve Document Metadata from an Existing Session

Method: GET

Path: api/documate/v1/data-manager/workflows/<workflow_name>/session/<session_id>/documents

Path Parameters:

  • workflow_name: The url encoded, case sensitive name of the workflow for which the requested session belongs
  • session_id: The id of the session for which to retrieve documents

Example Response:

{ "documents": [ { "format": "docx", "name": "output.docx", "template": "sample_output.docx", "type": "outputDocument", "url": "https://yourdomain.documate.org/api/documate/v1/data-manager/workflows/4/session/AD7xBNhgMZUK3QtxfwwjyM9OuhWHs7Tn/download-document?file_number=59&filename=output.docx&extension=docx" }, { "format": "pdf", "name": "output.pdf", "template": "sample_output.pdf", "type": "outputDocument", "url": "https://yourdomain.documate.org/api/documate/v1/data-manager/workflows/4/session/AD7xBNhgMZUK3QtxfwwjyM9OuhWHs7Tn/download-document?file_number=60&filename=output.pdf&extension=pdf" }, { "format": "pdf", "name": "user_upload.pdf", "template": "uploadedFile[0]", "type": "fileUpload", "url": "https://yourdomain.documate.org/api/documate/v1/data-manager/workflows/4/session/AD7xBNhgMZUK3QtxfwwjyM9OuhWHs7Tn/download-document?file_number=58&filename=user_upload.pdf&extension=pdf" } ] }
Download Document:

Note that this endpoint is primarily intended to be called in conjunction with api/documate/v1/data-manager/workflows/<workflow_name>/session/<session_id>/documents, using the url response. Builders should not need to manually construct the parameters.

Method: GET

Path: /data-manager/workflows/<workflow_id>/session/<session_id>/download-document?file_number=<file_number>&filename=<filename>&extension=<extension>

Path Parameters:

  • workflow_id: An internal id of the workflow for which the requested session belongs
  • session_id: The id of the session that the document is associated with

Query Parameters:

  • file_number: An internal number associated with the document
  • filename: The name of the file
  • extension: The extension of the file

Response:

The binary file contents.

List Workflow Names:

Method: GET

Path: /api/playground?folder=questions

Example Response:

[ "Continued.yml", "Divorce Workflow.yml", "Evictions.yml", "Express Workflow.yml" ]

List Workflow Variables:

Method: GET

Path: /officeaddin?pgtypes=<workflow name>.yml

Path Parameters:

pgtypes: name of the workflow returned from List Workflows endpoint.

Example Response:
{ "attachments": [], "success": true, "types_json": { "types_list": [ { "datatype": "text", "inputtype": "radio", "label": "Marital Status", "required": true, "selections": [ "Married", "Single" ], "variable": "marital_status" }, { "datatype": "text", "label": "My Text 2", "required": true, "variable": "my_text2" }, ] } }

Note: This API overlaps with the Documate Office add-in API, so it will also allow for additional data such as variable names for buttons and instruction blocks.