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

> Initiate an outbound call.


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.

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.


## 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 (e.g. `+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, e.g. `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
            created once 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 —

        e.g. `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).

````