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

# Start an outbound call

> Start a phone call from a number your organization owns. The caregiver attached to that number runs the call. Use the returned `call_id` to read the result rather than guessing which row in the call list is yours. The call runs only when workspace balance, caregiver readiness, and the concurrency limit allow it; a refused call creates no record.



## OpenAPI

````yaml /openapi/backend.json post /api/calls/make-outbound
openapi: 3.0.3
info:
  title: Drive Health operational API
  version: 1.0.0
  description: >-
    Server-to-server API for organizations integrating with Drive Health. It
    starts chat and voice conversations and reads the calls, chats, transcripts,
    and recordings those conversations produce. Authenticate every request with
    an organization API key.
servers:
  - url: https://backend.drivehealth.ai
    description: Production. Use the API origin supplied for your environment.
security:
  - organizationBearer: []
  - organizationApiKey: []
tags:
  - name: Chat
    description: >-
      Start a chat with a caregiver, exchange messages, and end the session.
      These routes also answer on the compatibility mount `/v1/chat/...`.
  - name: Voice
    description: Start phone calls from an owned number and register browser voice calls.
  - name: Results
    description: >-
      Read the calls, chat sessions, transcripts, and recordings your
      organization owns.
paths:
  /api/calls/make-outbound:
    post:
      tags:
        - Voice
      summary: Start an outbound call
      description: >-
        Start a phone call from a number your organization owns. The caregiver
        attached to that number runs the call. Use the returned `call_id` to
        read the result rather than guessing which row in the call list is
        yours. The call runs only when workspace balance, caregiver readiness,
        and the concurrency limit allow it; a refused call creates no record.
      operationId: startOutboundCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundCallRequest'
            example:
              from_number: '+15551110000'
              to_number: '+15552220000'
              variables:
                - var_name: patient_name
                  var_value: Alex
      responses:
        '200':
          description: The call was initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallStartedResponse'
              example:
                err: false
                msg: Call initiated successfully
                results:
                  call_id: 3c2b1a09-8f7e-4d6c-9b8a-7d6c5b4a3f2e
        '400':
          description: >-
            The number is not owned by your organization, or a call precondition
            failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                unknownNumber:
                  summary: Number not owned
                  value:
                    err: true
                    msg: From number not found.
                concurrency:
                  summary: Over the concurrency limit
                  value:
                    err: true
                    msg: Maximum concurrency limit reached.
        '403':
          $ref: '#/components/responses/Refused'
components:
  schemas:
    OutboundCallRequest:
      type: object
      required:
        - from_number
        - to_number
      properties:
        from_number:
          type: string
          description: >-
            A phone number your organization owns. The caregiver attached to it
            runs the call.
          example: '+15551110000'
        to_number:
          type: string
          description: The phone number to call.
          example: '+15552220000'
        variables:
          type: array
          description: Values the caregiver can use during the call.
          items:
            $ref: '#/components/schemas/CallVariable'
          default: []
    CallStartedResponse:
      type: object
      required:
        - err
        - msg
        - results
      properties:
        err:
          type: boolean
          example: false
        msg:
          type: string
          example: Call initiated successfully
        results:
          type: object
          required:
            - call_id
          properties:
            call_id:
              type: string
              format: uuid
              description: ID of the new call.
    ErrorEnvelope:
      type: object
      required:
        - err
        - msg
      properties:
        err:
          type: boolean
          example: true
        msg:
          type: string
          description: What went wrong.
    CallVariable:
      type: object
      required:
        - var_name
        - var_value
      properties:
        var_name:
          type: string
          example: patient_name
        var_value:
          type: string
          example: Alex
    Refusal:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: Why the request was refused.
  responses:
    Refused:
      description: >-
        Refused before the endpoint ran, with `detail` instead of the standard
        envelope: the key is missing, invalid, or revoked; more than one
        credential was presented; or a selector names a different organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Refusal'
          examples:
            invalidKey:
              summary: Invalid or revoked key
              value:
                detail: Unauthorized
            noCredential:
              summary: No credential
              value:
                detail: Authentication credentials were not provided.
            conflictingCredentials:
              summary: More than one credential
              value:
                detail: >-
                  More than one credential was presented. Send an organization
                  key or a session token, not both.
            foreignSelector:
              summary: Selector names another organization
              value:
                detail: >-
                  This key belongs to a different organization than the request
                  selected.
  securitySchemes:
    organizationBearer:
      type: http
      scheme: bearer
      description: >-
        An organization API key starting with `dh_`, sent as `Authorization:
        Bearer dh_your_api_key`.
    organizationApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Alternative to the Authorization header. Send one credential per
        request.

````

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