---
title: "Create direct outreach for a campaign"
method: POST
path: "/api/v1/outreach/create"
tags: ["Outreach Management API"]
---

# Create direct outreach for a campaign

`POST /api/v1/outreach/create`

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

Create direct outreach for a campaign for a patient identified by contact_id (MRN).

**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.

**Scheduling Rules:**
- `scheduled_at`: Optional — defaults to now + 10 minutes. Must be at most 48 hours in the future and no more than 1 hour in the past.
- `expires_at`: Optional — defaults to now + 48 hours. Must be at least 1 hour in the future and after `scheduled_at`.

**Response Codes:**
- `201 Created`: Successfully created outreach
- `400 Bad Request`: Validation error (invalid datetime, expires before scheduled, etc.)
- `404 Not Found`: Patient not found with the provided contact_id
- `401 Unauthorized`: Authentication failed or wrong authentication method used
- `500 Internal Server Error`: Server error during processing

**Request Body:**
```json
{
    "contact_id": "MRN123456",                    // Required: MRN
    "campaign_id": "campaign-uuid-789",           // Required: Campaign UUID
    "scheduled_at": "2025-01-15T10:00:00Z",      // Optional: ISO datetime (defaults to now + 10 min)
    "expires_at": "2025-01-17T10:00:00Z",         // Optional: ISO datetime (defaults to now + 48 hours)
    "dry_run": false                              // Optional: Test mode without creating outreach
}
```

**Success Response (201):**
```json
{
    "status": "success",
    "message": "Successfully created outreach for campaign",
    "outreach_id": "outreach-uuid-123"
}
```

**Validation Error Response (400):**
```json
{
    "detail": "scheduled_at must be at least 1 hour in the past"
}
```

**Patient Not Found Response (404):**
```json
{
    "detail": "No patient found with contact_id: MRN123456"
}
```

## Request body

- OutreachCreateRequest: Request schema for creating outreach for campaign
  - `contact_id` string, required: Patient MR (Medical Record Number) - stored in identifier_value where identifier_type='MR'
  - `campaign_id` string, required: Campaign ID
  - `scheduled_at` string, nullable: ISO datetime string - must be at least 1 hour in the past and at most 48 hours in the future. Defaults to 10 minutes from now if not provided
  - `expires_at` string, nullable: ISO datetime string - defaults to 48 hours from now if not provided
  - `dry_run` boolean, nullable: Dry run mode

## Response `200`

Successful Response

- OutreachCreateResponse: Response schema for outreach creation API
  - `status` string, required: Overall status: 'success' or 'error'
  - `message` string, required: Human-readable status message
  - `outreach_id` string, nullable: Created outreach ID

## 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)