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

# n8n integration

> Automate your pre-sales pipeline with n8n workflows that connect to the Quikly REST API.

[n8n](https://n8n.io) is an open-source workflow automation platform. You can use it to build no-code automations that create proposals from incoming leads, notify you when clients respond, or sync Quikly data with your CRM.

## Set up your API key in n8n

<Steps>
  <Step title="Create an API key in Quikly">
    Go to **Settings → API Keys** and create a key with `read,write` scope. Copy the full key.
  </Step>

  <Step title="Add an HTTP Request node in n8n">
    In your n8n workflow, add an **HTTP Request** node.
  </Step>

  <Step title="Configure authentication">
    Set the authentication to **Generic Credential Type → Header Auth**:

    * **Name**: `X-API-Key`
    * **Value**: `qk_your_api_key_here`
  </Step>

  <Step title="Set the base URL">
    Use `https://api.getquikly.com/api/external/v1` as the base URL for all requests.
  </Step>
</Steps>

<Tip>
  Create a reusable Header Auth credential in n8n so you don't have to enter your API key in every node.
</Tip>

## Workflow templates

Quikly provides ready-made workflow templates that you can import into n8n.

### Lead to proposal

This workflow turns a form submission or webhook trigger into a Quikly proposal:

1. **Webhook trigger** — receives lead data (name, email, project description)
2. **Analyze brief** — calls `POST /ai/analyze-brief` to extract structured requirements
3. **Get rate recommendation** — calls `POST /ai/rate-recommendation` for market-calibrated pricing
4. **Create proposal** — calls `POST /proposals` with the requirements and rate
5. **Share proposal** — calls `POST /proposals/{id}/share` to generate a client link
6. **Send notification** — emails you the share link or posts to Slack

```json Example: Analyze brief node theme={null}
{
  "method": "POST",
  "url": "https://api.getquikly.com/api/external/v1/ai/analyze-brief",
  "headers": {
    "X-API-Key": "qk_your_api_key_here",
    "Content-Type": "application/json"
  },
  "body": {
    "brief": "{{ $json.projectDescription }}",
    "language": "en"
  }
}
```

### Telegram to proposal

This workflow receives messages from a Telegram bot and creates proposals through the Quikly Agent Mode:

1. **Telegram trigger** — receives messages from your BotFather bot
2. **Create or resume lead session** — calls `POST /lead-sessions` or `PATCH /lead-sessions/{id}`
3. **Agent chat** — calls `POST /agent/chat` to run the conversational proposal flow
4. **Reply to Telegram** — sends the agent's response back to the chat
5. **On proposal ready** — receives a webhook callback and sends the share link to Telegram

### Proposal status watcher

A polling workflow that checks for client responses:

1. **Schedule trigger** — runs every 15 minutes
2. **List proposals** — calls `GET /proposals?status=sent` to find shared proposals
3. **Check status** — calls `GET /proposals/{id}/status` for each
4. **Filter changes** — compares with previous run to detect new responses
5. **Notify** — sends a Slack message or email when a client accepts, rejects, or requests revisions

## Webhook triggers in n8n

Instead of polling, you can use Quikly webhooks to trigger n8n workflows instantly:

<Steps>
  <Step title="Create an n8n webhook node">
    Add a **Webhook** node in n8n. Copy the generated URL (e.g., `https://your-n8n.com/webhook/abc123`).
  </Step>

  <Step title="Register the webhook in Quikly">
    Call `POST /webhooks` with the n8n URL and the events you want to listen to.
  </Step>

  <Step title="Process the payload">
    The webhook node receives the Quikly event payload. Use it to trigger downstream actions.
  </Step>
</Steps>

```json Example: Register webhook for client responses theme={null}
{
  "name": "n8n - Client responses",
  "url": "https://your-n8n.com/webhook/abc123",
  "events": [
    "proposal.accepted",
    "proposal.rejected",
    "proposal.revision_requested"
  ]
}
```

## Common API calls for n8n

| Action                    | Method | Endpoint                                    |
| ------------------------- | ------ | ------------------------------------------- |
| List proposals            | `GET`  | `/proposals`                                |
| Create proposal           | `POST` | `/proposals`                                |
| Get proposal status       | `GET`  | `/proposals/{id}/status`                    |
| Analyze a brief           | `POST` | `/ai/analyze-brief`                         |
| Get rate recommendation   | `POST` | `/ai/rate-recommendation`                   |
| Share with client         | `POST` | `/proposals/{id}/share`                     |
| Get your rate params      | `GET`  | `/ai/rate-params`                           |
| Check quota before acting | `GET`  | `/usage/precheck?operation=proposal_create` |
| Create lead session       | `POST` | `/lead-sessions`                            |
| Agent chat turn           | `POST` | `/agent/chat`                               |

<Note>
  All endpoints use the base URL `https://api.getquikly.com/api/external/v1`. See the [API reference](/api-reference) for full request and response schemas.
</Note>