> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Place outbound calls

> Place an outbound call through a channel connection, with idempotent retries and optional answering-machine detection.

[Back to the Outbound Dialing API overview](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-overview.md)

Places an outbound call through the given channel connection. Returns immediately once the call has been accepted for submission. This does not wait for the call to ring or connect. The response returns the `outboundCallId`, the initial `phase` (`accepted`), and the `initiationState`. The request needs the `outbound_calls.initiate` scope.

Returns `201` on a genuinely new call. Repeating the exact same `idempotencyKey` and body returns `200` with the original call instead of placing a duplicate one. Reusing a key with a different body returns `409 IDEMPOTENCY_CONFLICT`.

The request requires `channelConnectionId`, `to`, and `idempotencyKey`. Set `to` to a phone number in E.164 format or to a SIP URI. Optional fields are `clientReferenceId` to correlate the call with your own records, `amdMode` (`off`, `continue`, or `disconnect`) for answering-machine detection, and `sessionMetadata` to attach to the session that starts when the call connects. A `502` error means the call could not be submitted to the telephony provider. If the error code is `OUTBOUND_PROVIDER_REQUEST_UNKNOWN`, check the call's `initiationState` shortly after instead of resubmitting. To track the call, use [Look up a call by ID](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-id) or [Events of outbound calls](https://koreai.mintlify.site/agent-platform/api-reference/outbound-calls-events).


## OpenAPI

````yaml agent-platform/api-specs/outbound-calls.yaml post /api/v1/project/{projectSlug}/{env}/outbound-calls
openapi: 3.1.0
info:
  title: Outbound Dial API
  version: 1.0.0
  summary: >-
    Project-scoped API for placing, tracking, and terminating outbound phone/SIP
    calls through KoreVG.
  description: >
    Places an outbound call through a project's telephony channel connection,
    and lets you

    track it through to completion — either by polling, by listing/searching the
    call log, or

    by subscribing to a live server-sent-events stream.


    Outbound calls are asynchronous by nature. Initiating a call returns
    immediately with an

    `outboundCallId` and an initial `phase` of `accepted` — the call has been
    accepted for

    submission, not yet answered. Track its progress with `GET
    .../outbound-calls/{id}`, the

    live event stream at `GET .../outbound-calls/{id}/events`, or by
    listing/searching the call

    log.


    ### Call lifecycle


    A call moves through `phase` values in order: `accepted` → `dialing` →
    `ringing` →

    `in_progress` (answered) → `terminal` (call has ended, either way). Once a
    call reaches

    `terminal`, `outcome` explains how it ended (`completed`, `busy`,
    `rejected`, `no_answer`,

    `machine`, `failed`, `canceled`, or `expired`), and `failureReason` carries
    additional

    detail for a non-`completed` outcome. A call that connects (`in_progress`)
    creates a

    session — `sessionId` on the call record correlates to that session's own
    history/traces

    once available.


    ### Idempotency


    Every initiate request requires an `idempotencyKey`. Retrying the identical
    request body

    with the same key returns the **original** call (`200`) instead of placing a
    duplicate

    call (`201` on first submission). Reusing the same key with a **different**
    body is

    rejected with `409 IDEMPOTENCY_CONFLICT` — pick a new key for a genuinely
    different call.


    ### Authentication


    Authenticate with the `x-api-key` header, using a Platform API key

    (`abl_...`) scoped to the project you are calling. Write operations
    (initiate, terminate)

    require the `outbound_calls.initiate` scope; read operations (lookup, list,
    summary,

    search, event stream) require `outbound_calls.read`.


    ### Privacy


    `destination` is always returned masked on the wire (for example,
    `+1*******67`) — the full

    number is never echoed back after initiation. `providerCallSid` (the
    underlying telephony

    provider's own call identifier) is likewise masked in call-log responses.
    List and search

    responses never carry an unmasked destination either; use `POST
    .../outbound-calls/search`

    with the real number to look a call up by destination — it is matched
    against a blind

    index server-side, so the raw number never appears in a URL or is logged in
    access logs.


    ### Isolation


    A call belonging to a different project is concealed as `404
    CHANNEL_NOT_FOUND` /

    `404 Not Found`, never `403` — the API does not disclose whether a resource
    exists outside

    your project's scope.
servers:
  - url: https://example.com
    description: Base URL of your platform.
    variables:
      host:
        default: runtime.example.com
security:
  - ApiKeyAuth: []
tags:
  - name: Outbound Calls
    description: Place and track outbound phone/SIP calls.
paths:
  /api/v1/project/{projectSlug}/{env}/outbound-calls:
    post:
      tags:
        - Outbound Calls
      summary: Initiate an outbound call
      description: |
        Initiate an outbound call.
      operationId: initiateOutboundCall
      parameters:
        - $ref: '#/components/parameters/ProjectSlug'
        - $ref: '#/components/parameters/Env'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateOutboundCallRequest'
            example:
              channelConnectionId: cc_01a09438
              to:
                type: phone
                number: '+14155550123'
              idempotencyKey: order-4821-attempt-1
              clientReferenceId: order-4821
              amdMode: 'off'
      responses:
        '200':
          description: >-
            Idempotent replay — the original call for this `idempotencyKey` +
            body, returned unchanged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateOutboundCallResponse'
        '201':
          description: A new call was created and submitted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateOutboundCallResponse'
              example:
                success: true
                data:
                  outboundCallId: oc_01a0a4af5a417f5186af
                  phase: accepted
                  initiationState: submitted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/ProviderError'
components:
  parameters:
    ProjectSlug:
      name: projectSlug
      in: path
      required: true
      description: The project's slug.
      schema:
        type: string
        minLength: 1
    Env:
      name: env
      in: path
      required: true
      description: >-
        Deployment environment segment the call runs under, for example,
        `production`, `staging`, `dev`.
      schema:
        type: string
        minLength: 1
  schemas:
    InitiateOutboundCallRequest:
      type: object
      additionalProperties: false
      required:
        - channelConnectionId
        - to
        - idempotencyKey
      properties:
        channelConnectionId:
          type: string
          minLength: 1
          description: >-
            The outbound-capable channel connection (telephony trunk/app) to
            place the call through.
        to:
          $ref: '#/components/schemas/OutboundCallDestination'
        idempotencyKey:
          type: string
          minLength: 1
          description: >
            Caller-supplied key. Repeating this exact request (same key + same
            body) returns

            the original call (`200`) instead of dialing again. The same key
            with a

            different body is rejected with `409 IDEMPOTENCY_CONFLICT`.
        clientReferenceId:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            Optional caller correlation id, echoed back on the call record and
            filterable via `clientReferenceId`.
        amdMode:
          $ref: '#/components/schemas/OutboundAmdMode'
        sessionMetadata:
          type: object
          description: >-
            Optional arbitrary key/value metadata attached to the session that's
            created after the call connects.
          additionalProperties: true
    InitiateOutboundCallResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - outboundCallId
            - phase
            - initiationState
          properties:
            outboundCallId:
              type: string
            phase:
              $ref: '#/components/schemas/OutboundCallPhase'
            initiationState:
              $ref: '#/components/schemas/OutboundInitiationState'
    OutboundCallDestination:
      description: Destination for the call — a phone number or a SIP URI.
      oneOf:
        - type: object
          required:
            - type
            - number
          properties:
            type:
              type: string
              enum:
                - phone
            number:
              type: string
              minLength: 1
              description: E.164 phone number.
        - type: object
          required:
            - type
            - sipUri
          properties:
            type:
              type: string
              enum:
                - sip
            sipUri:
              type: string
              minLength: 1
    OutboundAmdMode:
      type: string
      description: >
        Answering-machine detection behavior. off=disabled, no AMD processing;
        continue=detect

        and report via `amdResult`, but let the call proceed regardless;
        disconnect=detect and

        automatically hang up on a machine.
      enum:
        - 'off'
        - continue
        - disconnect
    OutboundCallPhase:
      type: string
      description: >
        Lifecycle phase, in order: accepted=submitted, not yet dialing;
        dialing=submitted to

        the carrier; ringing=destination is ringing; in_progress=answered, call
        is live;

        terminal=call has ended (see `outcome`).
      enum:
        - accepted
        - dialing
        - ringing
        - in_progress
        - terminal
    OutboundInitiationState:
      type: string
      description: >
        Submit-lifecycle state, distinct from `phase` — tracks getting the
        request to the

        telephony provider, not the call itself. created=call row written, not
        yet submitted;

        provider_requesting=submit in flight; submitted=provider accepted the
        request;

        provider_request_unknown=the submit outcome could not be confirmed (will
        be

        reconciled); failed_to_submit=submission failed before reaching the
        provider.
      enum:
        - created
        - provider_requesting
        - submitted
        - provider_request_unknown
        - failed_to_submit
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable detail.
            requestId:
              type: string
              description: Correlates this failure to platform-side logs.
  responses:
    BadRequest:
      description: >
        The request could not be understood. `error.code` says which validation
        failed —

        for example, `INVALID_PHONE_NUMBER` for a malformed `to.number`, or
        `SIP_INJECTION_REJECTED`

        for a SIP URI containing CRLF/header-injection content.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Missing or invalid `x-api-key`, or the key lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: >
        `error.code=CHANNEL_NOT_FOUND` — either the `channelConnectionId`
        doesn't exist, or

        the `outboundCallId` doesn't exist or belongs to a different project
        (isolation is

        enforced by concealment, not a `403`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    IdempotencyConflict:
      description: >-
        `error.code=IDEMPOTENCY_CONFLICT` — this `idempotencyKey` was already
        used with a different request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Unexpected failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ProviderError:
      description: >
        The call could not be submitted to the telephony provider. `error.code`
        distinguishes

        the cause: `OUTBOUND_PROVIDER_SUBMIT_FAILED` (the provider rejected the
        request —

        often a transient capacity condition, safe to retry),
        `OUTBOUND_WEBHOOK_NOT_CONFIGURED`

        (the project's environment is missing its outbound status-webhook
        signing key — a

        deployment configuration issue, not fixable by retrying), or

        `OUTBOUND_PROVIDER_REQUEST_UNKNOWN` (the submit outcome could not be
        confirmed; the

        platform reconciles this automatically — check the call's
        `initiationState` shortly

        after rather than resubmitting).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Project-bound Platform API key (`abl_...`). The key must carry
        `outbound_calls.initiate`

        for write operations (initiate, terminate) or `outbound_calls.read` for
        read operations

        (lookup, list, summary, search, event stream).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.