> ## Documentation Index
> Fetch the complete documentation index at: https://helpdocs.gavel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gavel API Documentation

> Use the Gavel API to create workflow sessions with pre-filled data, retrieve generated documents, and list workflow metadata programmatically.

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**.

<Note>
  You need a Gavel API key to authenticate every request. See [Creating an API key](#creating-an-api-key) below.
</Note>

## 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.

```http theme={null}
X-Api-Key: YOUR_GAVEL_API_KEY
```

Your base URL is your Gavel subdomain: `https://yourdomain.gavel.io`.

***

## Creating an API key

<Steps>
  <Step title="Log in as a Builder or Admin">
    Sign in to your Gavel account with a Builder or Admin seat.
  </Step>

  <Step title="Open Settings > API Keys">
    In the left sidebar, click **Settings**, then select **API Keys**.
  </Step>

  <Step title="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.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.

<ParamField path="interview_name" type="string" required>
  The URL-encoded, case-sensitive name of the workflow. For example, `My%20Gavel%20Workflow`.
</ParamField>

```http theme={null}
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.

<AccordionGroup>
  <Accordion title="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}`.
  </Accordion>
</AccordionGroup>

#### Example request

The example below shows a workflow named **My Gavel Workflow** with every supported variable type.

```json theme={null}
{
  "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

```json theme={null}
{
  "continuation_url": "https://yourdomain.gavel.io/run/playground6/My%20Gavel%20Workflow/?session=TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a",
  "session_id": "TerMtx6W3o4xhhEq76MqaKL5t2FQcJ2a"
}
```

<ResponseField name="continuation_url" type="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.
</ResponseField>

<ResponseField name="session_id" type="string">
  The unique identifier for the session. Use this to retrieve documents after the session is complete.
</ResponseField>

***

### 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.

<ParamField path="workflow_name" type="string" required>
  The URL-encoded, case-sensitive name of the workflow.
</ParamField>

<ParamField path="session_id" type="string" required>
  The session ID returned by the Create Workflow Session endpoint.
</ParamField>

```http theme={null}
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

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="documents" type="array">
  An array of document objects for the session.
</ResponseField>

<ResponseField name="documents[].format" type="string">
  File format: `docx` or `pdf`.
</ResponseField>

<ResponseField name="documents[].name" type="string">
  The output file name.
</ResponseField>

<ResponseField name="documents[].template" type="string">
  The source template file name, or `uploadedFile[n]` for user-uploaded files.
</ResponseField>

<ResponseField name="documents[].type" type="string">
  Either `outputDocument` (a generated document) or `fileUpload` (a file the user attached during the workflow).
</ResponseField>

<ResponseField name="documents[].url" type="string">
  The URL to download this document binary. Pass this to the Download Document endpoint.
</ResponseField>

***

### 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.

<ParamField path="workflow_id" type="string" required>
  The internal workflow ID (appears in the metadata response URL).
</ParamField>

<ParamField path="session_id" type="string" required>
  The session ID associated with the document.
</ParamField>

<ParamField query="file_number" type="integer" required>
  An internal number associated with the specific document.
</ParamField>

<ParamField query="filename" type="string" required>
  The file name of the document.
</ParamField>

<ParamField query="extension" type="string" required>
  The file extension (e.g. `docx`, `pdf`).
</ParamField>

```http theme={null}
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.

<Tip>
  Construct this request by copying the `url` from the documents metadata response. You do not need to assemble the query parameters by hand.
</Tip>

***

### 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.

```http theme={null}
GET /api/playground?folder=questions
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY
```

#### Example response

```json theme={null}
[
  "Continued.yml",
  "Divorce Workflow.yml",
  "Evictions.yml",
  "Express Workflow.yml"
]
```

<Note>
  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.
</Note>

***

### 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.

<ParamField query="pgtypes" type="string" required>
  The workflow name as returned by the List Workflow Names endpoint, including the `.yml` extension. Example: `Divorce Workflow.yml`.
</ParamField>

```http theme={null}
GET /officeaddin?pgtypes={workflow_name}.yml
Host: yourdomain.gavel.io
X-Api-Key: YOUR_GAVEL_API_KEY
```

#### Example response

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

<Info>
  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.
</Info>