External API

The Instant Trigger API lets an external system request that AgenticCX call a specific person right now, as part of a running outbound campaign. Where a Planned campaign's segment decides who gets called, an Instant campaign lets you decide, each request you send adds one person to that campaign's call pool.

What It Does

Accepting a request is not the same as starting a call. The endpoint queues the person and returns Queued; the call itself is placed by the campaign engine's own scheduler, typically within about 15 seconds. This is by design: call generation stays in one place, so call windows, retry limits, and concurrency limits apply the same way regardless of how a person entered the pool.

Typical use case: event driven scenarios such as "a customer submitted a form, call them right away" or "an order was cancelled, place a notification call."

Authentication

A client_credentials OAuth flow, audience AgenticCXExternal, role Customer.

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your client id>
&client_secret=<your secret>
&scope=AgenticCXExternal

Send the returned token as Authorization: Bearer <token> on every request. The scope parameter is required, if it is omitted the token is issued without an audience claim and every call fails with 401. Your tenant is resolved from the token itself, there is no tenant header or query parameter to send.

Endpoints

Base path: ext-api/v1

campaignId is the number shown as Campaign ID on the campaign detail screen. It never changes even if the campaign's name does, integrate against it, not the name. The </> button next to the copy button on that screen opens a window listing every one of these endpoints with a ready to run curl command (the token appears as a placeholder, never a real credential).

Submitting a Request

POST campaign/{campaignId}/call-requests accepts an items array (1 to 100 entries per call). Each item needs a clientReferenceId (your own key, up to 128 characters) and a contact.phoneNumber and contact.name; contact.email, locale, and up to 20 parameters key/value pairs are optional. The response is always 200, items are independent, each one carries its own result: Queued (accepted, call coming), Deferred (accepted but outside the call window), Merged (this person already had a call coming, the two requests combined), or Rejected (with a reason).

clientReferenceId is your idempotency key. Sending the same key twice never produces a second call, you get the first request's result back exactly. This makes it safe to resend an entire batch after a dropped connection without reconciling anything yourself.

Tracking and Listing

GET call-requests/{clientReferenceId} returns the full picture for one request: what you submitted, what AgenticCX decided, and what the call itself did (state, every attempt, its outcome). GET call-requests lists a campaign's request history with cursor based pagination, filterable by date range or call state. GET call-requests-summary returns the same filtering as counts, for a dashboard style view without paging through individual records.

Known Behaviors to Read Before Integrating

A campaign level rejection (campaign not found, not an Instant Trigger campaign, not active, or outside its date window) returns 422 for the entire request body, before any individual item is evaluated. A 422 should never be retried with a new clientReferenceId, that is the one scenario that can produce a duplicate call, resend with the same key once the underlying issue (such as a paused campaign) is resolved.