Gavel API Documentation - Gavel

Gavel API Overview

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

Log in as a Builder or Admin
Sign in to your Gavel account with a Builder or Admin seat.
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.

Request

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

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.

Request

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

3. Download a document

Download the binary contents of a generated or uploaded document. You should use the url field returned by the Retrieve Document Metadata endpoint rather than constructing this URL manually.

Request

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

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

5. List workflow variables

Returns the variable schema for a specific workflow. Use this to understand what data to pass when creating a session.

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.