> ## Documentation Index > Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an outbound batch > Creates an outbound batch under conversations:write and starts dialing right away, at most five calls at a time per organization. Send up to 5000 recipients as JSON, or a csvUrl (https) to a CSV with a header row: phone_number (E.164) is required; name, first_message, prompt, and from_channel_id map to the recipient fields; any other column becomes a dynamic variable. The number each call leaves from is resolved per recipient: its fromChannelId, then the batch fromChannelId, then the Agent's own outbound channel, then the organization's platform-managed line. Batch-level firstMessage and prompt apply unless a recipient overrides them; {{variables}} are substituted by the voice provider. Calls start right away unless startAt is given; an optional schedule limits them to weekday windows in a time zone; at endAt whatever is still pending is cancelled as expired. Each accepted call becomes an ordinary outbound Conversation with originKind automation; a recipient settles only after that Conversation's post-call evaluation, and retries (retryOn) when nobody answered or the evaluation failed. Send idempotencyKey so a retried request returns the same batch instead of creating a second one. ## OpenAPI ````yaml https://api.getarbol.com/openapi.json post /outbound-batches openapi: 3.1.2 info: contact: email: support@getarbol.com name: Arbol url: https://docs.getarbol.com description: >- Build and operate Arbol's organization-scoped conversational platform through one provider-neutral REST contract. Resources cover Agents, channels, contacts, conversations, Knowledge, connected accounts, analytics, and evaluation runs. Every bearer is verified by Auth0, every request is bound to exactly one Organization, and every operation enforces all scopes listed in its security requirement. title: Arbol API version: 1.0.0 servers: - description: Production url: https://api.getarbol.com/v1 security: [] tags: - description: >- Create and configure conversational Agents. Provider-specific runtime details remain private to Arbol. name: Agents - description: >- Define suites, start durable evaluation runs, inspect trials, and compare Agent behavior. name: Agent evaluations - description: >- Read organization-scoped operational aggregates without exposing raw provider telemetry. name: Analytics - description: >- Attach and manage provider-neutral voice or messaging endpoints owned by an Agent. name: Channels - description: >- Authorize and manage reusable organization accounts whose credentials remain in Composio. name: Connected accounts - description: >- Manage people, their routable identities, merged activity timeline, and durable CSV imports. name: Contacts - description: >- Start outbound calls and inspect tenant-scoped voice, WhatsApp, and web conversations. name: Conversations - description: >- Define revisioned structured fields used to capture organization-specific Contact and Conversation facts. name: Definitions - description: >- Call a list of phone numbers with one Agent, a few at a time, with optional first-message and prompt overrides. name: Outbound batches - description: >- Read and assert typed values against active Definitions with explicit evidence and verification state. name: Facts - description: >- Discover live business-tool capabilities available through Arbol's Composio boundary. name: Integrations - description: >- Upload, index, search, download, and lifecycle-manage organization Knowledge documents. name: Knowledge - description: Read and update the current Organization's product-level settings. name: Organization - description: >- Discover provider-neutral synthetic voices that can be assigned to voice Agents. name: Voices paths: /outbound-batches: post: tags: - Outbound batches summary: Create an outbound batch description: >- Creates an outbound batch under conversations:write and starts dialing right away, at most five calls at a time per organization. Send up to 5000 recipients as JSON, or a csvUrl (https) to a CSV with a header row: phone_number (E.164) is required; name, first_message, prompt, and from_channel_id map to the recipient fields; any other column becomes a dynamic variable. The number each call leaves from is resolved per recipient: its fromChannelId, then the batch fromChannelId, then the Agent's own outbound channel, then the organization's platform-managed line. Batch-level firstMessage and prompt apply unless a recipient overrides them; {{variables}} are substituted by the voice provider. Calls start right away unless startAt is given; an optional schedule limits them to weekday windows in a time zone; at endAt whatever is still pending is cancelled as expired. Each accepted call becomes an ordinary outbound Conversation with originKind automation; a recipient settles only after that Conversation's post-call evaluation, and retries (retryOn) when nobody answered or the evaluation failed. Send idempotencyKey so a retried request returns the same batch instead of creating a second one. operationId: createOutboundBatch requestBody: required: true content: application/json: schema: type: object properties: agentId: $ref: '#/components/schemas/ArbolResourceId' endAt: $ref: '#/components/schemas/IsoDatetime' description: >- Stop starting calls at this instant: recipients still pending become cancelled with failureReason expired; calls in progress finish. Absent: run until every recipient is settled. firstMessage: description: >- Replaces the Agent's first message for every call in the batch. Supports {{dynamic_variables}}. type: string minLength: 1 maxLength: 2000 fromChannelId: $ref: '#/components/schemas/ArbolResourceId' description: >- Connected voice channel to call from. Resolution order per call: recipient fromChannelId, then this, then the Agent's own outbound channel, then the organization's platform-managed line. idempotencyKey: description: >- Caller-generated key. Repeating a request with the same key returns the batch created the first time instead of calling everyone again. examples: - campaign-2026-09-recordatorios type: string minLength: 8 maxLength: 200 name: type: string minLength: 1 maxLength: 200 prompt: description: >- Replaces the Agent's system prompt for every call in the batch. The Agent's stored configuration is untouched. type: string minLength: 1 maxLength: 20000 retries: default: 0 description: >- Extra attempts per recipient when a call does not count as successful (see retryOn). 0 dials each number once. type: integer minimum: 0 maximum: 5 retryDelaySeconds: default: 900 description: Wait between attempts to the same number. type: integer minimum: 60 maximum: 86400 retryOn: default: - noAnswer - failure description: >- What earns a retry. noAnswer: the call closed without a single message. failure: the Conversation's post-call success evaluation is failure (voicemail, goal not met, per the Agent's assessments). Drop failure when a refusal must not be called again. maxItems: 2 type: array items: $ref: '#/components/schemas/OutboundBatchRetryTrigger' schedule: $ref: '#/components/schemas/CallingSchedule' description: >- Only start calls inside these windows; outside them the batch waits for the next opening. Absent: any time. startAt: $ref: '#/components/schemas/IsoDatetime' description: >- Do not start any call before this instant. Absent: start right away (inside the schedule, if one is given). csvUrl: description: >- https link to a CSV (max 5 MB, header row required). Alternative to recipients. Downloaded once, when the batch is created. examples: - https://files.example.com/campaign-september.csv type: string maxLength: 2000 format: uri recipients: minItems: 1 maxItems: 5000 type: array items: $ref: '#/components/schemas/OutboundBatchRecipientInput' required: - agentId - name additionalProperties: false responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/OutboundBatch' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '400': description: >- Inferable validation failure or a non-inferable malformed transport request. content: application/json: schema: oneOf: - oneOf: - $ref: '#/components/schemas/BadRequest' - $ref: '#/components/schemas/UndefinedError' - $ref: '#/components/schemas/TransportBadRequestError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '401': description: Authentication is required. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Unauthorized' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '403': description: The caller is not allowed to perform this operation. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Forbidden' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '404': description: Outbound batch not found content: application/json: schema: oneOf: - $ref: '#/components/schemas/NotFound' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '409': description: The outbound batch request conflicts with its state content: application/json: schema: oneOf: - $ref: '#/components/schemas/Conflict3' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '413': $ref: '#/components/responses/TransportPayloadTooLarge' '415': $ref: '#/components/responses/TransportUnsupportedMediaType' '422': description: >- The Agent or a channel cannot place voice calls, or the recipients are invalid content: application/json: schema: oneOf: - $ref: '#/components/schemas/UnprocessableContent3' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '429': description: '429' content: application/json: schema: oneOf: - $ref: '#/components/schemas/TooManyRequests' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' '503': description: The outbound batch service is unavailable content: application/json: schema: oneOf: - $ref: '#/components/schemas/ServiceUnavailable2' - $ref: '#/components/schemas/UndefinedError' headers: X-Request-Id: $ref: '#/components/headers/RequestId' security: - userOAuth: - org:use - conversations:write - machineOAuth: - conversations:write components: schemas: ArbolResourceId: type: string maxLength: 64 pattern: >- ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ description: >- Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type. examples: - agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31 title: Arbol resource ID IsoDatetime: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: ISO 8601 timestamp with an explicit UTC offset. examples: - '2026-08-29T14:30:00Z' title: ISO timestamp OutboundBatchRetryTrigger: type: string enum: - noAnswer - failure title: Outbound batch retry trigger CallingSchedule: type: object properties: timezone: type: string minLength: 1 maxLength: 64 examples: - America/Bogota windows: minItems: 1 maxItems: 20 type: array items: $ref: '#/components/schemas/CallingWindow' required: - timezone - windows additionalProperties: false description: >- Weekday windows on the wall clock of `timezone`. Example: Monday and Tuesday 04:00-14:00 and 20:00-22:00, Friday 10:00-11:00. title: Calling schedule OutboundBatchRecipientInput: type: object properties: dynamicVariables: default: {} description: >- Values for {{placeholders}} in the prompt and first message. `name` is filled from the recipient name when not given. type: object propertyNames: type: string minLength: 1 maxLength: 80 additionalProperties: anyOf: - type: string maxLength: 2000 - type: number - type: boolean firstMessage: description: Overrides the batch first message for this recipient only. type: string minLength: 1 maxLength: 2000 fromChannelId: $ref: '#/components/schemas/ArbolResourceId' description: Channel to call this recipient from; overrides the batch channel. name: type: string minLength: 1 maxLength: 200 phoneNumber: $ref: '#/components/schemas/E164PhoneNumber' prompt: description: Overrides the batch prompt for this recipient only. type: string minLength: 1 maxLength: 20000 required: - phoneNumber additionalProperties: false title: Outbound batch recipient input OutboundBatch: type: object properties: agentId: $ref: '#/components/schemas/ArbolResourceId' counts: $ref: '#/components/schemas/OutboundBatchCounts' createdAt: $ref: '#/components/schemas/IsoDatetime' endAt: anyOf: - $ref: '#/components/schemas/IsoDatetime' - type: 'null' firstMessage: anyOf: - type: string minLength: 1 maxLength: 2000 - type: 'null' fromChannelId: anyOf: - $ref: '#/components/schemas/ArbolResourceId' - type: 'null' id: $ref: '#/components/schemas/ArbolResourceId' idempotencyKey: anyOf: - type: string maxLength: 200 - type: 'null' name: type: string maxLength: 200 prompt: anyOf: - type: string minLength: 1 maxLength: 20000 - type: 'null' retries: type: integer minimum: 0 maximum: 5 retryDelaySeconds: type: integer minimum: 60 maximum: 86400 retryOn: maxItems: 2 type: array items: $ref: '#/components/schemas/OutboundBatchRetryTrigger' schedule: anyOf: - $ref: '#/components/schemas/CallingSchedule' - type: 'null' startAt: anyOf: - $ref: '#/components/schemas/IsoDatetime' - type: 'null' status: $ref: '#/components/schemas/OutboundBatchStatus' updatedAt: $ref: '#/components/schemas/IsoDatetime' required: - agentId - counts - createdAt - endAt - firstMessage - fromChannelId - id - idempotencyKey - name - prompt - retries - retryDelaySeconds - retryOn - schedule - startAt - status - updatedAt additionalProperties: false title: Outbound batch BadRequest: type: object properties: defined: const: true inferable: type: boolean code: const: BAD_REQUEST status: const: 400 message: type: string data: type: object properties: issues: maxItems: 20 type: array items: type: object properties: code: type: string enum: - custom - invalid_format - invalid_type - invalid_value - too_big - too_small - unrecognized_keys message: type: string maxLength: 500 path: maxItems: 16 type: array items: anyOf: - type: string maxLength: 120 - type: integer minimum: 0 maximum: 9007199254740991 required: - code - message additionalProperties: false truncated: type: boolean required: - issues - truncated additionalProperties: false required: - defined - inferable - code - status - message - data UndefinedError: type: object properties: defined: const: false inferable: type: boolean code: type: string status: type: number message: type: string data: {} required: - defined - inferable - code - status - message TransportBadRequestError: additionalProperties: false properties: code: const: BAD_REQUEST data: {} defined: const: false inferable: const: false message: type: string required: - defined - inferable - code - message type: object Unauthorized: type: object properties: defined: const: true inferable: type: boolean code: const: UNAUTHORIZED status: const: 401 message: type: string data: {} required: - defined - inferable - code - status - message Forbidden: type: object properties: defined: const: true inferable: type: boolean code: const: FORBIDDEN status: const: 403 message: type: string data: type: object properties: missingPermissions: maxItems: 10 type: array items: $ref: '#/components/schemas/AuthPermission' required: - missingPermissions additionalProperties: false required: - defined - inferable - code - status - message NotFound: type: object properties: defined: const: true inferable: type: boolean code: const: NOT_FOUND status: const: 404 message: type: string data: {} required: - defined - inferable - code - status - message Conflict3: type: object properties: defined: const: true inferable: type: boolean code: const: CONFLICT status: const: 409 message: type: string data: {} required: - defined - inferable - code - status - message UnprocessableContent3: type: object properties: defined: const: true inferable: type: boolean code: const: UNPROCESSABLE_CONTENT status: const: 422 message: type: string data: {} required: - defined - inferable - code - status - message TooManyRequests: type: object properties: defined: const: true inferable: type: boolean code: const: TOO_MANY_REQUESTS status: const: 429 message: type: string data: type: object properties: retryAfterSeconds: type: integer exclusiveMinimum: 0 maximum: 3600 required: - retryAfterSeconds additionalProperties: false required: - defined - inferable - code - status - message - data ServiceUnavailable2: type: object properties: defined: const: true inferable: type: boolean code: const: SERVICE_UNAVAILABLE status: const: 503 message: type: string data: {} required: - defined - inferable - code - status - message CallingWindow: type: object properties: days: minItems: 1 maxItems: 7 type: array items: type: string enum: - mon - tue - wed - thu - fri - sat - sun end: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ examples: - '09:30' description: No new call starts at or after this wall-clock time. start: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ examples: - '09:30' required: - days - end - start additionalProperties: false title: Calling window E164PhoneNumber: type: string pattern: ^\+[1-9]\d{7,14}$ description: International telephone number in E.164 form. examples: - '+573001234567' title: E.164 phone number OutboundBatchCounts: type: object properties: calling: type: integer minimum: 0 maximum: 9007199254740991 cancelled: type: integer minimum: 0 maximum: 9007199254740991 completed: type: integer minimum: 0 maximum: 9007199254740991 failed: type: integer minimum: 0 maximum: 9007199254740991 pending: type: integer minimum: 0 maximum: 9007199254740991 total: type: integer minimum: 0 maximum: 9007199254740991 required: - calling - cancelled - completed - failed - pending - total additionalProperties: false title: Outbound batch recipient counts OutboundBatchStatus: type: string enum: - queued - running - completed - cancelled description: >- queued: no call placed yet. running: at least one call placed. completed: every recipient settled. cancelled: pending recipients were dropped; calls already placed finish normally. title: Outbound batch status AuthPermission: type: string enum: - agent-evaluations:read - agent-evaluations:run - agent-evaluations:write - agents:read - agents:write - analytics:read - arbi:use - channels:read - channels:write - contacts:read - contacts:write - conversations:read - conversations:transcript - conversations:write - definitions:read - definitions:write - facts:read - facts:write - integrations:read - integrations:write - knowledge:read - knowledge:write - org:manage - org:use description: >- One permission from the closed Arbol API vocabulary accepted from a verified Auth0 token. examples: - agents:read title: API permission TransportPayloadTooLargeError: additionalProperties: false properties: code: const: PAYLOAD_TOO_LARGE data: {} defined: const: false inferable: const: false message: type: string required: - defined - inferable - code - message type: object TransportUnsupportedMediaTypeError: additionalProperties: false properties: code: const: UNSUPPORTED_MEDIA_TYPE data: {} defined: const: false inferable: const: false message: type: string required: - defined - inferable - code - message type: object headers: RequestId: description: >- Opaque request correlation identifier. Include it when contacting Arbol support. schema: type: string maxLength: 128 responses: TransportPayloadTooLarge: content: application/json: schema: $ref: '#/components/schemas/TransportPayloadTooLargeError' description: The request body exceeds the API transport limit. headers: X-Request-Id: $ref: '#/components/headers/RequestId' TransportUnsupportedMediaType: content: application/json: schema: $ref: '#/components/schemas/TransportUnsupportedMediaTypeError' description: The request media type is not supported. headers: X-Request-Id: $ref: '#/components/headers/RequestId' securitySchemes: userOAuth: description: >- Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server. flows: authorizationCode: authorizationUrl: https://auth.getarbol.com/authorize scopes: agent-evaluations:read: Read Agent evaluation suites, runs, and results. agent-evaluations:run: Execute and cancel Agent evaluation runs. agent-evaluations:write: Create and update Agent evaluation suites. agents:read: Read Agents and their explicitly requested expansions. agents:write: Create, update, and delete Agents. analytics:read: Read organization analytics. arbi:use: Use the personal Arbi workspace. channels:read: Read Agent channels. channels:write: Create, update, authorize, and delete Agent channels. contacts:read: Read Contacts and their explicitly requested expansions. contacts:write: Create, update, merge, import, and delete Contacts. conversations:read: Read Conversation metadata. conversations:transcript: Read Conversation messages and media evidence. conversations:write: Create and process Conversations. definitions:read: Read Definitions and Definition usage. definitions:write: Create, update, and retire Definitions. facts:read: Read current and historical Facts. facts:write: Assert typed Facts. integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence. integrations:write: Authorize accounts and assign exact tool access. knowledge:read: Read Knowledge documents and search indexed content. knowledge:write: Create, index, update, and delete Knowledge documents. org:manage: Update the Organization and administer its members. org:use: Use Arbol as a member of the selected Auth0 Organization. tokenUrl: https://auth.getarbol.com/oauth/token type: oauth2 machineOAuth: description: >- Organization-bound Auth0 client-credentials token. The client grant must contain every operation scope. flows: clientCredentials: scopes: agent-evaluations:read: Read Agent evaluation suites, runs, and results. agent-evaluations:run: Execute and cancel Agent evaluation runs. agent-evaluations:write: Create and update Agent evaluation suites. agents:read: Read Agents and their explicitly requested expansions. agents:write: Create, update, and delete Agents. analytics:read: Read organization analytics. channels:read: Read Agent channels. channels:write: Create, update, authorize, and delete Agent channels. contacts:read: Read Contacts and their explicitly requested expansions. contacts:write: Create, update, merge, import, and delete Contacts. conversations:read: Read Conversation metadata. conversations:transcript: Read Conversation messages and media evidence. conversations:write: Create and process Conversations. definitions:read: Read Definitions and Definition usage. definitions:write: Create, update, and retire Definitions. facts:read: Read current and historical Facts. facts:write: Assert typed Facts. integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence. integrations:write: Authorize accounts and assign exact tool access. knowledge:read: Read Knowledge documents and search indexed content. knowledge:write: Create, index, update, and delete Knowledge documents. org:manage: Update the Organization and administer its members. tokenUrl: https://auth.getarbol.com/oauth/token type: oauth2 ````