---
title: "Cancel all outstanding outreaches for a patient"
method: POST
path: "/api/v1/outreach/cancel"
tags: ["Outreach Management API"]
---

# Cancel all outstanding outreaches for a patient

`POST /api/v1/outreach/cancel`

## 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/outreach/cancel`
- Auth: HTTP bearer

Cancel all outstanding outreaches for a patient identified by external_contact_id.

**Authentication:**
This endpoint supports dual authentication methods:
- **Auth0 JWT Bearer Token**: For partners using Auth0 authentication
  - Header: `Authorization: Bearer <JWT_TOKEN>`
  - Token must include `partner_id` claim
  - Token is validated for signature, expiration, issuer, and audience

- **Verification Token**: For partners using legacy authentication
  - Header: `verification-token: <ENCRYPTED_TOKEN>`
  - Token format: `partner_id:verification_token` (encrypted)
  - Validated against partner credentials

Your partner account is configured for one of these methods. Please use the authentication method assigned to your account.
If you attempt to use the wrong method, you will receive a 401 Unauthorized error.

**Behavior:**
All active outreaches for the patient are cancelled in a single request.
The response includes the list of cancelled outreach IDs and their updated status.

**Response Codes:**
- `200 OK`: Successfully cancelled one or more outreaches
- `404 Not Found`: Patient not found OR no outstanding outreaches found
- `401 Unauthorized`: Authentication failed or wrong authentication method used
- `500 Internal Server Error`: Server error during processing

**Request Body:**
```json
{
    "external_contact_id": "MRN123456",
    "reason": "Patient requested cancellation"  // Optional
}
```

**Success Response (200):**
```json
{
    "version": "1.0",
    "status": "success",
    "message": "Successfully cancelled 2 outreach(es)",
    "cancelled_outreaches": [
        {"outreach_id": "uuid-1", "status": "archived"},
        {"outreach_id": "uuid-2", "status": "archived"}
    ],
    "patient_id": "patient-uuid"
}
```

**Error Response (404):**
```json
{
    "detail": "No outstanding outreaches found for patient"
}
```

## Request body

- OutreachCancelRequest: Request schema for outreach cancellation
  - `external_contact_id` string, required: External contact ID (MRN)
  - `reason` string, nullable: Reason for cancellation

## Response `200`

Successful Response

- OutreachCancelResponse: Response schema for outreach cancellation API
  - `version` string: API version
  - `status` string, required: Overall status: 'success', 'not_found', or 'error'
  - `message` string, required: Human-readable status message
  - `cancelled_outreaches` OutreachInfo[], nullable: List of cancelled outreaches
    - `outreach_id` string, required: Unique outreach identifier
    - `status` string, required: New status of the outreach
  - `patient_id` string, nullable: HAI patient ID (for debugging)

## Other responses

- `422`: Validation 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)