---
title: "API Trigger"
description: "Trigger outbound calls from external systems like n8n, Zapier, or your own backend"
---

The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Dograh generates a unique endpoint URL that external systems can call to start a conversation.

This is useful when you want to trigger calls from your own backend, a CRM, or workflow tools like n8n and Zapier.

## Prerequisites

- A configured [telephony provider](/integrations/telephony/overview) — outbound calls will fail without one
- An [API key](/configurations/api-keys) for authentication

## Finding your trigger URL

When you add an API Trigger node to your workflow, Dograh assigns it a unique UUID. The trigger node exposes two URLs that share this UUID — one for the published agent and one for the latest draft. You can copy either URL from the trigger node's settings dialog.

```
POST https://your-dograh-instance/api/v1/public/agent/{uuid}        # Production
POST https://your-dograh-instance/api/v1/public/agent/test/{uuid}   # Test
```

If you are using the hosted version, replace `your-dograh-instance` with `api.dograh.com`.

### Test vs production

| Mode       | URL                                | Runs                                                                      |
|------------|------------------------------------|---------------------------------------------------------------------------|
| Production | `/api/v1/public/agent/{uuid}`      | The published version of the agent.                                       |
| Test       | `/api/v1/public/agent/test/{uuid}` | The latest draft. Falls back to the published version if no draft exists. |

Use the test URL while iterating on changes so production traffic continues to hit the published version. Once you publish your draft, both URLs run the same definition.

The request body, headers, and response shape are identical for both URLs.

## Making a request

Authenticate by passing your API key in the `X-API-Key` header. The request body requires a `phone_number` and accepts an optional `initial_context` object.

```bash
curl -X POST https://your-dograh-instance/api/v1/public/agent/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'
```

### Response

A successful request returns a `workflow_run_id` that you can use to [retrieve call details](/api-reference/calls/get-run), recordings, and transcripts.

```json
{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}
```

### Error responses

| Status | Cause |
|---|---|
| `400` | Telephony provider not configured, or call failed to initiate |
| `401` | Missing or invalid API key |
| `403` | API key does not have access to this agent |
| `404` | Trigger not found or not active |

## Initial context

`initial_context` is a JSON object containing any information you want your voice agent to access during the call. You can reference these values in your prompts using [template variables](/voice-agent/template-variables) — values enclosed in `{{` and `}}`.

For example, if your request includes:
```json
{
    "phone_number": "+14155550100",
    "initial_context": {
        "user": {
            "name": "John"
        }
    }
}
```

You can reference the user's name in your prompt as `{{initial_context.user.name}}`.

See [Context & Variables](/core-concepts/context-and-variables) for more on how data flows through a call.

<Note>
For full endpoint details including all parameters and response fields, see the [API reference](/api-reference/calls/trigger).
</Note>