Gavel API Documentation

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

Open Settings > API Keys

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

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.

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.

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.

Variable type rules

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

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.

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.

string

required

The URL-encoded, case-sensitive name of the workflow.

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

array

An array of document objects for the session.

string

File format: docx or pdf.

string

The output file name.

string

The source template file name, or uploadedFile[n] for user-uploaded files.

string

Either outputDocument (a generated document) or fileUpload (a file the user attached during the workflow).

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.

string

required

The internal workflow ID (appears in the metadata response URL).

string

required

The session ID associated with the document.

integer

required

An internal number associated with the specific document.

string

required

The file name of the document.

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.

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.

Get Started

Questionnaire

Document Templates

Logic & Calculations

Sharing & Access

Integrations

Video Series

Support

Account Management

Gavel API Documentation

Authentication

Creating an API key

Endpoints

1. Create a workflow session with pre-filled data

Request body

Example request

Example response

2. Retrieve document metadata from a session

Example response

3. Download a document

4. List workflow names

Example response

5. List workflow variables

Example response

​Authentication

​Creating an API key

​Endpoints

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

​Request body

​Example request

​Example response

​2. Retrieve document metadata from a session

​Example response

​3. Download a document

​4. List workflow names

​Example response

​5. List workflow variables

​Example response

Authentication

Creating an API key

Endpoints

1. Create a workflow session with pre-filled data

Request body

Example request

Example response

2. Retrieve document metadata from a session

Example response

3. Download a document

4. List workflow names

Example response

5. List workflow variables

Example response