202 Accepted — you receive a call_event_id that you can use to poll for the call object and its analysis once processing is complete.
This endpoint requires a write-enabled API key. Requests made with a read-only key will receive a
403 Forbidden response.Endpoint
Request Body
The request body must be a JSON object conforming toCreateCallDto. The following fields are required on every submission.
Required Fields
string
required
Your system’s unique external identifier for this recording. Shilo stores this as
external_recording_id on the Call object and you can use it later to retrieve the call via external_recording_id:{value}.string
required
A publicly accessible URL pointing to the audio file for this call. Shilo’s servers must be able to fetch this URL without authentication. Supported formats include MP3, WAV, M4A, and OGG.
number
required
Total length of the call in seconds. This value is stored on the call and used to contextualize AI analysis outputs.
string
required
The analysis category that determines which AI coaching rubric is applied to this call (e.g.
"sales"). Contact your Shilo account team to confirm the categories available for your organization.string
required
Your system’s unique identifier for the agent on this call. Shilo uses this to match the call to an existing Shilo user record. If no match is found, Shilo will use
user_name and user_email to create or locate the user.string
required
Display name of the agent on this call. Used for speaker labeling in the transcript and coaching output.
string
required
Email address of the agent on this call. Used to look up or create the corresponding Shilo user account.
string
required
Your system’s unique identifier for the contact (lead or prospect) on this call. Shilo uses this to associate the call with an existing contact record.
string
required
Full display name of the contact on this call. Used for speaker labeling in the transcript and analysis output.
Optional Fields
string
ISO-8601 timestamp representing when the call actually took place (e.g.
"2030-09-24T14:00:00Z"). If omitted, Shilo records the ingestion time instead.string
The phone number the call was placed from, in any standard format. Nullable.
string
The phone number the call was placed to, in any standard format. Nullable.
boolean
Set to
true if this was an inbound call received by the agent; false if the agent placed the call. Nullable.array
Override the default AI models applied to this call. Each element must be an object with
model (string) and type (string) properties. If omitted, Shilo uses the models configured for your organization. Nullable.string
IANA timezone string for the agent (e.g.
"America/New_York"). Used to localize timestamps in coaching reports. Nullable.string
URL of the agent’s profile picture. Used for display in the Shilo dashboard. Nullable.
string
First name of the contact. If provided alongside
contact_last_name, Shilo uses these in place of contact_name for structured display. Nullable.string
Last name of the contact. Nullable.
string
Phone number of the contact. Nullable.
string[]
Array of email addresses associated with the contact. Nullable.
string
Human-readable sales stage name for the contact at the time of this call (e.g.
"Nurture"). Nullable.string
Your system’s identifier for the contact’s sales stage. Nullable.
string
Human-readable lead source name for the contact (e.g.
"Website"). Nullable.string
Your system’s identifier for the contact’s lead source. Nullable.
string[]
Array of tag strings to apply to the contact (e.g.
["hot-lead", "referral"]). Nullable.Response
A successful submission returns HTTP202 Accepted with a CreateCallResponse body.
string
UUID that tracks this submission through Shilo’s async processing pipeline. Save this value — you can pass it as
call_event_id:{uuid} to GET /calls/{identifier} and GET /calls/{identifier}/analysis to poll for results.string
Current processing status of the submission. On initial response this is always
"QUEUED". The call progresses through internal states before analysis becomes available.Example Response
Save the
call_event_id returned in this response. To retrieve the processed call or its AI analysis, use this value as the identifier path parameter in the format call_event_id:{uuid} — for example: GET /api/v1/calls/call_event_id:ee6f2136-b94a-4438-9335-3acf5b2a0d31.Example Request
Error Responses
400 Bad Request — Returned when the request body is missing required fields or contains invalid values. The response body includes amessage field describing the problem.