Skip to main content
The Gavel API lets you integrate Gavel document automation into your own applications and systems. You can pre-populate workflow sessions with client data, retrieve the documents Gavel generates, and inspect the variable schema for any workflow — all without a user ever opening the questionnaire manually. The API is available to customers on Scale plans.
You need a Gavel API key to authenticate every request. See Creating an API key below.

​
Authentication

All API endpoints authenticate via the X-Api-Key request header. Pass your Gavel API key as the value of this header on every request. 
X-Api-Key: YOUR_GAVEL_API_KEY
Your base URL is your Gavel subdomain: https://yourdomain.gavel.io.

​
Creating an API key

1

Log in as a Builder or Admin

Sign in to your Gavel account with a Builder or Admin seat.
2

Open Settings > API Keys

In the left sidebar, click Settings, then select API Keys.
3

Create and copy the key

Enter a name for the key (for your reference only), click Create a Key, and immediately copy the value shown.
Gavel does not let you retrieve an API key after you leave the page. Store the key somewhere secure — such as a password manager or secrets manager — before navigating away.
4

Use the key

Paste the key into the X-Api-Key header of your API requests, or use it to connect the Word add-in or Zapier integration.

​
Endpoints

​
1. Create a workflow session with pre-filled data

Use this endpoint to create a new session for a workflow and populate it with data from your system. When all variables are provided, the returned continuation_url takes the user directly to the document download page. When some variables are missing, Gavel prompts the user only for the missing answers before generating documents.
​
interview_name
string
required
The URL-encoded, case-sensitive name of the workflow. For example, My%20Gavel%20Workflow.
POST /api/documate/v1/interviews/{interview_name}/new
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY
Content-Type: application/json

​
Request body

The body contains a single variables object. Keys are variable names; values are the data to pre-fill.
  • Text / Number: Pass a plain string or number.
  • Date: Use the format "2024-05-30T" (ISO 8601 date with a trailing T).
  • Date Time: Use full ISO 8601 format, e.g. "2021-05-01T23:02:02.098Z".
  • Multi Select: Pass an array of strings matching the exact option labels in your question. Strings that do not match an option are ignored.
  • Repeating Items: Pass an array of objects, one per row. Each object’s keys are the attribute variable names for that repeating item. Optional repeating items with no rows can be set to [].
  • Nested Repeating Items: Gavel supports one level of nesting. Add the nested repeating item as a key inside each parent repeating item object, using the same array-of-objects format.
  • hsl_review_answers: Set to true to skip the final “Please review your answers” page. Gavel recommends using the Skip the final review page workflow setting instead whenever possible.
  • Invisible Logic variables: You can post data into Invisible Logic variables by referencing them in single curly brackets inside your workflow, e.g. {clientnumber}.

​
Example request

The example below shows a workflow named My Gavel Workflow with every supported variable type. 
{
  "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"
    ]
  }
}

​
Example response

{
  "continuation_url": "https://yourdomain.gavel.io/run/playground6/My%20Gavel%20Workflow/?session=TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a",
  "session_id": "TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a"
}
​
continuation_url
string
A URL you can redirect the user to. If all variables were supplied, this lands on the document download page. If variables are missing, the user is prompted to fill in only the missing answers.
​
session_id
string
The unique identifier for the session. Use this to retrieve documents after the session is complete.

​
2. Retrieve document metadata from a session

After a workflow session is complete, use this endpoint to get metadata — name, format, type, and download URL — for every document associated with the session.
​
workflow_name
string
required
The URL-encoded, case-sensitive name of the workflow.
​
session_id
string
required
The session ID returned by the Create Workflow Session endpoint.
GET /api/documate/v1/data-manager/workflows/{workflow_name}/session/{session_id}/documents
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY

​
Example response

{
  "documents": [
    {
      "format": "docx",
      "name": "output.docx",
      "template": "sample_output.docx",
      "type": "outputDocument",
      "url": "https://yourdomain.gavel.io/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.gavel.io/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.gavel.io/api/documate/v1/data-manager/workflows/4/session/AD7xBNhgMZUK3QtxfwwjyM9OuhWHs7Tn/download-document?file_number=58&filename=user_upload.pdf&extension=pdf"
    }
  ]
}
​
documents
array
An array of document objects for the session.
​
documents[].format
string
File format: docx or pdf.
​
documents[].name
string
The output file name.
​
documents[].template
string
The source template file name, or uploadedFile[n] for user-uploaded files.
​
documents[].type
string
Either outputDocument (a generated document) or fileUpload (a file the user attached during the workflow).
​
documents[].url
string
The URL to download this document binary. Pass this to the Download Document endpoint.

​
3. Download a document

Download the binary contents of a generated or uploaded document. In practice, you should use the url field returned by the Retrieve Document Metadata endpoint rather than constructing this URL manually.
​
workflow_id
string
required
The internal workflow ID (appears in the metadata response URL).
​
session_id
string
required
The session ID associated with the document.
​
file_number
integer
required
An internal number associated with the specific document.
​
filename
string
required
The file name of the document.
​
extension
string
required
The file extension (e.g. docx, pdf).
GET /data-manager/workflows/{workflow_id}/session/{session_id}/download-document?file_number={file_number}&filename={filename}&extension={extension}
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY
Response: The raw binary file contents of the document.
Construct this request by copying the url from the documents metadata response. You do not need to assemble the query parameters by hand.

​
4. List workflow names

Returns an array of all workflow names available on your account. Use these names to construct paths for the other endpoints. 
GET /api/playground?folder=questions
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY

​
Example response

[
  "Continued.yml",
  "Divorce Workflow.yml",
  "Evictions.yml",
  "Express Workflow.yml"
]
The names returned include the .yml extension. Use the full string (e.g. Divorce Workflow.yml) as the pgtypes parameter in the List Workflow Variables endpoint.

​
5. List workflow variables

Returns the variable schema for a specific workflow — including each variable’s name, data type, input type, label, and whether it is required. Use this to understand what data to pass when creating a session.
​
pgtypes
string
required
The workflow name as returned by the List Workflow Names endpoint, including the .yml extension. Example: Divorce Workflow.yml.
GET /officeaddin?pgtypes={workflow_name}.yml
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY

​
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"
      }
    ]
  }
}
This endpoint also powers the Gavel Word add-in. The response may include additional metadata for button and instruction block elements used in the add-in, which you can safely ignore when building integrations.