Skip to main content
POST
Create a patient

​
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:

​
Option 2: Provider IDs

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

​
Responsible Party

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 the EMR with the provided demographics
  2. Link that guarantor to the insurance record
  3. Set the responsible party on the patient
Supported values: Optional guarantor fields:
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 the EMR — if a guarantor with those demographics already exists in your instance, a duplicate will be created.

​
Registration Fields

Additional demographic and consent fields can be set at patient creation:
Notification language. When voice_enabled or text_enabled is set, the notification language in the EHR follows the patient’s language: Spanish when language contains “spanish” (case-insensitive), otherwise English. These are the only two options exposed 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)
Option 2: Insurance Provider ID 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

​
Example Request

​
Basic Request

​
With Provider Names

​
With Provider IDs

​
Example Response

Store the returned patient_id to correlate the follow-up webhook. job_id is the API log ID for the request and is also present on the resulting webhook, so you can match either identifier back to this call.

​
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

​
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:
Referring Provider Not Found:
PCP Not Found:
Insurance Not Found:
Patient creation is asynchronous. Store the returned patient_id and listen for webhooks to determine the final status.

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Body

application/json
​
first_name
string | null

Patient first name.

Example:

"Jane"

​
last_name
string | null

Patient last name.

Example:

"Doe"

​
dob
string<date> | null

Date of birth (YYYY-MM-DD).

Example:

"1980-01-15"

​
sex
string | null

Patient sex: male, female, or unknown.

Example:

"female"

​
ssn
string | null

Social Security Number, 9 digits, no dashes.

Example:

"123456789"

​
phone
string | null

Primary phone (222-333-4444).

Example:

"555-123-4567"

​
email
string | null

Patient email.

Example:

"jane.doe@example.com"

​
referring_provider_first_name
string | null

Referring provider first name (provide with last name, or use referring_provider_id).

Example:

"Jane"

​
referring_provider_last_name
string | null

Referring provider last name.

Example:

"Doe"

​
referring_provider_id
string | null

Cobalt referring-provider UUID (from GET /v1/referring-providers).

​
referring_provider_npi
string | null

Referring provider NPI.

Example:

"1234567890"

​
pcp_first_name
string | null

Primary care provider first name (provide with last name, or use pcp_id).

Example:

"Jane"

​
pcp_last_name
string | null

Primary care provider last name.

Example:

"Doe"

​
pcp_id
string | null

Cobalt UUID of the PCP (from GET /v1/referring-providers or GET /v1/providers).

​
insurance_name
string | null

Primary insurance company name (or use insurance_provider_id). Must match the EMR settings exactly.

Example:

"Blue Cross Anthem"

​
insurance_provider_id
string | null

Cobalt insurance-provider UUID (from GET /v1/insurance-providers).

Example:

"insurance-provider-123"

​
insurance_subscriber_number
string | null

Primary insurance subscriber / member number. Required when insurance is provided.

Example:

"INS123456789"

​
insurance_sequence
string | null

Insurance sequence: primary, secondary, or tertiary.

Example:

"primary"

​
insurance_policy_type
string | null

Insurance policy type (e.g. PPO).

Example:

"PPO"

​
plan_code
string | null

Insurance plan code. For Greenway, the payer identifier that signals insurance is being attached.

Example:

"PLAN-001"

​
group_number
string | null

Insurance group number.

Example:

"GRP98999"

​
secondary_insurance_name
string | null

Secondary insurance company name (provide with its subscriber number). Must match the EMR settings exactly.

Example:

"Blue Cross Anthem"

​
secondary_insurance_subscriber_number
string | null

Secondary insurance subscriber / member number.

Example:

"INS123456789"

​
emergency_contact_first_name
string | null

Emergency contact first name (all four emergency_contact_* fields must be provided together).

Example:

"Jane"

​
emergency_contact_last_name
string | null

Emergency contact last name.

Example:

"Doe"

​
emergency_contact_relation
string | null

Emergency contact relationship to the patient.

Example:

"spouse"

​
emergency_contact_phone
string | null

Emergency contact phone (222-333-4444).

Example:

"555-123-4567"

​
pharmacy_id
string | null

EMR pharmacy ID.

Example:

"PHARM-123"

​
cell_phone
string | null

Cell phone (222-333-4444).

Example:

"555-987-6543"

​
middle_name
string | null

Patient middle name.

Example:

"Anne"

​
mrn
string | null

Medical Record Number to assign the patient.

Example:

"12345"

​
document_url
string | null

URL of a document to attach to the patient.

Example:

"https://example.com/patient-doc.pdf"

​
referral_reason
string | null

Reason for the referral.

Example:

"Specialist consultation"

​
referral_type
string | null

Referral type.

Example:

"Internal"

​
referred_to_provider_id
string | null

Referred-to provider EMR ID. Validated against the account's providers.

Example:

"provider-123"

​
referred_to_location_id
string | null

Referred-to location EMR ID.

Example:

"location-1"

​
facility_id
string | null

EMR facility ID.

Example:

"FAC-123"

​
facility_name
string | null

EMR facility name.

Example:

"Main Hospital"

​
address_street
string | null

Street address line 1.

Example:

"123 Main Street"

​
address_line2
string | null

Street address line 2.

Example:

"Apt 4B"

​
address_city
string | null

City.

Example:

"Los Angeles"

​
address_county
string | null

County.

Example:

"Los Angeles County"

​
address_state
string | null

Two-letter U.S. state abbreviation.

Example:

"CA"

​
address_zip
string | null

5-digit U.S. ZIP code.

Example:

"90001"

​
responsible_party
string | null

Guarantor relationship to the patient. Allowed values vary by EMR (e.g. self, spouse, child, other).

Example:

"self"

​
check_eligibility
enum<string> | null

Whether to run an eligibility check on creation.

Available options:
true,
false
​
responsible_party_first_name
string | null

Guarantor first name (required when responsible_party is not self).

Example:

"Jane"

​
responsible_party_last_name
string | null

Guarantor last name.

Example:

"Doe"

​
responsible_party_sex
string | null

Guarantor sex.

Example:

"female"

​
responsible_party_dob
string<date> | null

Guarantor date of birth (YYYY-MM-DD).

Example:

"1980-01-15"

​
responsible_party_phone
string | null

Guarantor phone (222-333-4444).

Example:

"555-123-4567"

​
responsible_party_email
string | null

Guarantor email.

Example:

"jane.doe@example.com"

​
responsible_party_address_line1
string | null

Guarantor street address line 1.

Example:

"123 Main Street"

​
responsible_party_address_line2
string | null

Guarantor street address line 2.

Example:

"Apt 4B"

​
responsible_party_address_city
string | null

Guarantor city.

Example:

"Los Angeles"

​
responsible_party_address_state
string | null

Guarantor two-letter U.S. state abbreviation.

Example:

"CA"

​
responsible_party_address_zip
string | null

Guarantor 5-digit U.S. ZIP code.

Example:

"90001"

​
location
string | null

EMR location ID. Validated against the account's locations.

Example:

"location-1"

​
nationality
string | null

Patient nationality.

Example:

"American"

​
marital_status
string | null

Marital status.

Example:

"Married"

​
billing_group
string | null

Billing group.

Example:

"Group A"

​
no_email_reason
string | null

Reason the patient has no email, accepted in place of email.

Example:

"Patient declined"

​
no_ssn_reason
string | null

Reason the patient has no SSN, accepted in place of ssn.

Example:

"Patient declined"

​
language
string | null

Preferred language.

Example:

"English"

​
race
string | null

Patient race.

Example:

"White"

​
ethnicity
string | null

Patient ethnicity.

Example:

"Not Hispanic or Latino"

​
release_of_info
enum<string> | null

Release-of-information consent. Accepts true/false (true maps to Y, false to N) or an eClinicalWorks code: Y (release allowed), M (modified/restricted), N (no release), I (ANSI 5010 informed consent).

Available options:
true,
false,
Y,
M,
N,
I
​
rx_history_consent
enum<string> | null

Prescription-history consent. Accepts true/false (true maps to Y, false to N) or an eClinicalWorks code: Y (signed), N (denied), U (unasked).

Available options:
true,
false,
Y,
N,
U
​
self_pay
enum<string> | null

Whether the patient is self-pay.

Available options:
true,
false
​
default_facility_id
string | null

Default facility EMR ID for the patient.

Example:

"FAC-123"

​
voice_enabled
enum<string> | null

Whether voice notifications are enabled.

Available options:
true,
false
​
text_enabled
enum<string> | null

Whether text notifications are enabled.

Available options:
true,
false
​
callback_urls

URL(s) to receive the completion webhook for this patient, in addition to the account webhook.

Example:

Response

Patient queued for creation

​
success
boolean
required
​
message
string
required
​
patient_id
string
required
​
job_id