> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Patient
> Creates a patient. `id`, `first_name`, and `last_name` are required; all other fields are optional.
## Overview
Creates a patient record. `id`, `first_name`, and `last_name` are required; all
other fields are optional.
`id` is the patient's external id, the same identifier used by the professional claim endpoints, so a patient
created here can be reused in later claim submissions.
This endpoint manages **demographic** data only. Insurance/policy data is not
accepted — a body containing a `policies` field (or any unknown field) is
rejected with a `400`.
## Authentication
JWT Bearer token from `/api/token`.
## Request Body
External patient id.
Patient's first name.
Patient's last name.
Patient's full name.
One of `male`, `female`, `other`, or `unknown`.
Date of birth in `yyyy-MM-dd` format.
Patient email address.
Patient phone number.
Patient address with `line1`, `line2`, `city`, `state`, `zip`, and `country`.
## Example
```bash theme={null}
curl -X POST "https://forecaster.cairhealth.com/api/patient" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "EXT-PAT-123",
"first_name": "Jane",
"last_name": "Doe",
"gender": "female",
"dob": "1990-01-02",
"email": "jane@example.com",
"phone_number": "555-1234",
"address": {
"line1": "1 Main St",
"city": "Springfield",
"state": "IL",
"zip": "62704",
"country": "US"
}
}'
```
## Response
```json theme={null}
{
"success": true,
"message": "Patient created successfully",
"data": {
"patientId": "EXT-PAT-123",
"patientFhirId": "fhir-patient-id"
}
}
```
Returns `409 Conflict` when a patient with the same `id` already exists. Use
`PUT /api/patient/{patientId}` to update an existing patient.
## OpenAPI
````yaml POST /api/patient
openapi: 3.1.0
info:
title: Cair Health APIs
description: APIs for the Cair Health platform
license:
name: MIT
version: 1.0.0
servers:
- url: https://forecaster.cairhealth.com
security:
- bearerAuth: []
paths:
/api/patient:
post:
description: >-
Creates a patient. `id`, `first_name`, and `last_name` are required; all
other fields are optional.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatientCrudRequest'
responses:
'201':
description: Patient created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PatientCrudResponse'
'400':
description: Invalid request body or validation error
'401':
description: Unauthorized access or invalid organization ID
'404':
description: Organization or patient not found
'409':
description: Patient already exists
'500':
description: Server error
security:
- bearerAuth: []
components:
schemas:
PatientCrudRequest:
type: object
description: >-
Patient demographics. `id` is the external patient id, keyed by the Cair
customer-patient-id naming system
(https://fhir.cairhealth.com/fhir/identifier/customer-patient-id)
properties:
id:
type: string
description: External patient id
first_name:
type: string
description: Patient's first name
last_name:
type: string
description: Patient's last name
name:
type: string
nullable: true
description: Patient's full name
gender:
type: string
nullable: true
enum:
- male
- female
- other
- unknown
description: Patient gender
dob:
type: string
nullable: true
description: Date of birth, yyyy-MM-dd
email:
type: string
nullable: true
description: Patient email address
phone_number:
type: string
nullable: true
description: Patient phone number
address:
type: object
description: Patient address
properties:
city:
type: string
nullable: true
description: City
country:
type: string
nullable: true
description: Country
line1:
type: string
nullable: true
description: Address line 1
line2:
type: string
nullable: true
description: Address line 2
state:
type: string
nullable: true
description: State
zip:
type: string
nullable: true
description: Postal code
required:
- id
- first_name
- last_name
additionalProperties: false
PatientCrudResponse:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
properties:
patientId:
type: string
description: External patient id
patientFhirId:
type: string
description: FHIR id of the Patient resource
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.