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

# Create a receptionist task

> Adds a task to the AI Receptionist inbox, as staff do with New task. `status` defaults to `todo`. `patient_id`, `linked_call_id` and `assigned_provider_calendar_id` must belong to your organization (404 otherwise). Requires the receptionist:write scope.

| Requirement | Detail |
| - | - |
| **Scope** | `receptionist:write` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!NOTE]
>
> **Safety**
>
> * **Writes data:** Yes. Adds a task to the AI Receptionist inbox in HealOS. It is not sent to your EHR.
> * **Safe to retry:** Only with an `Idempotency-Key` header: a repeat with the same key returns the first task instead of a second one. Without it, a retry creates a second task.
> * **Contacts an outside system:** None
> * **Dry run:** Not available.

> [!NOTE]
>
> Rolling out: this endpoint is on staging first and not yet on `api.healos.ai`.

The task appears in the dashboard inbox like one staff created (`source` is `manual`). `status` defaults to `todo`.

`patient_id`, `linked_call_id` and `assigned_provider_calendar_id` must belong to your organization; any other id is a `404` and no task is created. A call that staff removed from Call History cannot be linked.

Guide: [Calls and inbox](https://docs.healos.ai/guides/receptionist/calls-and-inbox.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json POST /receptionist/tasks
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /receptionist/tasks:
    post:
      tags:
        - Receptionist
      summary: Create a receptionist task
      description: >-
        Adds a task to the AI Receptionist inbox, as staff do with New task.
        `status` defaults to `todo`. `patient_id`, `linked_call_id` and
        `assigned_provider_calendar_id` must belong to your organization (404
        otherwise). Requires the receptionist:write scope.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: >-
              Up to 255 printable ASCII characters. Use a new random value (a
              UUID) for each new request and resend the same value when you
              retry it.
            example: 5f0c3a8e-2b7d-4c1e-9a64-0d3f2e1b7c90
          required: false
          name: Idempotency-Key
          in: header
          description: >-
            Makes a retry of this request safe. A repeat with the same key and
            the same request within 24 hours does not run again: it returns the
            original status with the resource as it is now, and an
            `Idempotent-Replayed: true` header. Keys are scoped to your
            organization and API key. See https://docs.healos.ai/idempotency.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceptionistTaskCreate'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceptionistTaskResponse'
          headers:
            Idempotent-Replayed:
              description: >-
                `true` when this response is a replay of an earlier request with
                the same `Idempotency-Key`.
              schema:
                type: string
                enum:
                  - 'true'
        '400':
          description: >-
            Validation error: a blank or overlong title, an unknown field,
            category or status, or a malformed id or date; or `Idempotency-Key`
            is empty, longer than 255 characters or not printable ASCII
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/IdempotencyError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs receptionist:write)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The patient, call or provider calendar is not your organization's
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            A request with this `Idempotency-Key` is still being processed
            (`idempotency_in_progress`; retry after `Retry-After`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyError'
        '422':
          description: >-
            This `Idempotency-Key` was already used for a different request
            (`idempotency_key_reused`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdempotencyError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    ReceptionistTaskCreate:
      type: object
      properties:
        title:
          type: string
          maxLength: 500
          example: Call back about a refill request
        category:
          type: string
          nullable: true
          enum:
            - action
            - communicate
            - coordinate
            - document
            - order
            - call_followup
            - billing
            - insurance
            - refill
            - records
            - referral
            - appointment
          description: >-
            One of: action, communicate, coordinate, document, order,
            call_followup, billing, insurance, refill, records, referral,
            appointment.
          example: refill
        status:
          type: string
          enum:
            - todo
            - done
            - archived
          description: >-
            `todo` (open), `done` (resolved) or `archived` (hidden from the
            default inbox view).
          example: todo
        notes:
          type: string
          nullable: true
          maxLength: 10000
          example: Caller asked for a 90-day supply.
        due_date:
          type: string
          nullable: true
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-10-30'
        patient_id:
          type: string
          nullable: true
          pattern: ^\d{1,19}$
          description: >-
            A patient in your organization (GET /patients). Another
            organization's patient is a 404.
          example: '700000000000000001'
        patient_label:
          type: string
          nullable: true
          maxLength: 300
          description: The patient name the inbox row shows.
          example: Pat Example
        assigned_provider_calendar_id:
          type: string
          nullable: true
          pattern: ^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$
          description: >-
            Assign the task to one of your organization's AI Receptionist
            provider calendars.
        linked_call_id:
          type: string
          nullable: true
          pattern: ^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$
          description: >-
            The call this task came from (GET /receptionist/calls). Another
            organization's call is a 404.
          example: c0a80101-0000-4000-8000-000000000001
      required:
        - title
      additionalProperties: false
    ReceptionistTaskResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ReceptionistTask'
      required:
        - data
    ValidationError:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - error
    IdempotencyError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
            - idempotency_key_invalid
            - idempotency_in_progress
            - idempotency_key_reused
            - idempotency_resource_gone
      required:
        - error
        - code
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    ReceptionistTask:
      type: object
      properties:
        id:
          type: string
          example: 7a5c0000-0000-4000-8000-000000000001
        title:
          type: string
        category:
          type: string
          nullable: true
        status:
          type: string
          example: todo
        source:
          type: string
          description: >-
            `manual` (created by staff or the API), `call` (created from a call)
            or `system`.
          example: call
        notes:
          type: string
          nullable: true
        due_date:
          type: string
          nullable: true
          example: '2026-10-30'
        patient_id:
          type: string
          nullable: true
        patient_label:
          type: string
          nullable: true
        assigned_provider_calendar_id:
          type: string
          nullable: true
        linked_call_id:
          type: string
          nullable: true
        caller_phone:
          type: string
          nullable: true
          description: >-
            The number the linked call came from, for a call back. Null without
            a phone call.
          example: '+15555550100'
        ehr_source:
          type: string
          nullable: true
          description: The EHR the organization had connected when the task was created.
        created_at:
          type: string
          example: '2026-10-27T14:07:50.000Z'
        updated_at:
          type: string
          example: '2026-10-27T14:08:02.000Z'
      required:
        - id
        - title
        - category
        - status
        - source
        - notes
        - due_date
        - patient_id
        - patient_label
        - assigned_provider_calendar_id
        - linked_call_id
        - caller_phone
        - ehr_source
        - created_at
        - updated_at
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

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