> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Patient
> Creates a new patient record.
### Provider IDs for Referrals
When creating patients with referral information, use the **`ehr_id`** value from providers:
* **`referred_to_provider_id`** (optional): Use the `ehr_id` from `GET /v1/providers` (not the `id`)
This value represents the rendering provider identifier your EMR system uses. Cobalt passes it directly to your EMR when creating the patient record.
**Don't use the Cobalt `id` here.** The `id` field from GET responses is Cobalt's internal UUID, used only for updating provider settings via PATCH endpoints.
### Referring Provider and PCP Options
When creating a patient, you can specify the referring provider and PCP (Primary Care Provider) using either names or provider IDs:
#### Option 1: Provider Names (All EMRs)
Provide the provider's first and last name:
```json theme={null}
{
"referring_provider_first_name": "John",
"referring_provider_last_name": "Smith",
"pcp_first_name": "Jane",
"pcp_last_name": "Doe"
}
```
#### Option 2: Provider IDs (eClinicalWorks Only)
Provide a Cobalt `id` (UUID, with or without dashes). This option:
* Automatically looks up the provider's name, phone, and fax
* Provides more accurate matching by validating contact information in the EMR
* Falls back to using provided names if the ID is not found
The accepted source depends on the field:
* **`referring_provider_id`**: the `id` from `GET /v1/referring-providers`.
* **`pcp_id`**: the `id` from **either** `GET /v1/referring-providers` **or** `GET /v1/providers`. Pass a `/v1/providers` `id` when the patient's PCP is one of the practice's own physicians rather than an external referring provider. Cobalt resolves the UUID against both sets of providers, so you can use whichever endpoint the provider appears in.
```json theme={null}
{
"referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
"pcp_id": "223ecd1b29e546ca9db6b391eb49b213"
}
```
For `pcp_id`, use the `id` field (the Cobalt UUID), not the `ehr_id`. This differs from `referred_to_provider_id`, which expects the `ehr_id` from `GET /v1/providers`.
**EMR Compatibility**: The `referring_provider_id` and `pcp_id` parameters are currently only supported for **eClinicalWorks**. For other EMRs, you must use the name fields (`referring_provider_first_name`, `referring_provider_last_name`, `pcp_first_name`, `pcp_last_name`).
### Responsible Party (eClinicalWorks Only)
By default, the patient is their own responsible party (`responsible_party: "self"`). For minors or patients whose billing is managed by another person, set `responsible_party` to one of the values below and include the guarantor's demographic fields.
When a non-self responsible party is provided alongside insurance, Cobalt will:
1. Create a guarantor record in eCW with the provided demographics
2. Link that guarantor to the insurance record
3. Set the responsible party on the patient
```json theme={null}
{
"responsible_party": "parent",
"responsible_party_first_name": "Jane",
"responsible_party_last_name": "Smith",
"responsible_party_sex": "female",
"responsible_party_dob": "1975-06-15",
"responsible_party_phone": "555-555-1234",
"insurance_name": "Aetna",
"insurance_subscriber_number": "ABC123"
}
```
**Supported values:**
| Value | eCW Code | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `self` | 1 | Patient is the insured |
| `spouse` | 2 | Patient is the spouse of the insured |
| `child` | 3 | Natural Child — insured has financial responsibility |
| `adopted_child` | 4 | Natural Child — insured does not have financial responsibility (includes legally adopted) |
| `step_child` | 5 | Step Child |
| `foster_child` | 6 | Foster Child |
| `ward_of_court` | 7 | Ward of the Court |
| `employee` | 8 | Employee |
| `unknown` | 9 | Unknown / Other relationship |
| `handicapped_dependent` | 10 | Handicapped Dependent |
| `organ_donor` | 11 | Organ Donor |
| `cadaver_donor` | 12 | Cadaver Donor |
| `grandchild` | 13 | Grandchild |
| `niece_nephew` | 14 | Niece/Nephew |
| `injured_plaintiff` | 15 | Injured Plaintiff |
| `sponsored_dependent` | 16 | Sponsored Dependent |
| `minor_dependent` | 17 | Minor Dependent of a Minor Dependent |
| `parent` | 18 | Parent |
| `grandparent` | 19 | Grandparent |
| `life_partner` | 53 | Life Partner |
| `other` | 99 | Other |
`responsible_party_first_name` and `responsible_party_last_name` are required when using a non-self responsible party. The guarantor is created as a separate record in eCW — if a guarantor with those demographics already exists in your instance, a duplicate will be created.
### Registration Fields (eClinicalWorks Only)
Additional demographic and consent fields can be set at patient creation:
| Field | Type | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `language` | string | Preferred language. Must match a valid language name in your eCW instance. |
| `race` | string | Race. Must match a valid race name in your eCW instance. |
| `ethnicity` | string | Ethnicity. Must match a valid ethnicity code or display name in your eCW instance. |
| `release_of_info` | boolean | Consent for release of information. Defaults to `true`. |
| `rx_history_consent` | boolean | Consent for pharmacy history sharing. Defaults to `true`. |
| `self_pay` | boolean | Explicitly marks the patient as self-pay, overriding insurance-derived logic. |
| `default_facility_id` | string | The eCW facility ID to set as the patient's primary service location. |
| `voice_enabled` | boolean | Enables voice (phone) notifications in the eCW Patient Communications settings. Defaults to off. |
| `text_enabled` | boolean | Enables text (SMS) notifications in the eCW Patient Communications settings. Defaults to off. |
```json theme={null}
{
"language": "Spanish",
"race": "White",
"ethnicity": "Hispanic or Latino",
"release_of_info": true,
"rx_history_consent": false,
"default_facility_id": "25",
"voice_enabled": true,
"text_enabled": true
}
```
**Notification language.** When `voice_enabled` or `text_enabled` is set, the notification language in eCW follows the patient's `language`: Spanish when `language` contains "spanish" (case-insensitive), otherwise English. These are the only two options eCW exposes for communication notifications.
### Insurance Options
When creating a patient, you can specify insurance using either the insurance name or an insurance provider ID:
**Option 1: Insurance Name (All EMRs)**
```json theme={null}
{
"insurance_name": "United Healthcare"
}
```
**Option 2: Insurance Provider ID (eClinicalWorks Only)**
Use `insurance_provider_id` from `GET /v1/insurance-providers` (UUID without dashes). This option:
* Automatically looks up the insurance name, address, city, and state
* Provides more accurate matching when there are duplicate insurance names
* Falls back to using provided insurance\_name if the ID is not found
```json theme={null}
{
"insurance_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a"
}
```
### Example Request
#### Basic Request
```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"last_name": "Smith",
"first_name": "John",
"phone": "5551234567",
"dob": "1980-01-01",
"sex": "male"
}'
```
#### With Provider Names
```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"last_name": "Smith",
"first_name": "John",
"phone": "5551234567",
"dob": "1980-01-01",
"sex": "male",
"referring_provider_first_name": "Jane",
"referring_provider_last_name": "Doe",
"pcp_first_name": "Robert",
"pcp_last_name": "Johnson"
}'
```
#### With Provider IDs (eClinicalWorks Only)
```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/patients \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
"last_name": "Smith",
"first_name": "John",
"phone": "5551234567",
"dob": "1980-01-01",
"sex": "male",
"referring_provider_id": "e35e82b85df58f08a9b38e06a91e9f1a",
"pcp_id": "223ecd1b29e546ca9db6b391eb49b213"
}'
```
### Example Response
```json theme={null}
{
"success": true,
"message": "Patient processing. A webhook event will be sent upon completion.",
"patient_id": "9988776655443322"
}
```
### Webhook Notifications
When patient processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:
#### Success
```json theme={null}
{
"id": "evt_pat_succ_g7h8i9",
"access_token_reference_id": "user_pat_ref_k3l4m5",
"object": "event",
"created": "2023-10-29T12:00:00Z",
"type": "patient.created",
"data": {
"patient_id": "9988776655443322",
"mrn": "123456",
"eligibility_information": [
{
"insurance_name": "Aetna",
"status": "Active"
}
] // returned when check_eligibility=true. Availability depends on EHR support.
}
}
```
#### Failure Examples
The `patient.failed` webhook event includes a `failure_reason` and may contain additional fields in the `data` object depending on the cause of the failure.
**Duplicate Patient:**
```json theme={null}
{
"id": "evt_pat_fail_dup_p2q3r4",
"access_token_reference_id": "user_pat_ref_k3l4m5",
"object": "event",
"created": "2023-10-29T12:05:00Z",
"type": "patient.failed",
"data": {
"patient_id": "9988776655443322",
"failure_reason": "Duplicate patient found. Please use the existing patient or update the patient information using the PATCH /v1/patients/:id endpoint.",
"existing_mrn": "654321"
}
}
```
**Referring Provider Not Found:**
```json theme={null}
{
"id": "evt_pat_fail_ref_s5t6u7",
"access_token_reference_id": "user_pat_ref_k3l4m5",
"object": "event",
"created": "2023-10-29T12:10:00Z",
"type": "patient.failed",
"data": {
"patient_id": "9988776655443323",
"failure_reason": "No valid referring provider found. Please update the referring provider using the PATCH /v1/patients/:id endpoint."
}
}
```
**PCP Not Found:**
```json theme={null}
{
"id": "evt_pat_fail_pcp_y1z2a3",
"access_token_reference_id": "user_pat_ref_k3l4m5",
"object": "event",
"created": "2023-10-29T12:12:00Z",
"type": "patient.failed",
"data": {
"patient_id": "9988776655443325",
"failure_reason": "No valid PCP provider found. Please update the PCP provider using the PATCH /v1/patients/:id endpoint."
}
}
```
**Insurance Not Found:**
```json theme={null}
{
"id": "evt_pat_fail_ins_v8w9x0",
"access_token_reference_id": "user_pat_ref_k3l4m5",
"object": "event",
"created": "2023-10-29T12:15:00Z",
"type": "patient.failed",
"data": {
"patient_id": "9988776655443324",
"failure_reason": "No valid insurance found. Please update the insurance using the PATCH /v1/patients/:id endpoint."
}
}
```
Patient creation is asynchronous. Store the returned patient\_id and listen for webhooks to determine the final status.
## OpenAPI
````yaml POST /patients
openapi: 3.0.0
info:
title: Cobalt API
version: 1.0.1
description: API for interacting with Cobalt's EHR integration services
servers:
- url: https://api.usecobalt.com/v1
security:
- ClientCredentials: []
ClientSecret: []
AccessToken: []
paths:
/patients:
post:
summary: Create Patient
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
address_city:
type: string
address_line2:
type: string
description: Address line 2 (apartment, suite, unit, etc.)
address_state:
type: string
address_street:
type: string
address_zip:
type: string
cell_phone:
type: string
check_eligibility:
type: string
enum:
- 'true'
- 'false'
default: 'false'
description: Whether to check insurance eligibility for the patient
dob:
type: string
email:
type: string
description: Patient email address
no_email_reason:
type: string
description: >-
Reason why email was not provided. Can be used instead of
email when email is required. Only available for certain
EMRs.
emergency_contact_first_name:
type: string
emergency_contact_last_name:
type: string
emergency_contact_phone:
type: string
emergency_contact_relation:
type: string
first_name:
type: string
group_number:
type: string
description: >-
Insurance group number. Currently only used for Greenway,
where it is required alongside plan_code and
insurance_policy_type when attaching insurance.
insurance_name:
type: string
insurance_provider_id:
type: string
description: >-
The id of an insurance provider from GET
/v1/insurance-providers (UUID without dashes). Can be used
instead of insurance_name for enhanced matching. Currently
only supported for eClinicalWorks.
insurance_sequence:
type: string
enum:
- primary
- secondary
- tertiary
insurance_subscriber_number:
type: string
last_name:
type: string
pcp_first_name:
type: string
pcp_last_name:
type: string
pcp_id:
type: string
description: >-
The id of a PCP provider from GET /v1/referring-providers
(UUID without dashes). Can be used instead of pcp_first_name
and pcp_last_name. Currently only supported for
eClinicalWorks.
plan_code:
type: string
description: >-
Greenway-internal plan code identifying the payer (e.g.
AETN08). Currently only used for Greenway, where it replaces
the insurance_name lookup and is required alongside
group_number and insurance_policy_type when attaching
insurance.
pharmacy_id:
type: string
phone:
type: string
referred_to_provider_id:
type: string
description: >-
The ehr_id of the provider this patient is being referred to
(rendering provider). Use the ehr_id from GET /v1/providers
referring_provider_first_name:
type: string
description: First name of the referring provider
referring_provider_last_name:
type: string
description: Last name of the referring provider
referring_provider_id:
type: string
description: >-
The id of a referring provider from GET
/v1/referring-providers (UUID without dashes). Can be used
instead of referring_provider_first_name and
referring_provider_last_name. Currently only supported for
eClinicalWorks.
responsible_party:
type: string
enum:
- self
- spouse
- child
- adopted_child
- step_child
- foster_child
- ward_of_court
- employee
- unknown
- handicapped_dependent
- organ_donor
- cadaver_donor
- grandchild
- niece_nephew
- injured_plaintiff
- sponsored_dependent
- minor_dependent
- parent
- grandparent
- life_partner
- other
description: >-
The responsible party for the patient. Non-self values
(spouse, parent, child, other, unknown) are currently
supported for eClinicalWorks only and require
responsible_party_* demographic fields.
secondary_insurance_name:
type: string
secondary_insurance_subscriber_number:
type: string
sex:
type: string
enum:
- male
- female
- unknown
responsible_party_first_name:
type: string
description: >-
First name of the responsible party. Required when
responsible_party is not self (eClinicalWorks only).
responsible_party_last_name:
type: string
description: >-
Last name of the responsible party. Required when
responsible_party is not self (eClinicalWorks only).
responsible_party_sex:
type: string
enum:
- male
- female
description: Sex of the responsible party (eClinicalWorks only).
responsible_party_dob:
type: string
description: >-
Date of birth of the responsible party in YYYY-MM-DD format
(eClinicalWorks only).
responsible_party_phone:
type: string
description: Phone number of the responsible party (eClinicalWorks only).
language:
type: string
description: >-
Patient preferred language (eClinicalWorks only). Must match
a valid language name in your eCW instance.
race:
type: string
description: >-
Patient race (eClinicalWorks only). Must match a valid race
name in your eCW instance.
ethnicity:
type: string
description: >-
Patient ethnicity (eClinicalWorks only). Must match a valid
ethnicity code or display name in your eCW instance.
release_of_info:
type: boolean
description: >-
Consent for release of information (eClinicalWorks only).
Defaults to true.
rx_history_consent:
type: boolean
description: >-
Consent for pharmacy history sharing (eClinicalWorks only).
Defaults to true.
self_pay:
type: boolean
description: >-
Explicitly marks the patient as self-pay, overriding
insurance-derived self-pay logic (eClinicalWorks only).
default_facility_id:
type: string
description: >-
The eCW facility ID to set as the patient primary service
location (eClinicalWorks only).
voice_enabled:
type: boolean
description: >-
Enables voice (phone) notifications for the patient in the
eCW Patient Communications settings (eClinicalWorks only).
text_enabled:
type: boolean
description: >-
Enables text (SMS) notifications for the patient in the eCW
Patient Communications settings (eClinicalWorks only).
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
patient_id:
type: string
components:
securitySchemes:
ClientCredentials:
type: apiKey
in: header
name: client_id
ClientSecret:
type: apiKey
in: header
name: client_secret
AccessToken:
type: apiKey
in: header
name: access_token
````