API Documentation
Integrate Gavel with your favorite apps and services. The API is available to users under the Enterprise plans.
General API
Authentication:
Authentication for all endpoints is done via X-Api-Key header:
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 Gavel 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%20Gavel%20Workflow/new HTTP/1.1
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY
Content-Type: application/json
Response:
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:
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:
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:
Note: This API overlaps with the Gavel Office add-in API, so it will also allow for additional data such as variable names for buttons and instruction blocks.