---
title: "Submit patient demographic and scheduling data"
method: POST
path: "/api/v1/contacts"
tags: ["Partner API v1"]
---

# Submit patient demographic and scheduling data

`POST /api/v1/contacts`

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

Submit patient demographic and scheduling data.

**Enhanced Functionality:**
This endpoint now supports combined payloads including:
- Contact data (required)
- Medications data (optional)
- Outreach data (optional)
- Related persons data (optional) — list of people associated with the patient (e.g., emergency contacts, caregivers)

All processing is synchronous - responses are returned immediately without waiting for pipeline processing.

**Data Processing:**
Submitted patient data is fully processed and validated before a response is returned.
If any step of patient data processing fails, the contact will be marked as failed in the response.

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

**Response Codes:**
- `201 Created`: Successfully processed contact data (contact-only requests)
- `200 OK`: Successfully processed combined payload (contact + medications/outreach)
- `207 Multi-Status`: Partially successful (some contacts/medications/outreach failed)
- `401 Unauthorized`: Authentication failed or wrong authentication method used
- `400 Bad Request`: Invalid request payload
- `500 Internal Server Error`: Server error during processing

## Request body

- ContactsBundleRequest: Request schema for combined contacts with medications and outreach
  - `contacts` ContactWithMedicationAndOutreach[], required: List of contacts with optional medications and outreach
    - `mrn` string, required: Medical record number (MRN)
    - `first_name` string, required: First name of the patient
    - `middle` string, nullable: Middle name of the patient
    - `last_name` string, required: Last name of the patient
    - `date_of_birth` string, nullable: Patient's date of birth (YYYY-MM-DD). Required unless outreach_name is 'Diabetes Chat'
    - `next_call_date` string, nullable: Patient's next call date (YYYY-MM-DD)
    - `gender` string, nullable: Patient's gender (male, female, other). Required unless outreach_name is 'Diabetes Chat'
    - `phone_number` string, nullable: Patient's phone number (E.164 format recommended). Required unless outreach_name is 'Diabetes Chat'
    - `do_not_call` boolean, nullable: Indicates if the patient should not be contacted. Explicit true/false indicates that a patient should/should not be DNC'd.
    - `is_deleted` boolean, nullable: Indicates if the patient record should be marked as archived. If true, sets entity_status='archived'. If false or not provided, sets entity_status='active'.
    - `deceased_boolean` boolean, nullable: Indicates the patient is deceased. If true, marks the patient deceased and sets entity_status='archived'. Once a patient is marked deceased, ICE will not allow reverting to non-deceased via this field. If false or not provided, no change is applied.
    - `provider_name` string, nullable: Name of the primary care provider
    - `preferred_language` string, nullable: Preferred language code (ISO 639-1)
    - `timezone` string, nullable: Patient's timezone (IANA format)
    - `outreach_name` string, required: Type of outreach for this patient
    - `additional_info` object, nullable: Additional information about the patient in JSON format
    - `address_line1` string, nullable: Address line 1 (Street and number)
    - `address_line2` string, nullable: Address line 2 (Additional street details)
    - `city` string, nullable: City of residence
    - `state` string, nullable: State code (US State Abbreviations)
    - `country` string, nullable: Country of residence
    - `postal_code` string, nullable: Postal or ZIP code
    - `procedure_code` string, nullable: CPT code representing the upcoming procedure
    - `procedure_date` string, date-time, nullable: Date and time of the procedure
    - `procedure_type` string, nullable: Description of the procedure
    - `procedure_site` string, nullable: Site where the procedure will be performed
    - `discharge_date` string, date-time, nullable: Date of patient discharge (if applicable)
    - `upcoming_procedure_reason` string, nullable: The reason for the procedure
    - `upcoming_procedure_arrival_buffer` string, nullable: Time patient should arrive before procedure start
    - `upcoming_procedure_arrival_location` string, nullable: Arrival location for procedure
    - `upcoming_procedure_prep` string, nullable: Preparation instructions for procedure
    - `upcoming_procedure_required_clearances` string, nullable: Required clearances for the upcoming procedure
    - `upcoming_procedure_address` string, nullable: Address for the upcoming procedure
    - `upcoming_procedure_date` string, date-time, nullable: Date and time of upcoming procedure
    - `upcoming_procedure_type` string, nullable: Type of upcoming procedure
    - `upcoming_appointment_date` string, date-time, nullable: Date and time of upcoming appointment
    - `upcoming_appointment_type` string, nullable: Type of upcoming appointment
    - `upcoming_appointment_reason` string, nullable: Reason for upcoming appointment
    - `upcoming_appointment_clinic_name` string, nullable: Clinic name for upcoming appointment
    - `upcoming_appointment_address` string, nullable: Address for upcoming appointment
    - `previous_appointment_date` string, date-time, nullable: Date and time of previous appointment
    - `previous_appointment_type` string, nullable: Type of previous appointment
    - `previous_appointment_clinic_name` string, nullable: Clinic name of previous appointment
    - `care_location_slug` string, nullable: Care location slug for primary care location
    - `related_persons` RelatedPerson[], nullable: List of related persons associated with the patient (e.g., emergency contacts, caregivers)
      - `first_name` string, nullable: First name of the related person
      - `last_name` string, nullable: Last name of the related person
      - `datetime` RelatedPersonDatetime: Datetime range for the related person relationship.
        - `start` string, nullable: Start date/time of the relationship
        - `end` string, nullable: End date/time of the relationship
        - `timezone` string, nullable: Timezone for the datetime values
      - `is_primary_contact` boolean, nullable: Indicates if this is the primary contact person
      - `relationship_type` string, nullable: Type of relationship role (e.g., guardian, caregiver, emergency contact)
      - `personal_relation` string, nullable: Personal relation to the patient (e.g., spouse, parent, child, caregiver)
    - `medications` SrcExternalApiSchemasProductV1ContactsMedicationRequest[], nullable: List of medications for this patient
      - `medication_name` string, required: Name of the medication
      - `dosage` string, nullable: Dosage information
      - `frequency` string, nullable: Frequency of medication
      - `start_date` string, nullable: Start date of medication (YYYY-MM-DD)
      - `prescriber_name` string, nullable: Name of the prescriber
    - `outreach` OutreachRequest: Schema for outreach data within contact
      - `campaign_id` string, required: Campaign ID for the outreach
      - `scheduled_at` string, required: ISO datetime string - must be at least 1 hour in the past and at most 48 hours in the future
      - `expires_at` string, required: ISO datetime string - must be at least 1 hour in the future
      - `action` 'create' | 'cancel', nullable: Action to perform: create or cancel
      - `reason` string, nullable: Reason for cancellation (if action is cancel)
      - `dry_run` boolean, nullable: Dry run mode

## Response `200`

Successful Response

- unknown

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