Skip to main content

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>

Path Parameters​

  • projectId (required): The HealthEx project id. The patient must be enrolled in this project.
  • patientId (required): 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​

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

  • patientId: The HealthEx patient id (always present).
  • firstName, lastName: The patient's name.
  • dateOfBirth: ISO 8601 date string (YYYY-MM-DD).
  • 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​

Unauthorized​

HTTP 401 — The token is missing, invalid, or expired.

Forbidden​

HTTP 403 — The caller is not authorized to access this patient's demographics in this project.

Not Found​

HTTP 404 — No active patient exists for the given patientId in the given projectId.

See Also​