> ## 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.

# Start an outbound conversation

> Starts one outbound voice Conversation under conversations:write; channel selection, provider routing, and persistence belong to Agents. Reuse the same idempotencyKey after an uncertain response to recover the original Conversation instead of starting another call.



## OpenAPI

````yaml https://api.getarbol.com/openapi.json post /conversations
openapi: 3.1.2
info:
  contact:
    email: support@getarbol.com
    name: Arbol
    url: https://docs.getarbol.com
  description: >-
    Provider-neutral API for creating and operating Arbol agents, contacts,
    conversations, channels, knowledge, integrations, and evaluations. Every
    request is bound to one Auth0 Organization.
  title: Arbol API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.getarbol.com/v1
security: []
paths:
  /conversations:
    post:
      tags:
        - Conversations
      summary: Start an outbound conversation
      description: >-
        Starts one outbound voice Conversation under conversations:write;
        channel selection, provider routing, and persistence belong to Agents.
        Reuse the same idempotencyKey after an uncertain response to recover the
        original Conversation instead of starting another call.
      operationId: createConversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  $ref: '#/components/schemas/ArbolResourceId'
                channelId:
                  $ref: '#/components/schemas/ArbolResourceId'
                contactId:
                  anyOf:
                    - $ref: '#/components/schemas/ArbolResourceId'
                    - type: 'null'
                dynamicVariables:
                  default: {}
                  type: object
                  propertyNames:
                    type: string
                    minLength: 1
                    maxLength: 80
                  additionalProperties:
                    anyOf:
                      - type: string
                        maxLength: 2000
                      - type: number
                      - type: boolean
                firstMessage:
                  type: string
                  minLength: 1
                  maxLength: 2000
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 200
                subjectContactId:
                  anyOf:
                    - $ref: '#/components/schemas/ArbolResourceId'
                    - type: 'null'
                title:
                  anyOf:
                    - type: string
                      maxLength: 500
                    - type: 'null'
                toNumber:
                  $ref: '#/components/schemas/E164PhoneNumber'
              required:
                - agentId
                - idempotencyKey
                - toNumber
              additionalProperties: false
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
          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: Agent or channel 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 destination identity is ambiguous
          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 conversation could not be started
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UnprocessableContent'
                  - $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 conversation service is unavailable
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ServiceUnavailable'
                  - $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
    E164PhoneNumber:
      type: string
      pattern: ^\+[1-9]\d{7,14}$
      description: International telephone number in E.164 form.
      examples:
        - '+573001234567'
      title: E.164 phone number
    Conversation:
      type: object
      properties:
        agentId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        channelKind:
          $ref: '#/components/schemas/ChannelKind'
        closeReason:
          anyOf:
            - $ref: '#/components/schemas/ConversationCloseReason'
            - type: 'null'
        contactId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/IsoDatetime'
        direction:
          $ref: '#/components/schemas/ConversationDirection'
        durationSeconds:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 9007199254740991
            - type: 'null'
        endedAt:
          anyOf:
            - $ref: '#/components/schemas/IsoDatetime'
            - type: 'null'
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        language:
          anyOf:
            - type: string
              maxLength: 35
            - type: 'null'
        lastMessageAt:
          anyOf:
            - $ref: '#/components/schemas/IsoDatetime'
            - type: 'null'
        messageCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        originKind:
          $ref: '#/components/schemas/ConversationOriginKind'
        outcome:
          anyOf:
            - $ref: '#/components/schemas/ConversationOutcome'
            - type: 'null'
        sentiment:
          anyOf:
            - $ref: '#/components/schemas/ConversationSentiment'
            - type: 'null'
        startedAt:
          $ref: '#/components/schemas/IsoDatetime'
        status:
          $ref: '#/components/schemas/ConversationStatus'
        subjectContactId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        summary:
          anyOf:
            - type: string
              maxLength: 8000
            - type: 'null'
        title:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
        updatedAt:
          $ref: '#/components/schemas/IsoDatetime'
      required:
        - agentId
        - channelKind
        - closeReason
        - contactId
        - createdAt
        - direction
        - durationSeconds
        - endedAt
        - id
        - language
        - lastMessageAt
        - messageCount
        - originKind
        - outcome
        - sentiment
        - startedAt
        - status
        - subjectContactId
        - summary
        - title
        - updatedAt
      additionalProperties: false
      description: >-
        Tenant-scoped Conversation metadata; transcripts and media require
        separate authorized expansions.
      title: Conversation
    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:
                  message:
                    type: string
                    maxLength: 500
                  path:
                    maxItems: 16
                    type: array
                    items:
                      anyOf:
                        - type: string
                          maxLength: 120
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                required:
                  - 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
    UnprocessableContent:
      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
    ServiceUnavailable:
      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
    ChannelKind:
      type: string
      enum:
        - voice
        - whatsapp
        - telegram
        - slack
        - email
        - web
      description: Conversation transport family.
      examples:
        - voice
      title: Channel kind
    ConversationCloseReason:
      type: string
      enum:
        - completed
        - inactivity
        - handoff
        - provider_migration
        - error
        - manual
      description: Reason recorded when a Conversation enters its closed state.
      examples:
        - completed
      title: Conversation close reason
    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
    ConversationDirection:
      type: string
      enum:
        - inbound
        - outbound
      description: Direction of a Conversation relative to the organization.
      examples:
        - inbound
      title: Conversation direction
    ConversationOriginKind:
      type: string
      enum:
        - inbound
        - manual
        - automation
        - import
        - test
      description: Source that created the Conversation record.
      examples:
        - manual
      title: Conversation origin
    ConversationOutcome:
      type: string
      enum:
        - successful
        - unsuccessful
        - follow_up_needed
        - no_answer
      description: Structured business outcome assigned to a Conversation.
      examples:
        - successful
      title: Conversation outcome
    ConversationSentiment:
      type: string
      enum:
        - positive
        - neutral
        - negative
      description: Coarse sentiment assigned to a Conversation.
      examples:
        - neutral
      title: Conversation sentiment
    ConversationStatus:
      type: string
      enum:
        - open
        - closed
      description: Durable lifecycle state of a Conversation.
      examples:
        - open
      title: Conversation 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

````