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

# Introduction

> Everything you need to start using the DocsAutomator API

The DocsAutomator API lets you generate documents programmatically, manage automations, and control e-signature workflows. Use it to integrate document generation into any application.

<Info>
  The API works with both **Google Doc** and **PDF template** automations. The same `POST /createDocument` endpoint generates documents from either template type -- the automation's configuration determines the output.
</Info>

## Base URL

```
https://api.docsautomator.co
```

## Authentication

All API requests require authentication. Pass your API key using either method:

```bash theme={null}
# Bearer token (recommended)
Authorization: Bearer YOUR_API_KEY

# Alternative header
X-API-Key: YOUR_API_KEY
```

<Info>
  Find your API key at [app.docsautomator.co/settings/workspace/api](https://app.docsautomator.co/settings/workspace/api). API keys are scoped to a workspace.
</Info>

## Quick Start

Create your first document in three steps:

<Steps>
  <Step title="Get your API key">
    Go to **Settings > Workspace > API** in the DocsAutomator app.
  </Step>

  <Step title="Get your automation ID">
    Find the automation ID on the automation's settings page, or call `GET /automations` to list all automations.
  </Step>

  <Step title="Create a document">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.docsautomator.co/createDocument \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "docId": "YOUR_AUTOMATION_ID",
          "data": {
            "customer_name": "Acme Corp",
            "invoice_date": "2025-01-15",
            "total": "$1,500.00"
          }
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch("https://api.docsautomator.co/createDocument", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          docId: "YOUR_AUTOMATION_ID",
          data: {
            customer_name: "Acme Corp",
            invoice_date: "2025-01-15",
            total: "$1,500.00",
          },
        }),
      });

      const result = await response.json();
      console.log(result.pdfUrl);
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://api.docsautomator.co/createDocument",
          headers={
              "Authorization": "Bearer YOUR_API_KEY",
              "Content-Type": "application/json",
          },
          json={
              "docId": "YOUR_AUTOMATION_ID",
              "data": {
                  "customer_name": "Acme Corp",
                  "invoice_date": "2025-01-15",
                  "total": "$1,500.00",
              },
          },
      )

      result = response.json()
      print(result["pdfUrl"])
      ```
    </CodeGroup>
  </Step>
</Steps>

## Sync vs Async Mode

By default, `POST /createDocument` runs synchronously and waits for the document to be generated (up to 5 minutes). For high-volume or latency-sensitive workflows, use **async mode**.

### Sync mode (default)

```json theme={null}
{
  "docId": "abc123",
  "data": { "name": "Acme Corp" }
}
```

Returns `200` with the PDF URL when complete.

### Async mode

```json theme={null}
{
  "docId": "abc123",
  "async": true,
  "data": { "name": "Acme Corp" }
}
```

Returns `202` with a `jobId` immediately. Poll `GET /job/{jobId}` for the result:

```bash theme={null}
curl https://api.docsautomator.co/job/YOUR_JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Polling pattern:** Use exponential backoff starting at 2 seconds. Jobs typically complete in 5-30 seconds.

## Data Source Guides

The `POST /createDocument` endpoint works differently depending on your automation's data source. See the guide for your data source:

<CardGroup cols={2}>
  <Card title="API" href="/api-reference/documents/create-from-api">
    Pass data directly — most flexible option
  </Card>

  <Card title="Airtable" href="/api-reference/documents/create-from-airtable">
    Pass a record ID
  </Card>

  <Card title="Google Sheets" href="/api-reference/documents/create-from-google-sheets">
    Pass a row number
  </Card>

  <Card title="SmartSuite" href="/api-reference/documents/create-from-smartsuite">
    Pass a record ID
  </Card>

  <Card title="ClickUp" href="/api-reference/documents/create-from-clickup">
    Pass a task ID
  </Card>
</CardGroup>

## Rate Limits

| Scope             | Limit                                    |
| ----------------- | ---------------------------------------- |
| Global            | 2000 requests per 15 minutes per API key |
| Test email        | 25 per hour per automation               |
| Queue concurrency | Max 5 active jobs per workspace          |

When you exceed a rate limit, the API returns `429 Too Many Requests`.

## Error Codes

| Code  | Description                                                 |
| ----- | ----------------------------------------------------------- |
| `400` | Bad request — missing or invalid parameters                 |
| `401` | Unauthorized — incorrect or missing API key                 |
| `402` | Payment required — document limit exceeded                  |
| `404` | Not found — automation, template, or resource doesn't exist |
| `429` | Rate limited — too many requests                            |
| `500` | Server error — try again or contact support                 |

### Common 401 Causes

* Missing `Authorization` or `X-API-Key` header
* Incorrect API key
* Expired Google refresh token (reconnect Google account in the app)

### Common 404 Causes

* Automation ID doesn't exist or belongs to another workspace
* No template configured on the automation
* Automation is inactive (set `isActive: true` via the API or app)

## Webhooks

Configure a webhook URL on your automation to receive notifications after document generation. The webhook receives a POST request with:

```json theme={null}
{
  "message": "success",
  "pdfUrl": "https://...",
  "googleDocUrl": "https://...",
  "webhookParams": { "orderId": "ORD-123", "recId": "recAbC123XyZ" },
  "additionalParams": { "orderId": "ORD-123", "recId": "recAbC123XyZ" }
}
```

Pass custom data through to webhooks using `webhookParams` in your `createDocument` request. It is returned under both `webhookParams` and `additionalParams` (identical content; the latter is kept for backward compatibility), together with the automatically included trigger record identifier — `recId` (Airtable, SmartSuite, Notion), `taskId` (ClickUp), or `rowNumber` (Google Sheets). Your own keys are never overwritten.

## E-Signatures

When an automation has e-signatures enabled and the template contains e-sign placeholders (`{{esign.signature_1}}`, `{{esign.date_1}}`, etc.), creating a document automatically starts a signing workflow. The response includes the signing session ID and signing links.

See the [E-Signatures](/api-reference/e-signatures) endpoints for managing signing sessions programmatically, or the [eSign guide](/features/docsautomator-esign) for setup instructions.

<Info>
  Each endpoint in the API Reference section includes an interactive API playground where you can test requests directly from the docs. Navigate to any endpoint page and look for the "Try it" panel on the right side.
</Info>

## Need Help?

<CardGroup cols={2}>
  <Card title="In-App Chat" icon="comments">
    Contact support via the in-app chat
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@docsautomator.co">
    [support@docsautomator.co](mailto:support@docsautomator.co)
  </Card>
</CardGroup>