API Documentation
Integrate Gavel with your favorite apps and services. The API is available to users under the Scale 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 Time variables must be in ISO8601 format
- Date variables in this format: "2024-05-30T"
- ~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”: []
- Nested Repeating Items We support one level of nesting repeating items. A nested repeating item and its values can be set the same way as the repeating item value while referencing the repeating item it is nested under.
- 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.
- Invisible Logic:
- ~You are able to Post data into Invisible Logic Variables by creating a New Variable and having the data set variable in single curly brackets; e.g. {clientnumber}
Example:
For a workflow named: My Gavel Workflow with the following data types for variables:
- my_date_variable: Date
- my_datetime_variable: Date Time
- ~firstname: Text
- ~lastname: Text
- ~age: Number
- my_repeating_item: Repeating Item
- ~repeating_name: Text
- ~repeating_age: Number
- my_nested_repeating_item: Nested Repeating Item
- ~nested_repeating_name: Text
- ~nested_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
{
"variables": {
"my_date_variable": "2021-05-01T",
"my_datetime_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,
"my_nested_repeating_item": [
{
"nested_repeating_name": "Item 1's Nested Item 1",
"nested_repeating_age": 10
},
{
"nested_repeating_name": "Item 1's Nested Item 2",
"nested_repeating_age": 20
}
]
},
{
"repeating_name": "Item 2",
"repeating_age": 2,
"my_nested_repeating_item": [
{
"nested_repeating_name": "Item 2's Nested Item 1",
"nested_repeating_age": 30
},
{
"nested_repeating_name": "Item 2's Nested Item 2",
"nested_repeating_age": 40
}
]
}
]
"my_multi":["name of option", "name of other option"]
}
}
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.
