Patient Demographics

This endpoint returns the demographic information HealthEx has on file for a patient — name, date of birth, gender, contact details, mailing address, and the identifier your organization assigned the patient.

The endpoint is project-scoped: the externalId returned is the one your organization assigned this patient in the given project.

Making the API Call

GET https://api.healthex.io/v1/projects/{projectId}/patients/{patientId}/demographics
Accept: application/json
Authorization: Bearer <token>

Required Path Parameters

• projectId: The HealthEx project id. The patient must be enrolled in this project.
• patientId: The HealthEx patient id.

Response Format

A successful request returns 200 with a JSON body shaped as:

{
    "patientId": "17d4513f-73e8-4b2a-9c1d-5e6f7a8b9c0d",
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1985-04-12",
    "gender": "female",
    "email": "jane.doe@example.com",
    "phone": "+15551234567",
    "externalId": "PARTNER-PT-00042",
    "addressLines": ["123 Main St", "Apt 4B"],
    "city": "San Francisco",
    "district": "San Francisco County",
    "state": "CA",
    "postalCode": "94110",
    "country": "US"
}

Response Fields

note

All fields except patientId are nullable — a given patient may not have every field populated.

Field	Description
patientId	The HealthEx patient id (always present).
firstName	The patient's first name.
lastName	The patient's last name.
dateOfBirth	ISO 8601 date string in YYYY-MM-DD format.
gender	The patient's gender. Typical values: male, female, other, unknown.
email	The patient's current primary email address.
phone	The patient's current primary phone number in E.164 format.
externalId	The identifier your organization assigned this patient in this project.
addressLines	An ordered array of street address lines (street, unit, building, c/o). Empty array when no address is on file.
city	City or locality.
district	Second-level administrative division — county in the US, equivalent term internationally.
state	First-level administrative division — US state, region, province, etc.
postalCode	ZIP / postcode.
country	ISO country code.

Error Responses

Response Code	Reason
401 Unauthorized	The token is missing, invalid, or expired.
403 Forbidden	The caller is not authorized to access this patient's demographics in this project.
404 Not Found	No active patient exists for the given patientId in the given projectId.

See Also

• Add Patients to Projects: Assign an externalId to a patient via your recruitment flow.
• Accessing Patient Data: For organizations that have data delivery configured, the same demographic fields appear in the delivery manifest.