dograh/docs/voice-agent/api-trigger.mdx

---
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. You can find this UUID in the dashboard URL when viewing the agent, or in the trigger node settings.

Your trigger endpoint is:

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

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

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