Patients

Create or update patient records with optional insurance information via the Integration API.

Create or update patient records with optional primary, secondary, and tertiary insurance information.

Upsert Patient

POST /integration/patients

Creates or updates a patient by id. Optionally upserts primary, secondary, and tertiary insurance records.

Request Body

Field	Type	Required	Description
`id`	string	Yes	Your unique identifier for this patient
`first_name`	string	Yes	Patient's first name
`last_name`	string	Yes	Patient's last name
`date_of_birth`	string (ISO 8601)	Yes	Date of birth
`gender`	string	No	`male`, `female`, or `other`
`phone`	string	No	Phone number
`email`	string	No	Email address
`ssn_last4`	string	No	Last 4 digits of SSN
`address_line_1`	string	No	Street address
`address_line_2`	string	No	Apartment, suite, etc.
`city`	string	No	City
`state`	string	No	State code (2 characters)
`zip_code`	string	No	ZIP code
`country`	string	No	Country code (default: `US`)
`primary_insurance`	object	No	Primary insurance details
`secondary_insurance`	object	No	Secondary insurance details
`tertiary_insurance`	object	No	Tertiary insurance details

Insurance Object

Each insurance object accepts the following fields:

Field	Type	Required	Description
`payer_id`	string	Yes	ID of the payer (must exist)
`policy_number`	string	No	Insurance policy number
`group_number`	string	No	Group number
`effective_date`	string (ISO 8601)	No	Coverage start date
`termination_date`	string (ISO 8601)	No	Coverage end date
`subscriber_id`	string	No	Subscriber ID (if different from patient)
`subscriber_first_name`	string	No	Subscriber's first name
`subscriber_last_name`	string	No	Subscriber's last name
`subscriber_relationship`	string	No	Relationship to subscriber (`self`, `spouse`, `child`, `other`)
`subscriber_date_of_birth`	string (ISO 8601)	No	Subscriber's date of birth
`subscriber_address_line_1`	string	No	Subscriber's street address
`subscriber_city`	string	No	Subscriber's city
`subscriber_state`	string	No	Subscriber's state
`subscriber_zip_code`	string	No	Subscriber's ZIP code
`subscriber_country`	string	No	Subscriber's country

Example Request

curl -X POST https://api.neuralrev.ai/integration/patients \
  -H "x-api-key: nrev_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "PAT-001",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-01-15T00:00:00Z",
    "gender": "female",
    "phone": "5551234567",
    "email": "jane.doe@example.com",
    "ssn_last4": "1234",
    "address_line_1": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip_code": "62701",
    "primary_insurance": {
      "payer_id": "PAYER-001",
      "policy_number": "POL-12345",
      "group_number": "GRP-100",
      "effective_date": "2024-01-01T00:00:00Z",
      "subscriber_first_name": "Jane",
      "subscriber_last_name": "Doe",
      "subscriber_relationship": "self",
      "subscriber_address_line_1": "123 Main St",
      "subscriber_city": "Springfield",
      "subscriber_state": "IL",
      "subscriber_zip_code": "62701",
      "subscriber_country": "US"
    }
  }'

Response

200 OK — Patient upserted successfully:

{
  "success": true,
  "message": "Patient upserted successfully"
}

400 Bad Request — Validation error or referenced payer not found:

{
  "error": "Payer not found for id: PAYER-999"
}

Notes

The payer_id in insurance objects must reference a payer that has already been created via the /integration/payers endpoint.
Sending a patient request without insurance fields will not remove existing insurance records. To update insurance, include the insurance object with updated values.
Only ssn_last4 (last 4 digits) is accepted — full SSN is never stored.