--- title: "Create a call" method: POST path: "/v1/call" tags: ["Call"] --- # Create a call `POST /v1/call` Create a new call with recording, transcript, agents, and customers ## Request body - CallCreate — Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats. - `recordingUrl` string, uri, required — URL of source recording (must be an accessible WAV, MP3, MP4, or OGG file). Can be a signed URL. - `stereoRecordingUrl` string, uri — URL of source stereo recording. Must be accessible. Can be a signed URL. Supported formats: WAV, MP3, MP4, OGG. - `startedAt` string, required — When the call started (ISO 8601 format) - `interfaceType` 'PHONE' | 'WEB', required — Interface type of the call (PHONE or WEB) - `callDirection` 'INBOUND' | 'OUTBOUND', required — Direction of the call (INBOUND or OUTBOUND) - `endedStatus` 'PARTICIPANTS_DID_NOT_SPEAK' | 'AGENT_DID_NOT_ANSWER' | 'AGENT_DID_NOT_SPEAK' | 'AGENT_STOPPED_SPEAKING' | 'AGENT_ENDED_CALL' | 'AGENT_TRANSFERRED_CALL' | 'AGENT_BUSY' | 'AGENT_ERROR' | 'CUSTOMER_ENDED_CALL' | 'VOICE_MAIL_REACHED' | 'SILENCE_TIME_OUT' | 'PHONE_CALL_PROVIDER_CONNECTION_ERROR' | 'CUSTOMER_DID_NOT_ANSWER' | 'CUSTOMER_DID_NOT_SPEAK' | 'CUSTOMER_STOPPED_SPEAKING' | 'CUSTOMER_BUSY' | 'DIAL_ERROR' | 'MAX_DURATION_REACHED' | 'UNKNOWN' — High-level call end status, indicating how the call terminated - `transcript` union[] — List of transcript entries made during the call - union - TranscriptEntryAgent - `startOffsetMs` integer, required - `endOffsetMs` integer, required - `text` string, required - `languageCode` string - `role` 'AGENT', required - `agent` object - `roarkId` string, uuid - `customId` string - TranscriptEntryCustomer - `startOffsetMs` integer, required - `endOffsetMs` integer, required - `text` string, required - `languageCode` string - `role` 'CUSTOMER', required - `customer` object — Metadata about the customer that spoke this turn - used to match which customer from the `customers` array this transcript entry belongs to - `phoneNumberE164` string — The phone number of the customer in E.164 format, matching the `phoneNumberE164` field on the `customers` array when creating the call - `label` string — Label matching the `label` field on the `customers` array when creating the call - `toolInvocations` object[] — List of tool invocations made during the call - `name` string, required — Name of the tool that was invoked - `description` string — Description of when the tool should be invoked - `parameters` object, required — Parameters provided to the tool during invocation - `result` union, required — Result returned by the tool after execution. Can be a string or a JSON object - string - object - `startOffsetMs` integer, required — Offset in milliseconds from the start of the call when the tool was invoked - `endOffsetMs` integer — Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution - `agent` object — Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to - `roarkId` string, uuid - `customId` string - `properties` object — Custom properties to include with the call. These can be used for filtering and will show in the call details page - `agent` union - object — Single agent participating in the call. Use this for simpler API when you have only one agent. - `roarkId` string, uuid, required — Existing Roark agent ID - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - object — Single agent participating in the call. Use this for simpler API when you have only one agent. - `name` string, required — Agent name - `description` string — Agent description - `customId` string — Agent custom ID - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - object — Single agent participating in the call. Use this for simpler API when you have only one agent. - `customId` string, required — Existing custom ID for a Roark agent - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - `agents` union[] — Agents participating in the call. Each agent requires identification and prompt information. - union - object — Agent participating in the call with their endpoint and prompt - `roarkId` string, uuid, required — Existing Roark agent ID - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - object — Agent participating in the call with their endpoint and prompt - `name` string, required — Agent name - `description` string — Agent description - `customId` string — Agent custom ID - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - object — Agent participating in the call with their endpoint and prompt - `customId` string, required — Existing custom ID for a Roark agent - `endpoint` union — Endpoint configuration for this agent (optional) - AgentEndpointById - `id` string, uuid, required — Existing Roark endpoint ID - AgentEndpointByValue — Lookup or create endpoint if one with these values does not exist - `value` string, required — Endpoint value (phone number in E.164 format or websocket URL) - `type` string, required — Type of endpoint (phone or websocket) - `direction` string — Call direction for this endpoint - `prompt` object — Agent's prompt configuration (optional) - `resolvedPrompt` string, required — The agent's system prompt used during this call - `customer` object — Single customer participating in the call. Use this for simpler API when you have only one customer. - `label` string, nullable — Label to identify this customer in the transcript (e.g., "speaker-01", "speaker-02") - `phoneNumberE164` string, nullable, required — Customer phone number in E.164 format (e.g., +14155551234) - `customers` object[] — Customers participating in the call. - `label` string, nullable — Label to identify this customer in the transcript (e.g., "speaker-01", "speaker-02") - `phoneNumberE164` string, nullable, required — Customer phone number in E.164 format (e.g., +14155551234) ## Response `200` Call created successfully - object - `data` object, required — Response after creating a call - `id` string, uuid, required — Unique identifier for the call - `projectId` string, uuid, required — ID of the project this call belongs to - `status` 'RINGING' | 'IN_PROGRESS' | 'ENDED', nullable, required - `callDirection` 'INBOUND' | 'OUTBOUND', required — Direction of the call (inbound or outbound) - `startedAt` string, required — Timestamp when the call started - `agents` object[], nullable, required - `id` string, uuid, required - `endpoint` object, nullable - `id` string, uuid, required - `environment` string, required - `phoneNumberE164` string, nullable - `customers` object[], nullable, required - `phoneNumberE164` string, nullable - `label` string, nullable - `createdAt` string, nullable, required ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `429` — Too Many Requests - `500` — Internal Server Error --- [API](https://skmtc.net/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.net/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/versions/83528d3618ef/schema)