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

# Place a call

> Dials one real person with an objective, or runs a saved outbound agent. It can't be undone once dialing starts. Calls go out only 8am–9pm in both the recipient's and the firm's time zones, at most 50 per firm per day and one per number every two hours, never to numbers on the Do Not Call list. Try `POST /calls/check` first.

Key permission: **Read history and place calls**.



## OpenAPI

````yaml /api-reference/openapi.json post /calls
openapi: 3.1.0
info:
  title: Lawtte API
  version: 1.0.0
  description: >-
    Read your receptionist's calls, place AI calls, manage saved outbound agents
    and the Do Not Call list. The same rules as the Lawtte connector apply to
    every call.
servers:
  - url: https://www.lawtte.ai/api/v1
security:
  - connectorKey: []
paths:
  /calls:
    post:
      tags:
        - Calls
      summary: Place a call
      description: >-
        Dials one real person with an objective, or runs a saved outbound agent.
        It can't be undone once dialing starts. Calls go out only 8am–9pm in
        both the recipient's and the firm's time zones, at most 50 per firm per
        day and one per number every two hours, never to numbers on the Do Not
        Call list. Try `POST /calls/check` first.


        Key permission: **Read history and place calls**.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallInput'
      responses:
        '201':
          description: Dialing. Get the result from `GET /calls/{id}` once it ends.
          content:
            application/json:
              schema:
                type: object
                properties:
                  call_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    example: dialing
                  message:
                    type: string
                  objective:
                    type: string
                  agent_id:
                    type: string
                    format: uuid
                  agent_name:
                    type: string
                  trial_calls_remaining:
                    type: integer
        '400':
          description: Invalid body; the message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, wrong, revoked or expired key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key doesn't have the permission this endpoint needs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Lawtte refused the call — consent, hours, Do Not Call, limits — and
            says why. Nothing was dialed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: More than 120 requests in a minute for this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: A problem on Lawtte's side. Nothing was changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CallInput:
      type: object
      additionalProperties: false
      required:
        - name
        - phone
        - consent_confirmed
        - represented_by_counsel
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Who is being called, as the agent should address them.
        phone:
          type: string
          minLength: 7
          maxLength: 32
          description: US phone number. Normalized to E.164.
        recipient_type:
          type: string
          enum:
            - client
            - witness
            - adjuster
            - business_office
            - other
          description: >-
            Required without `agent_id`; with it, defaults to the saved agent's.
            `witness` is off unless Lawtte enables it.
        consent_confirmed:
          type: boolean
          description: >-
            `true` means this person gave the firm this number and agreed to be
            called. `false` is refused.
        represented_by_counsel:
          type: boolean
          description: >-
            `true` if this person has their own lawyer for this matter. `true`
            is refused.
        objective:
          type: string
          minLength: 1
          maxLength: 1000
          description: >-
            What the call should accomplish. Required without `agent_id`; not
            allowed with it.
        agent_id:
          type: string
          format: uuid
          description: A saved outbound agent to run (see Agents).
        fields:
          type: object
          propertyNames:
            pattern: ^[a-z][a-z0-9_]{0,29}$
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 200
          description: >-
            Values for the saved agent's `{{placeholders}}`. Only with
            `agent_id`.
        context:
          type: string
          maxLength: 1000
          description: >-
            Brief, non-sensitive background. No SSNs, card or bank numbers,
            dates of birth, passwords, codes or medical details.
      example:
        name: Jane Doe
        phone: '+12125550100'
        recipient_type: client
        consent_confirmed: true
        represented_by_counsel: false
        objective: Confirm Jane received the settlement paperwork.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - insufficient_scope
                - invalid_request
                - not_found
                - rejected
                - rate_limited
                - unavailable
                - internal_error
            message:
              type: string
  securitySchemes:
    connectorKey:
      type: http
      scheme: bearer
      description: >-
        A connector key from **Settings → AI connectors → Connector keys**:
        `Authorization: Bearer lawtte_sk_…`.

````

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