---
title: "Submit outreach task bundles"
method: POST
path: "/api/v1/tasks"
tags: ["Partner API v1"]
---

# Submit outreach task bundles

`POST /api/v1/tasks`

## Request

- Base URL: `https://api.hippocraticai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.hippocraticai.com/api/v1/tasks`
- Auth: HTTP bearer

Submit a batch of outreach task bundles.

Each item in the batch defines three things:
- **`target`** — who the AI agent will contact (Patient, Practitioner, etc.)
- **`focus`** — the reason for the outreach (Appointment, MedicationRequest, Encounter, etc.) — optional
- **`task`** — when and how to run the outreach (timing, priority, classification)

Up to **10 items** can be submitted per request. Each item is processed independently —
one failure does not cancel other items in the batch.

---

### `target` and `focus` — resource actions

Both `target` and `focus` use the same `TaskResource` shape with an explicit `action` field:

```json
{
  "resource_type": "Patient",
  "action": "upsert",
  "data": { ... }
}
```

**`action="upsert"`** — HAI creates or updates the resource using the fields in `data`.
Use this when sending a new or updated record. All required fields for the resource type must be present.

**`action="reference"`** — HAI looks up an existing resource by its lookup key only.
Use this when the resource already exists and no update is needed.
`data` must contain only the lookup key (e.g. `mrn` for Patient, `npi` for Practitioner).
Returns `status=failed` for that item if the resource is not found.

---

### Required `data` fields per resource type

| resource_type | action=upsert (required) | action=reference (lookup key) |
|--------------|--------------------------|-------------------------------|
| `Patient` | `mrn`, `first_name`, `last_name` | `mrn` |
| `Practitioner` | `npi`, `provider_name` | `npi` |
| `Appointment` | `appointment_id`, `start` | `appointment_id` |
| `Encounter` | `encounter_id` | `encounter_id` |
| `MedicationRequest` | `rx_number`, `medication_name` | `rx_number` |

Additional optional fields (e.g. `dob`, `phone`, `email`, `gender` for Patient;
`provider_name` for Appointment) are accepted and stored when provided. GET Appointment
returns `provider_name` from the stored participant display.

---

### `task` fields

| field | required | description |
|-------|----------|-------------|
| `external_id` | yes | Your unique identifier for this task. Submitting the same `external_id` again returns `status=duplicate` and **refreshes** the target/`for`/`focus` resources (re-upsert + SNOW sync) against the existing task — no new task is created. A transient SNOW failure during that refresh surfaces as `failed` (retryable with the same `external_id`), not `duplicate`. |
| `task_tag` | yes | Classification / reason code (e.g. `pre_appointment_reminder`, `medication_adherence_followup`). |
| `task_group` | no | Optional batch or campaign identifier for grouping tasks. |
| `priority` | no | `routine` (default) \| `urgent` \| `asap` \| `stat` |
| `requested_start` | no | ISO 8601 UTC — earliest time to begin outreach. |
| `requested_end` | no | ISO 8601 UTC — hard cutoff after which outreach will not be attempted. |
| `timezone` | no | IANA timezone string (e.g. `America/New_York`). Used to apply local calling hours. |
| `additional_info` | no | Free-form JSON object for any partner-specific context you want stored on the task. |

---

### Batch response

The top-level `status` summarises the entire batch:

| status | meaning |
|--------|---------|
| `SUCCESS` | All items have status `created` or `duplicate` |
| `PARTIAL_SUCCESS` | Mix of successful and failed items |
| `FAILURE` | All items failed |

Each item is processed **atomically** — every resource it touches (target, `for`, each
`focus[]`, and the task) is written in a single transaction and committed only after the
downstream SNOW sync succeeds. If anything fails (validation, DB, or SNOW sync), the whole
item is rolled back — **nothing is persisted** — and it is reported as `failed`. Retry the
full payload; resubmission is idempotent via `external_id`.

Each item in `results` carries its own `status`:

| per-item status | meaning |
|-----------------|---------|
| `created` | Task (and all its resources) successfully created and synced |
| `duplicate` | A task with this `external_id` already exists — the task is not re-created, but its `target`/`for`/`focus` resources are refreshed (re-upsert + SNOW sync). A transient SNOW failure during the refresh returns `failed` (retryable with the same `external_id`). |
| `failed` | Validation error, resource not found, or a downstream failure — the item was rolled back (nothing persisted); see `error` field. Retry the full payload. |

---

### HTTP response codes

| code | when |
|------|------|
| `200 OK` | All items resolved to `created` or `duplicate` |
| `207 Multi-Status` | Mix of item statuses (at least one `failed`) |
| `400 Bad Request` | Request body is empty |
| `401 Unauthorized` | Missing or invalid authentication token |
| `422 Unprocessable Entity` | Request body fails schema validation (missing required field, wrong type) |
| `500 Internal Server Error` | Unexpected server error |

## Request body

- TaskItem[]
  - `target` TaskResource, required: Generic polymorphic resource reference — used for both target and focus. action="upsert": ICE creates or updates the resource. `data` must contain all required fields for that resource_type (validated by the processor). action="reference": ICE looks up an existing resource by its lookup key. `data` must contain only the lookup key for that resource_type. Fails with status=failed if the resource is not found.
    - `resource_type` string, required: FHIR resource type: Patient | Practitioner | Appointment | Encounter | MedicationRequest | Condition | ...
    - `action` 'upsert' | 'reference', required: Action to perform on a resource when processing a task bundle. UPSERT — create or update the resource using fields in data. REFERENCE — look up an existing resource by its lookup key only.
    - `data` object, required: Resource fields. Required fields depend on resource_type and action. For action=upsert, must include all required fields for that resource_type. For action=reference, must include only the lookup key (e.g. mrn for Patient, npi for Practitioner, appointment_id for Appointment).
  - `for` TaskResource: Generic polymorphic resource reference — used for both target and focus. action="upsert": ICE creates or updates the resource. `data` must contain all required fields for that resource_type (validated by the processor). action="reference": ICE looks up an existing resource by its lookup key. `data` must contain only the lookup key for that resource_type. Fails with status=failed if the resource is not found.
    - `resource_type` string, required: FHIR resource type: Patient | Practitioner | Appointment | Encounter | MedicationRequest | Condition | ...
    - `action` 'upsert' | 'reference', required: Action to perform on a resource when processing a task bundle. UPSERT — create or update the resource using fields in data. REFERENCE — look up an existing resource by its lookup key only.
    - `data` object, required: Resource fields. Required fields depend on resource_type and action. For action=upsert, must include all required fields for that resource_type. For action=reference, must include only the lookup key (e.g. mrn for Patient, npi for Practitioner, appointment_id for Appointment).
  - `focus` TaskResource[], nullable: Clinical resources the call is about (list; e.g. Appointment, MedicationRequest)
    - `resource_type` string, required: FHIR resource type: Patient | Practitioner | Appointment | Encounter | MedicationRequest | Condition | ...
    - `action` 'upsert' | 'reference', required: Action to perform on a resource when processing a task bundle. UPSERT — create or update the resource using fields in data. REFERENCE — look up an existing resource by its lookup key only.
    - `data` object, required: Resource fields. Required fields depend on resource_type and action. For action=upsert, must include all required fields for that resource_type. For action=reference, must include only the lookup key (e.g. mrn for Patient, npi for Practitioner, appointment_id for Appointment).
  - `task` TaskMeta, required: Task definition — controls outreach timing and classification.
    - `external_id` string, required: Partner-supplied task identifier (unique per partner)
    - `task_tag` string, required: Task classification / reason code (e.g. pre_appointment_reminder)
    - `task_group` string, nullable: Batch / campaign group identifier
    - `priority` string, nullable: FHIR RequestPriority: routine | urgent | asap | stat
    - `requested_start` string, nullable: ISO 8601 UTC — earliest time to begin outreach
    - `requested_end` string, nullable: ISO 8601 UTC — hard cutoff / expiration for outreach
    - `timezone` string, nullable: IANA timezone
    - `hippocratic_care_location_id` string, nullable: Hippocratic care-location id. Not the ICE row UUID.
    - `additional_info` object, nullable: Free-form partner-specific context stored on the task

## Response `200`

All items processed successfully (all `created` or `duplicate`)

- TaskResponse: Batch response — overall status + per-item results.
  - `status` string, required
  - `trace_id` string, required
  - `results` TaskItemResult[], required
    - `external_id` string, required
    - `task_id` string, nullable
    - `target_id` string, nullable
    - `focus_id` string, nullable
    - `status` string, required
    - `error` string, nullable

## Other responses

- `207`: Mix of outcomes across items — check per-item `status`
- `400`: Empty request body
- `401`: Missing or invalid authentication token
- `422`: Request schema validation failed — required field missing or wrong type
- `500`: Unexpected server error

---

[API](https://skmtc.dev/hippocraticai/apis/hippocratic-ai-agent-api-suite.md) - [All operations](https://skmtc.dev/hippocraticai/apis/hippocratic-ai-agent-api-suite/llms.txt) - [OpenAPI document](https://skmtc.dev/hippocraticai/apis/hippocratic-ai-agent-api-suite/revisions/c2472c92766c?raw)