## 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](https://helpdocs.gavel.io/workflows/api#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.

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