Upsert Patient

POST /v1/patients/upsert is a single endpoint integrations can call instead of choosing between POST /v1/patients (strict — 409 on conflict) and POST /v1/patients/batch (additive — never overwrites identity fields). It’s designed for partner systems that produce imperfect data: phones in 12 different shapes, dates that might be 04/12/85, the same patient sent twice from two upstream feeds. The endpoint:

Normalizes forgiving fields — bad phone / email / DOB / gender / state values are silently dropped.
Looks for an existing patient in priority order (external_id → demographics → phone+name → email+name).
Updates the match with every non-null field you sent (with two specific carve-outs), or creates a new patient if no match was found.
Returns which patient path it took, a list of fields it dropped, and one ordered processing result for every submitted payor.

It returns 200 OK for both create and update — there is no separate 201.

This endpoint accepts unknown fields silently. Sending proprietary metadata won’t 400 — it just won’t be persisted.

Request

POST https://api.getsolum.com/v1/patients/upsert Auth: X-API-Key: <your_api_key>. Every field is optional at the schema level — invariants are checked after normalization (see Required identifying info).

Identification

Field	Type	Notes
`external_id.type_id`	UUID	Must reference an `external_id_type` belonging to your company.
`external_id.value`	string	Your system’s identifier for this patient. Used as the highest-priority match key.

Demographics & contact

Field	Type	Normalization
`first_name`, `last_name`, `middle_name`	string	Trimmed, stored as given.
`date_of_birth`	string	Accepts `YYYY-MM-DD`, `YYYYMMDD`, `MM/DD/YYYY`, `MM-DD-YYYY`, `MM/DD/YY`, textual forms (`April 12, 1985`). Range-checked: must be ≥ 1900-01-01 and ≤ today.
`gender`	string	Coerced to `male` / `female` / `other`. Accepts synonyms (`M`, `F`, `man`, `woman`, `nb`, `non-binary`, `x`, `unknown`, …).
`phone_number`, `additional_phone_number`	string	Normalized to E.164 (`+1XXXXXXXXXX`). Accepts 10 digits, 11 digits starting with 1, with or without formatting.
`email`	string	Lowercased and regex-validated.

Address

Field	Type	Notes
`address`, `address2`, `city`, `zip`	string	Trimmed pass-through.
`state`	string	2-letter postal code, full name (`California`, `new york`), or common short form (`Calif`, `Mass`, `Tenn`).

Workflow / assignment / tags

Field	Type	Notes
`workflow_stage_id`	string	UUID or stage name. Unresolvable values are dropped.
`assigned_user_id`	string	UUID or user email. Unresolvable values are dropped.
`tags`	string[]	Array of tag UUIDs or tag names. Tags that don’t resolve are dropped (full or partial → `tags` appears in `dropped_fields`).

Nested entities

Field	Type	Notes
`referral`	object	Same shape as `POST /v1/patients`. Internal validators still apply.
`payors`	array	Each payor must contain exactly one of `insurance_id` or `insurance_name`. See Resolving a payor’s insurance and Payor reconciliation. Each payor may also carry an `external_id` for the coverage; see Coverage `external_id`.
`custom_fields`	object	Pass-through to the patient service.

Required identifying info

A new patient (no match found) must have at least one of:

A normalized phone_number, or
All three of first_name, last_name, date_of_birth (post-normalization).

If neither is present after normalization, the request returns:

400 Bad Request
{
  "detail": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "Insufficient identifying information to create a new patient. Send a phone_number, or send first_name + last_name + date_of_birth.",
    "param": "patient_identifiers",
    "dropped_fields": [],
    "missing_fields": ["first_name", "last_name", "date_of_birth"]
  }
}

missing_fields reports the identifying fields absent after normalization. In this error response, dropped_fields identifies a supplied phone number or email that Solum could not use because it belongs to another patient. For example, if both values belong to another patient and the remaining demographics are insufficient to create a new patient, dropped_fields contains phone_number and email. A value rejected during normalization can still be absent from dropped_fields in this response.

Match resolution

The service walks four tiers in order — external_id → demographics → phone_fuzzy_name → email_fuzzy_name — and the first hit wins. The match_reason field on the response tells you which tier resolved. The full rules, including how the name and DOB conflict checks behave on tiers 3 and 4, live in the Patient Matching guide. Read that page if you want to know exactly when the system will and won’t merge two records.

Update behavior on match

When a match is found, all non-null fields you sent overwrite the existing patient’s values. This is the deliberate departure from POST /v1/patients/batch, which only fills in blanks. Two exceptions apply on update — phone-immutability after first contact, and sibling-conflict drops when a phone/email belongs to another patient. Both are explained in detail under What Happens After a Match in the Patient Matching guide. When either fires, the affected field name is added to dropped_fields on the response.

External ID handling

The external_id block does double duty: it is the highest-priority match key, and the supplied value is reconciled onto the resolved patient.

Existing state	Behavior
`type_id` doesn’t belong to your company	`400 Bad Request` (validation error).
Patient has no record for this `type_id`	A new external-id record is created.
Patient already has the same `(type_id, value)`	No-op.
Patient has a different value for this `type_id`	The existing value is updated and the old-to-new change is recorded in the patient activity history.
A soft-deleted patient owns `(type_id, value)`	The orphaned external-id row is retired and the value is assigned to the resolved patient.
Another active patient acquires `(type_id, value)` during the upsert	Solum does not take the value from that patient; `external_id` is added to `dropped_fields`.

A successful response normally means the resolved patient carries the supplied external ID. Callers must still inspect dropped_fields: Solum can drop external_id after a concurrent conflict with another active patient or after a failed reassignment while reclaiming a value from a soft-deleted patient.

Resolving a payor’s insurance

Every payor in an upsert request must identify its configured insurance in exactly one of two ways:

Send insurance_id when your integration already knows the configured insurance UUID.
Send insurance_name when Solum should look up the configured insurance from free text.

Sending both fields, neither field, a blank insurance_name, or an insurance_name longer than 200 characters is a structural request error and returns 422. These cases are not converted into forgiving field drops. insurance_name is lookup-only. A successful match is converted to the configured insurance_id before the payor is processed. The submitted name is not stored, does not populate insurance_display_name, and does not create an alias. It is echoed only in the corresponding payor_results[].submitted_insurance_name so callers can reconcile the result with their request. For name-based lookups, Solum resolves each unique name in this order:

A unique normalized match against a configured canonical name or alias.
A unique match after adding the patient’s state name and postal code before and after the submitted name.
An AI-assisted match over a bounded list of the closest eligible configured insurances. Only a high- or medium-confidence selection from that list is accepted.

The state used for steps 2 and 3 is the valid normalized state in the current request, then the matched patient’s stored state, then no state. If a supplied state is invalid, state is added to dropped_fields; a matched patient’s stored state can still provide the lookup context. State helps resolve the insurance but does not participate in patient matching. An inferred match can select only an active insurance belonging to the authenticated company with a nonblank trading-partner service ID. This eligibility boundary applies only to insurance_name. An explicit insurance_id bypasses name resolution and retains its existing behavior, including support for an active company insurance without a trading-partner service ID. When a name cannot be resolved, Solum skips only that payor, continues creating or updating the patient and any other valid payors, and includes payors once in dropped_fields. Resolution is lookup-only: it never creates or modifies an insurance.

Insurance reference examples

Use a configured UUID directly:

{
  "payors": [
    {
      "insurance_id": "00000000-0000-4000-8000-000000000020",
      "payor_responsibility": "primary",
      "insured_member_id": "W884412307"
    }
  ]
}

Let the patient’s state disambiguate a generic Medicaid name:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "2016-03-14",
  "state": "VA",
  "payors": [
    {
      "insurance_name": "Medicaid",
      "payor_responsibility": "primary",
      "insured_member_id": "VA-884412307"
    }
  ]
}

For example, this can resolve to an eligible configured Virginia Medicaid insurance without persisting the word Medicaid from the request. An unresolved name does not fail the patient upsert:

// request
{
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "2016-03-14",
  "payors": [
    {
      "insurance_name": "Unknown Regional Plan",
      "payor_responsibility": "primary"
    }
  ]
}

// response (patient fields abbreviated)
{
  "patient": { "id": "..." },
  "matched": false,
  "created": true,
  "match_reason": null,
  "dropped_fields": ["payors"],
  "payor_results": [
    {
      "payor_responsibility": "primary",
      "submitted_insurance_name": "Unknown Regional Plan",
      "resolved_insurance_id": null,
      "resolved_insurance_name": null,
      "trading_partner_service_id": null,
      "payor_id": null,
      "coverage_chain_id": null,
      "outcome": "unresolved",
      "resolution_method": null,
      "reason_code": "no_configured_match",
      "message": "No configured insurance matched this name."
    }
  ]
}

Payor reconciliation

After the patient is created or matched, each resolved payor is reconciled independently:

Resolve every insurance_name to a canonical insurance_id. Unresolved names are skipped and reported through dropped_fields; explicit IDs bypass this lookup.
Match each surviving request payor by insurance_id to existing patient coverage chains. When the patient holds two coverages on that same carrier, the tie is broken by external_id first (a coverage already carrying the ID you sent wins), then by insured_member_id. If neither decides it, a new coverage is started rather than guessing between two policies.
If the existing payor has any service in in_progress or completed verification status, it is archived (preserved as historical) and a new payor row is created. Otherwise it’s updated in place.
Tier collisions — any other active payor occupying the same payor_responsibility (primary / secondary / tertiary) is archived to satisfy the (patient_id, payor_responsibility) unique index.
Invalid explicit IDs and name-based matches that become unavailable before validation are skipped, and payors is added to dropped_fields.

Each coverage runs in its own transaction. A failure while saving one payor therefore does not undo the patient or another successfully saved payor. A submission that is already represented exactly is reported as unchanged and does not create a new payor, service, subscriber, or service-location row. This preserves prior verification-of-benefits context as separate historical rows when carriers change, instead of overwriting them, while making partial success explicit in the response.

Coverage `external_id`

Each payor may carry an external_id — your own identifier for that coverage. It belongs to the coverage as a whole, so every historical version of it reports the same value, and no two coverages in your company can hold the same one. Send it on every sync and it does two jobs: it picks out the right coverage when a patient has two policies on one carrier (step 2 above), and it is stored on whichever coverage the payor lands on, replacing any previous value. Two rules worth knowing:

Set only, never clear. Omitting it, or sending null or an empty string, leaves whatever is already stored untouched. To remove an ID, use the payor endpoints, where an explicit null means “clear”.
Never taken from another coverage. If the ID you send already belongs to a different coverage, the payor is still written and only that field is skipped — payors.external_id then appears in dropped_fields. (POST /v1/patients rejects the whole request with 409 instead; the forgiving behavior is specific to this endpoint.)

The response returns the resolved payor_id and coverage_chain_id in the corresponding payor_results item. Read the full payor record back with expand[]=payors on the patient or payor endpoints.

There is one narrow case where a coverage ID you sent is not stored and this endpoint tells you so only through dropped_fields: another request claims the same ID in the moment between our check and our write. The patient and payor are already saved by then, so we keep them and skip the ID rather than failing the whole request.On POST /v1/patients that same race has no signal — there is no dropped_fields on that endpoint, so you would get a normal success for a patient whose coverage ID was never stored. If you rely on these IDs for reconciliation, read them back with expand[]=payors after a create, or use this endpoint and watch dropped_fields.

POST /v1/patients/batch does not accept this field; a CSV row carrying it fails that row’s validation.

Response

200 OK
{
  "patient": { /* full Patient object */ },
  "matched": false,
  "created": true,
  "match_reason": null,
  "dropped_fields": [],
  "payor_results": []
}

Field	Type	Meaning
`patient`	object	The full patient record after the operation.
`matched`	boolean	`true` if an existing patient was updated.
`created`	boolean	`true` if a new patient was created.
`match_reason`	string \| null	One of `external_id`, `demographics`, `phone_fuzzy_name`, `email_fuzzy_name`. `null` when `created` is `true`.
`dropped_fields`	string[]	Field names that were supplied but didn’t make it onto the record. See Dropped fields.
`payor_results`	object[]	One result per submitted payor, in request order. Empty when no payors were supplied.

matched and created are exclusive — exactly one is true.

Payor result fields

Field	Meaning
`payor_responsibility`	Submitted coverage tier.
`submitted_insurance_name`	Lookup text supplied by the caller, or `null` for an explicit insurance UUID.
`resolved_insurance_id`, `resolved_insurance_name`	Configured insurance selected for this coverage.
`trading_partner_service_id`	Service identifier on the selected configured insurance.
`payor_id`, `coverage_chain_id`	Persisted coverage identifiers, when available.
`outcome`	`created`, `updated`, `unchanged`, `unresolved`, or `failed`.
`resolution_method`	`canonical_name`, `alias`, `state_variant`, or `ai` for a successful name lookup.
`reason_code`	Stable reason for an unresolved or failed result.
`message`	Safe human-readable explanation, when one is needed.

An unresolved outcome can use no_configured_match, configured_insurance_inactive, insurance_not_vob_ready, ambiguous_match, match_confidence_too_low, or resolution_unavailable. A save failure uses persistence_failed. The response omits member IDs and internal exception details from these result objects.

Dropped fields

A field appears in dropped_fields when:

Cause	Fields affected
Unparseable value	`phone_number`, `additional_phone_number`, `email`, `date_of_birth`, `gender`, `state`
Phone-immutability lock on matched patient	`phone_number`
Unique constraint conflict (another patient owns it)	`phone_number`, `email`
Unresolvable name / UUID	`workflow_stage_id`, `assigned_user_id`, `tags` (full or partial)
Concurrent external-id conflict with another active patient, or a failed retry after reclaiming an orphaned value	`external_id`
Unresolved `insurance_name`, or an invalid, inactive, missing, or cross-company `insurance_id`	`payors`
Coverage `external_id` already held by a different coverage, or sent twice in one request	`payors.external_id`

dropped_fields is always present (empty array if nothing was dropped). Treat it as a soft-warning channel — surface it to your reconciliation logs.

Examples

Create a new patient

curl -X POST https://api.getsolum.com/v1/patients/upsert \
  -H "X-API-Key: $SOLUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "04/12/1985",
    "phone_number": "(555) 123-4567",
    "email": "JANE.DOE@example.com",
    "state": "CA",
    "external_id": {
      "type_id": "8f3b2a1c-...",
      "value": "PMS-99041"
    }
  }'

{
  "patient": { "id": "...", "first_name": "Jane", ... },
  "matched": false,
  "created": true,
  "match_reason": null,
  "dropped_fields": []
}

Update via external_id

Same external_id — value updates flow through:

// request
{
  "external_id": { "type_id": "8f3b2a1c-...", "value": "PMS-99041" },
  "email": "jane.new@example.com",
  "address": "123 Main St"
}

// response
{
  "patient": { "id": "...", "email": "jane.new@example.com", ... },
  "matched": true,
  "created": false,
  "match_reason": "external_id",
  "dropped_fields": []
}

Forgiving normalization in action

// request — DOB unparseable, gender synonym, bad email
{
  "first_name": "Sam",
  "last_name": "Lee",
  "phone_number": "5551234567",
  "date_of_birth": "13/14/1985",
  "gender": "M",
  "email": "not an email"
}

// response — patient created, two fields dropped, gender normalized
{
  "patient": { "id": "...", "gender": "male", "date_of_birth": null, ... },
  "matched": false,
  "created": true,
  "match_reason": null,
  "dropped_fields": ["email", "date_of_birth"]
}

Differences vs. other patient endpoints

Behavior	`POST /patients`	`POST /patients/batch`	`POST /patients/upsert`
Bad phone / email / DOB	`400`	`400` (whole batch fails)	Silently dropped
Existing patient match	`409` conflict	Additive merge (never overwrites)	Overwrites with provided fields
Required fields	Strict	Strict	Phone or full demographics
Returns match metadata	No	No	Yes (`match_reason`, `dropped_fields`)
Status code	`201` create / `409` conflict	`201`	`200` (always)

Use POST /patients for human-driven flows where errors should surface immediately. Use POST /patients/upsert for partner integrations where input quality varies and you’d rather get a usable record back than a 400.

Troubleshooting

Symptom	Cause	Fix
`400 Insufficient identifying information`	Phone normalized to null and demographics incomplete.	Send a valid phone OR all of `first_name` + `last_name` + `date_of_birth`.
`400 external_id.type_id … does not belong to this company`	Wrong company’s `external_id_type` UUID.	Use a `type_id` from your own company’s external-id types.
`match_reason: phone_fuzzy_name` when you expected a new patient	An existing patient owned that phone and the names fuzzy-matched.	Send `external_id` for unambiguous identity, or use a unique phone per patient.
`dropped_fields: ["phone_number"]` after update	Either the matched patient’s phone was locked (`first_communication_at` set), or another patient already owns that number.	Inspect the returned patient — the original phone is preserved.
`dropped_fields: ["external_id"]`	The `(type_id, value)` already exists on a different patient, OR the matched patient already has a different value for that `type_id`.	Resolve the duplicate identifier upstream.
`dropped_fields: ["tags"]` despite valid tag names	At least one tag name didn’t match any existing company tag.	Confirm tag names are exact (case-sensitive) and exist in your company.
`dropped_fields: ["payors"]`	At least one insurance name could not be resolved, or an explicit insurance ID was not a valid active insurance for your company.	Confirm the configured insurance and, for name-based matching, send the patient’s state when available.

Start Here

Account

API

Webhooks

Basic Configuration

Patients

AI Assistants

Insurance & Eligibility

Prior Authorizations

Upsert Patient (API)

Upsert Patient

Request

Identification

Demographics & contact

Address

Workflow / assignment / tags

Nested entities

Required identifying info

Match resolution

Update behavior on match

External ID handling

Resolving a payor’s insurance

Insurance reference examples

Payor reconciliation

Coverage `external_id`

Response

Payor result fields

Dropped fields

Examples

Create a new patient

Update via external_id

Forgiving normalization in action

Differences vs. other patient endpoints

Troubleshooting

​Upsert Patient

​Request

​Identification

​Demographics & contact

​Address

​Workflow / assignment / tags

​Nested entities

​Required identifying info

​Match resolution

​Update behavior on match

​External ID handling

​Resolving a payor’s insurance

​Insurance reference examples

​Payor reconciliation

​Coverage external_id

​Response

​Payor result fields

​Dropped fields

​Examples

​Create a new patient

​Update via external_id

​Forgiving normalization in action

​Differences vs. other patient endpoints

​Troubleshooting

Upsert Patient

Request

Identification

Demographics & contact

Address

Workflow / assignment / tags

Nested entities

Required identifying info

Match resolution

Update behavior on match

External ID handling

Resolving a payor’s insurance

Insurance reference examples

Payor reconciliation

Coverage `external_id`

Response

Payor result fields

Dropped fields

Examples

Create a new patient

Update via external_id

Forgiving normalization in action

Differences vs. other patient endpoints

Troubleshooting