API Trigger

The API Trigger node lets you initiate outbound calls to your voice agent programmatically. When you add an API Trigger node to your workflow, Paladin 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 — outbound calls will fail without one
• An API key for authentication

Finding your trigger URL#

When you add an API Trigger node to your workflow, Paladin assigns it a unique UUID. The trigger node exposes two URLs that share this UUID:

• A production URL for the published workflow
• A test URL for the latest draft

You can copy either URL from the trigger node's settings dialog.

POST https://app.paladin.northmanngrp.com/api/v1/public/agent/{uuid}        # Production
POST https://app.paladin.northmanngrp.com/api/v1/public/agent/test/{uuid}   # Test

Use https://app.paladin.northmanngrp.com as your Paladin API base URL.

Test vs production#

Use the test URL while iterating on changes so production traffic continues to hit the published version.

The production URL only executes a published workflow. If you update the workflow but do not publish it, the production trigger will continue to run the older 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 optional initial_context and telephony_configuration_id fields.

curl -X POST https://app.paladin.northmanngrp.com/api/v1/public/agent/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

curl -X POST https://app.paladin.northmanngrp.com/api/v1/public/agent/test/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

Use the test URL when you want to verify draft changes before publishing.

Response#

A successful request returns a workflow_run_id that you can use to retrieve call details, recordings, and transcripts.

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

Error responses#

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 — values enclosed in {{ and }}.

For example, if your request includes:

{
    "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 for more on how data flows through a call.

Choosing a telephony configuration#

By default, calls are placed through your organization's default outbound telephony configuration. To route a specific call through a different configuration — for example, to dial out from a regional number — pass telephony_configuration_id in the request body.

{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42
}

The id is shown on each row in Telephony configurations. The configuration must belong to the same organization as the API Trigger; otherwise the request returns 404.