Skip to main content
POST
/
v1
/
patients
/
upsert
Upsert Patient (forgiving)
curl --request POST \
  --url https://api.example.com/v1/patients/upsert \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "external_id": {
    "type_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "value": "<string>"
  },
  "first_name": "<string>",
  "last_name": "<string>",
  "middle_name": "<string>",
  "date_of_birth": "<string>",
  "gender": "<string>",
  "phone_number": "<string>",
  "additional_phone_number": "<string>",
  "email": "<string>",
  "address": "<string>",
  "address2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zip": "<string>",
  "comments": "<string>",
  "workflow_stage_id": "<string>",
  "assigned_user_id": "<string>",
  "location_id": "<string>",
  "tags": [
    "<string>"
  ],
  "referral": {
    "physician_name": "<string>",
    "physician_email": "<string>",
    "physician_phone": "<string>",
    "physician_fax": "<string>",
    "physician_group": "<string>",
    "physician_npi": "<string>",
    "physician_address": "<string>",
    "physician_address_2": "<string>",
    "physician_city": "<string>",
    "physician_zip": "<string>",
    "icd_codes": [
      "<string>"
    ],
    "service_types": [],
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "location_id": "<string>",
    "file_id": "<string>"
  },
  "payors": [
    {
      "insurance_id": "<string>",
      "payor_responsibility": "primary",
      "insured_member_id": "<string>",
      "group_number": "<string>",
      "group_description": "<string>",
      "coverage_from": "2023-12-25",
      "coverage_to": "2023-12-25",
      "plan_name": "<string>",
      "plan_type": "<string>",
      "eligibility_check_comment": "<string>",
      "subscriber": {
        "first_name": "<string>",
        "last_name": "<string>",
        "middle_name": "<string>",
        "dob": "2023-11-07T05:31:56Z",
        "insured_member_id": "<string>",
        "address": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "zip": "<string>"
      },
      "subscriber_id": "<string>",
      "services": [
        {
          "verification_benefits_status": "pending",
          "verification_dates": [
            "2023-11-07T05:31:56Z"
          ],
          "verification_benefits_comment": "<string>",
          "pre_cert_name": "<string>",
          "pre_cert_phone_number": "<string>",
          "pre_cert_fax": "<string>",
          "pre_cert_url": "<string>",
          "pre_cert_penalty": "<string>",
          "pre_cert_email": "<string>",
          "sca_instructions": "<string>",
          "claim_address": "<string>",
          "oon_reimbursement_rate": 123,
          "eligibility_check_id": "<string>",
          "carve_out_insurer_id": "<string>",
          "location_id": "<string>",
          "rep_name": "<string>",
          "call_reference_notes": "<string>",
          "location_rates": [
            {
              "covered_in_network": true,
              "covered_out_network": true,
              "copay_in_network": 123,
              "copay_out_network": 123,
              "co_insurance_in_network": 123,
              "co_insurance_out_network": 123,
              "auth_required_in_network": true,
              "auth_required_out_network": true,
              "auth_required_at_visit_in_network": 123,
              "auth_required_at_visit_out_network": 123,
              "mnr_required_in_network": true,
              "mnr_required_out_network": true,
              "mnr_required_at_visit_in_network": 123,
              "mnr_required_at_visit_out_network": 123,
              "deductible_apply_in_network": true,
              "deductible_apply_out_network": true,
              "oop_apply_in_network": true,
              "oop_apply_out_network": true,
              "dollar_limit_in_network": 123,
              "dollar_limit_out_network": 123,
              "dollar_limit_remaining_in_network": 123,
              "dollar_limit_remaining_out_network": 123,
              "visit_limit_in_network": 123,
              "visit_limit_out_network": 123,
              "visit_limit_remaining_in_network": 123,
              "visit_limit_remaining_out_network": 123,
              "id": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "custom_fields": {}
}
'
{
  "patient": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "<string>",
    "updated_at": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "middle_name": "<string>",
    "phone_number": "<string>",
    "additional_phone_number": "<string>",
    "email": "<string>",
    "date_of_birth": "<string>",
    "address": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "zip": "<string>",
    "workflow_stage_id": "<string>",
    "assigned_user_id": "<string>",
    "location_id": "<string>",
    "organization_id": "<string>",
    "active": true,
    "version": 1,
    "first_communication_at": "<string>",
    "custom_fields": {},
    "comments": "<string>",
    "tags": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "workflow_stage": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "actions": [],
      "order": 123,
      "description": "<string>"
    },
    "assigned_user": {
      "id": "<string>",
      "name": "<string>",
      "email": "<string>"
    },
    "referrals": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "physician_name": "<string>",
        "physician_email": "<string>",
        "physician_phone": "<string>",
        "physician_fax": "<string>",
        "physician_group": "<string>",
        "physician_npi": "<string>",
        "physician_address": "<string>",
        "physician_address_2": "<string>",
        "physician_city": "<string>",
        "physician_zip": "<string>",
        "icd_codes": [
          "<string>"
        ],
        "service_types": [],
        "start_date": "2023-12-25",
        "end_date": "2023-12-25",
        "location_id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "payors": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "<string>",
        "updated_at": "<string>",
        "patient_id": "<string>",
        "insurance_id": "<string>",
        "subscriber_id": "<string>",
        "insured_member_id": "<string>",
        "group_number": "<string>",
        "group_description": "<string>",
        "medicaid_id": "<string>",
        "coverage_from": "<string>",
        "coverage_to": "<string>",
        "plan_name": "<string>",
        "cob_notes": "<string>",
        "cob_last_verified_at": "<string>",
        "has_other_active_coverage": true,
        "out_of_state_benefits": true,
        "out_of_state_benefits_comments": "<string>",
        "in_grace_period": true,
        "last_payment_date": "<string>",
        "is_cobra_coverage": true,
        "deductible_apply_to_oop": true,
        "copay_applies_to_oop_max": true,
        "eligibility_check_status": "pending",
        "eligibility_check_comment": "<string>",
        "eligibility_check_date": "<string>",
        "eligibility_version": 0,
        "individual_deductible_policy_in_network": 123,
        "individual_deductible_policy_out_network": 123,
        "individual_deductible_remaining_in_network": 123,
        "individual_deductible_remaining_out_network": 123,
        "family_deductible_policy_in_network": 123,
        "family_deductible_policy_out_network": 123,
        "family_deductible_remaining_in_network": 123,
        "family_deductible_remaining_out_network": 123,
        "individual_oop_max_policy_in_network": 123,
        "individual_oop_max_policy_out_network": 123,
        "individual_oop_max_remaining_in_network": 123,
        "individual_oop_max_remaining_out_network": 123,
        "family_oop_max_policy_in_network": 123,
        "family_oop_max_policy_out_network": 123,
        "family_oop_max_remaining_in_network": 123,
        "family_oop_max_remaining_out_network": 123,
        "benefits_related_entities": [
          {}
        ],
        "ai_summary": "<string>",
        "ai_summary_generated_at": "<string>",
        "patient": {},
        "insurance": {},
        "subscriber": {},
        "services": [
          {
            "copay_in_network": 25,
            "created_at": "2024-01-15T10:30:00Z",
            "eligibility_check_status": "ELIGIBLE",
            "id": "550e8400-e29b-41d4-a716-446655440014",
            "payor_id": "550e8400-e29b-41d4-a716-446655440012",
            "service_type": "PT",
            "updated_at": "2024-01-15T10:30:00Z",
            "verification_benefits_status": "VERIFIED"
          }
        ],
        "active": true,
        "version": 1
      }
    ],
    "external_id_values": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "value": "<string>",
        "external_id_type": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>",
          "created_at": "2023-11-07T05:31:56Z"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ]
  },
  "matched": true,
  "created": true,
  "dropped_fields": [
    "<string>"
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Forgiving upsert request — every field optional, no throwing validators.

The service normalizes and silently drops unparseable phone / email / DOB values. The post-normalization invariant (phone OR full demographics) is checked there as well.

​
external_id
ExternalIdInput · object

External identifier from the integration. Used as the highest-priority match key.

​
first_name
string | null
​
last_name
string | null
​
middle_name
string | null
​
date_of_birth
string | null

DOB in any of: YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, MM-DD-YYYY, MM/DD/YY. Unparseable values are dropped.

​
gender
string | null
​
phone_number
string | null
​
additional_phone_number
string | null
​
email
string | null
​
address
string | null
​
address2
string | null
​
city
string | null
​
state
string | null
​
zip
string | null
​
comments
string | null
​
workflow_stage_id
string | null
​
assigned_user_id
string | null
​
location_id
string | null

Company location ID. Foreign IDs are dropped.

​
tags
string[] | null
​
referral
ReferralCreateRequest · object

Nested referral creation for patient creation

​
payors
PayorCreateInline · object[] | null
​
custom_fields
Custom Fields · object
​
created_from
enum<string> | null

Patient creation source enum matching Prisma

Available options:
form,
call,
api,
file,
sms,
fax,
chat_agent,
manual,
bulk_import,
eligibility

Response

Successful Response

Response — 200 OK for both create and update (idempotent semantics).

​
patient
Patient · object
required

Patient resource response model.

​
matched
boolean
required

True if an existing patient was found and updated

​
created
boolean
required

True if a new patient was created

​
match_reason
enum<string> | null

Which match tier resolved the patient. None when created=True.

Available options:
external_id,
demographics,
phone_fuzzy_name,
email_fuzzy_name
​
dropped_fields
string[]

Fields the request supplied that were silently dropped during normalization (unparseable phone/email/DOB, or external_id conflict, or phone-immutability lock).