The /public/agent/* routes require the X-API-Key header specifically — it is a required header on those operations, and a session bearer token will not authenticate them. See Authentication.

​
Choose the right public call route

Peachdesk exposes two public outbound call route families. They are not interchangeable, even though both path parameters look like UUIDs.
Do not pass a workflow UUID to /public/agent/{uuid} and do not pass a trigger UUID to /public/agent/workflow/{workflow_uuid}. Peachdesk treats these as different identifier types and the request will fail if you mix them up.
Once Peachdesk resolves the target agent, both route families behave the same:
  • They accept the same request body
  • They return the same response shape
  • They validate the same X-API-Key organization boundary
  • They use the same telephony configuration selection rules
If you specifically need the API Trigger route, see Trigger an outbound call by API Trigger node. To execute by workflow UUID, see Trigger an outbound call by workflow UUID.

​
Using initial context

initial_context passes runtime data into the agent at call time. Values are available as template variables in your agent’s prompt using double-brace syntax.
Your agent prompt can then reference {{customer_name}} and {{appointment_date}} and they will be substituted when the call starts.

​
Dynamic variables and metadata

Three fields carry per-call data, and they are not interchangeable: dynamic_variables is Retell’s retell_llm_dynamic_variables. It is merged on top of initial_context, so when the same key appears in both the value from dynamic_variables wins, and the merged set is what your prompt’s {{variables}} resolve against. metadata is an opaque object. It is stored on the run and returned verbatim as call.metadata on the call webhooks, so you can match a call to your own records. It is never rendered into the prompt — put values the agent should say or use in dynamic_variables, and values only your backend needs in metadata.

​
Caller ID selection

The number the recipient sees as the caller ID is chosen as follows:
  • If you pass from_number, that number is used. It must be an active outbound number your organization owns on the resolved telephony configuration, or the request is rejected with 400 from_number_not_found.
  • If you omit from_number, Peachdesk picks one automatically from the outbound numbers on that configuration, rotating across them so a single number is not used for every call. Numbers already on a live call are skipped. If every number is momentarily busy — or the selector is briefly unavailable — the call falls back to the configuration’s default caller ID rather than being delayed. A single API call is never blocked for this reason.
Rotation is scoped to one telephony configuration, because a number is rented from one provider. If your numbers are spread across more than one configuration, choose which set to draw from with telephony_configuration_id; otherwise your organization’s default configuration is used.

​
Run status values