Patient Provider Map

What is the Patient Provider Map?

The Patient Provider Map API returns the set of healthcare organizations that have clinical records for a given patient across Particle's network. Each entry represents an endpoint organization that has been observed querying or responding on behalf of the patient, enriched with directory information such as NPI, address, and the managing organization (implementer) behind the endpoint.

This is useful for:

Understanding which organizations hold records for a patient before or after a query
Identifying care relationships and provider footprint across networks
Supporting care coordination workflows that need to route to specific facilities

Availability

The Patient Provider Map is not enabled by default. To gain access, reach out to your Particle Health representative and we're happy to get you set up.

Endpoint

GET /api/v2/patients/{particle_patient_id}/provider_map

Returns the provider map for a single patient identified by their Particle Patient ID.

Path Parameters

Parameter	Type	Required	Description
`particle_patient_id`	string (UUID)	Yes	The Particle Patient ID for the patient

Authentication

Requires an API key passed in the Authorization header.

Response

{
  "particle_patient_id": "ac82d365-97f9-4111-92fa-3a2b92744b12",
  "providers": [
    {
      "oid": "2.16.840.1.113883.3.789",
      "organization_name": "Example Regional Medical Center",
      "network": "CAREQUALITY",
      "last_seen": "2025-12-15",
      "active": true,
      "type": "Practice",
      "npi": "1234567890",
      "address": "123 Health Ave",
      "city": "Springfield",
      "state": "IL",
      "postal_code": "62701",
      "lat": "39.799600",
      "lng": "-89.644600",
      "managing_organization_name": "Epic Systems",
      "managing_organization_oid": "2.16.840.1.113883.3.123"
    }
  ]
}

Response Fields

Top-level

Field	Type	Description
`particle_patient_id`	string	The Particle Patient ID for the patient
`providers`	array	List of provider organizations with records for the patient. Empty array if no records are found.

Provider entry fields

Field	Type	Required	Description
`oid`	string	Yes	Organization Identifier (OID) for the endpoint
`organization_name`	string	Yes	Name of the endpoint organization
`network`	string	Yes	Network source. Either `CAREQUALITY` or `EHEALTHEXCHANGE`
`last_seen`	string	Yes	Most recent date a record was observed for this patient at this organization, in `YYYY-MM-DD` format
`active`	boolean	No	Whether the endpoint is currently active in the directory
`type`	string	No	Organization type (e.g., `Practice`, `Implementer`)
`npi`	string	No	National Provider Identifier for the organization
`address`	string	No	Street address
`city`	string	No	City
`state`	string	No	State abbreviation
`postal_code`	string	No	ZIP code
`lat`	string	No	Latitude coordinate
`lng`	string	No	Longitude coordinate
`managing_organization_name`	string	No	Name of the managing (implementing) organization behind the endpoint
`managing_organization_oid`	string	No	OID of the managing organization

Error Responses

Status	Description
`400`	`particle_patient_id` is not a valid UUID
`401`	Missing or invalid API key
`404`	Patient not found
`500`	Internal server error

Provider Map Change Notifications

In addition to querying the provider map on demand, you can subscribe to receive webhook notifications when a patient's provider map changes. Two change types are supported:

`change_type`	Description
`new_provider`	A new organization OID appeared in the patient's provider map
`last_seen_updated`	An existing organization's `last_seen` date has advanced

To receive these notifications, create a providermap notification via the Management API. See Webhook Event Notifications for payload structure and signature verification.