---
title: "Submit appointment scheduling data for a patient"
method: POST
path: "/api/v1/appointments"
tags: ["Partner API v1"]
---

# Submit appointment scheduling data for a patient

`POST /api/v1/appointments`

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

Submit appointment scheduling data for a patient.

Use this endpoint to send upcoming, previous, or procedure-related appointment details
for a patient identified by MRN. The patient must already exist via a prior `/contacts` submission.

**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 appointment data
- `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

- AppointmentRequest: Main request body for appointments API
  - `contact` ContactInfo, required: Contact demographic information for validation - only MRN is mandatory
    - `mrn` string, required: Medical Record Number (mandatory)
    - `first_name` string, nullable: Contact first name (optional)
    - `last_name` string, nullable: Contact last name (optional)
    - `date_of_birth` string, nullable: Contact date of birth in YYYY-MM-DD format (optional)
    - `additional_info` object, nullable: Additional contact information as key-value pairs. Will be stored in FHIR extension format with url and valueString.
  - `appointments` Appointment[], required: List of appointments (1-100)
    - `appointment_id` string, required: Unique external appointment ID
    - `appointment_date` string, required: Appointment start date/time in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
    - `appointment_end_date` string, nullable: Appointment end date/time in ISO 8601 format
    - `appointment_reason` string, nullable: Reason for appointment
    - `appointment_type` string, nullable: Type of appointment (e.g., Routine, Follow-up)
    - `appointment_status` string, nullable: FHIR appointment status
    - `appointment_location_name` string, nullable: Name of appointment location
    - `appointment_location_address` AppointmentAddress: Address information for appointment location
      - `line1` string, nullable: Address line 1
      - `line2` string, nullable: Address line 2
      - `city` string, nullable: City
      - `state` string, nullable: State
      - `zip` string, nullable: ZIP/Postal code
      - `country` string, nullable: Country, defaults to US
    - `appointment_notes` string, nullable: Additional notes for appointment

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