Provider Data Management (PDM) API

The DexCare Provider Data Management (PDM) APIs are primarily for the extraction of provider related data from DexCare for use in other applications.

In DexCare an Entity represents a core data object within the system. Each entity is defined by a Schema that outlines its structure, including both required and optional properties.

See the full OpenAPI specification (OAS) for the PDM API.

Accessing the API

You will need an API Key in order to access the entities APIs.

You will specify the API key as part of the x-api-key header.

Ask you DexCare account representative for an API Key for the entities API.

DexCare Entities

The PDM APIs are based on DexCare’s Entities management system. DexCare’s Entities can be understood as a way to organize and manage information about various real-world things related to healthcare. Internally DexCare uses Entities to assure the consistency and atomicity of data as well as enforce that data adheres to an expected contract.

Think of Entities as the building blocks of information. Entities represent important items within DexCare such as:

• Staff (healthSystem.staff) — These are the healthcare professionals, which can include a broader range of roles beyond direct patient care, such as administrative or support roles. This Entity will also include Clinicians (healthSystem.clinician) as referenced entity (see below).
• Departments (healthSystem.department) : Different sections within a healthcare facility, like cardiology or pediatrics.
• Locations (healthSystem.location): Places where healthcare services are provided, such as hospitals or clinics. Multiple Departments and

DexCare Schemas

DexCare Schemas are like a blueprint or a set of rules that defines how Entities are structured and how they relate to one another. It outlines:

• What information is collected for each entity (like a provider’s name, specialty, and contact details).
• How different entities connect (for example, which providers work in which departments).

Schema Namespaces

In the context of the DexCare Entity API, a schema namespace helps to categorize and differentiate various Entities and their attributes. You must provide a namespace when querying our schema endpoint to retrieve a particular schema.

There are two high level namespaces that are most relevant to developers working with our API:

healthSystem — this is the namespace to which many Entities such as provider, department, location belong that are related to health systems.

assets — these are Entities that are useful utilities that may be used and shared by many different types of Entities, such as phone numbers.

Below is a non-comprehensive list of Entities and their namespaces which you will find useful.

Retrieving the Schema for a Given Entity

You will use /pdm/schema/ endpoint for either your production or UAT environment to retrieve the schema for a given entity.

Production Schema Endpoint

GET https://api.{externalDNS}/v1/pdm/schema/{namespace}/{name}

UAT Schema Endpoint

GET https://api.uat.{externalDNS}/v1/pdm/schema/{namespace}/{name}

Making requests to this endpoint will return a structure as follows:

{
  "title": "string",
  "description": "string",
  "$id": "string",
  "$schema": "string",
  "properties": {
    "id": {},
    "version": {},
    "type": {},
    "lastModifiedDate": {},
    "lastModifiedUser": {},
    "createdDate": {}
  }
}```

 

See the OpenAPI specification for complete documentation of the [PDM API](/api/oas/pdm).

For example, if you search for departments, it will return the following.

**Schema Request Example**

```shell
curl --location 'https://<BASEURL>/v1/pdm/schema/healthSystem/staff' \
-H “x-api-key: <YourApiKey>"

Schema Response Example

{
   "title":"staff",
   "$id":"https://dexcarehealth.com/schemas/healthSystem/staff",
   "dexProcessingDirectives":[
      "typescript",
      "persistance",
      "cache"
   ],
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "description":"Staff",
   "$ref":"https://dexcarehealth.com/schemas/core/entity",
   "enableAudit":true,
   "properties":{
      "businessLines":{
         "nullable":true,
         "items":{
            "$ref":"https://dexcarehealth.com/schemas/healthSystem/businessLine"
         },
         "tags":[
            
         ],
         "type":"array"
      },
      "businessUnits":{
         "nullable":true,
         "items":{
            "$ref":"https://dexcarehealth.com/schemas/healthSystem/businessUnit"
         },
         "tags":[
            
         ],
         "type":"array"
      },
      "clinician":{
         "nullable":true,
         "type":"object",
         "$ref":"https://dexcarehealth.com/schemas/healthSystem/clinician"
      },
      "createDate":{
         "format":"date-time",
         "type":"string"
      },      
      ...
      "type":{
         "const":"healthSystem.staff",
         "tags":[
            
         ],
         "type":"string"
      },
      "version":{
         "type":"string",
         "const":"13.12.3"
      }
   },
   "required":[
      "createDate",
      "id",
      "lastModifiedDate",
      "lastModifiedUser",
      "nameFirst",
      "nameLast",
      "type",
      "version"
   ],
   "tags":[
      "ingest",
      "omni",
      "fastPages"
   ],
   "type":"object",
   "unevaluatedProperties":false
}

Referenced Entities

Referenced entities in the context of the DexCare Provider Data Management (PDM) APIs are types of entities that are linked to other entities within the system. They serve as a way to establish relationships between different data objects, allowing for a more organized and interconnected data structure. For example, a healthcare provider entity may reference a department entity to indicate which department to which the provider belongs.

For instance, in the example above healthSysten.clincian is a reference object of staff.

      "clinician":{
         "nullable":true,
         "type":"object",
         "$ref":"https://dexcarehealth.com/schemas/healthSystem/clinician"
      },

Retrieving Entities in Batch

To export entity data from DexCare, you will use the PDM batch endpoint, e.g.

Production Batch Endpoint

POST https://api.{externalDNS}/v1/pdm/batch

UAT Batch Endpoint

POST https://api.uat.{externalDNS}/v1/pdm/batch

This API allows you to retrieve multiple entities of the same namespace and type.

This API uses a typical result set paging mechanism with optional offset and limit parameters. The result set that is returned will include the total number of items in the set as well individual entities in its data array.

Calling the batch API endpoint will return a structure as follows:

{
  "total": 1,
  "data": [
    {
      "type": "string",
      "version": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "lastModifiedDate": "2019-08-24T14:15:22Z",
      "createDate": "2019-08-24T14:15:22Z",
      "lastModifiedUser": "string"
    }
  ]
}

All Entities will share the common fields shown above.

See the OpenAPI specification for complete documentation of the PDM API.

Example Batch Call

Below is a simple request and response example for retrieving locations from DexCare.

Request

curl --header "Content-Type: application/json" \
  --request POST \
  -H "x-api-key: <YourApiKey>" \
  -H "Content-Type: application/json" \
  --data '{
   "namespace":"healthSystem",
   "type":"location",
   "offset":0,
   "limit":2
}' \
https://<BASE_URL>/v1/pdm/batch

Response

{
   "total":584,
   "data":[
      {
         "id":"00bab109-92e2-4522-894d-791242abfa15",
         "type":"healthSystem.location",
         "lastModifiedDate":"2025-03-11T22:32:15.399Z",
         "lastModifiedUser":"migrationClient",
         "createDate":"2025-03-11T22:34:15.671Z",
         "name":"PMG E WA FAMILY MEDICINE NORTH",
         "url":null,
         "country":"US",
         "county":"NONE",
         "conditionsTreated":null,
         "addressLine1":"212 E Central Ave Suite 440",
         "addressLine2":"",
         "city":"Spokane",
         "state":"WA",
         "postalCode":"99208",
         "latitude":47.7103226,
         "longitude":-117.4074194,
         ...
         "version":"15.0.0"
      },
      {
         "id":"00edb899-802d-41b9-8769-0000a2013a73",
         "type":"healthSystem.location",
         "lastModifiedDate":"2025-03-11T22:32:17.180Z",
         "lastModifiedUser":"migrationClient",
         "createDate":"2025-03-11T22:34:55.599Z",
         "name":"Swedish ExpressCare at Walgreens Bellevue",
         "url":null,
         "country":"US",
         "county":"NONE",
         "conditionsTreated":null,
         "addressLine1":"15585 NE 24th St",
         "addressLine2":"",
         "city":"Bellevue",
         "state":"WA",
         "postalCode":"98007",
         "latitude":47.6315452,
         "longitude":-122.1350994,
         ...
         "version":"15.0.0"
      }
   ]
}

Referenced Entities

In addition to the specific entity type that you are retrieving, the results may also include referenced entities from the schema.

Below is an example of the healthSystem.staff Entity and its reference objects healthSystem.clincian as defined by the schema as we saw above.

{
   "title":"staff",
   "$id":"https://dexcarehealth.com/schemas/healthSystem/staff",
   ...
   "properties":{
      ...
      "clinician":{
         "nullable":true,
         "type":"object",
         "$ref":"https://dexcarehealth.com/schemas/healthSystem/clinician"
      },
    ...

And this is an actual staff object with clinician data below it:

  {
     "id":"000b94e4-083e-4831-870d-0729dafedc0a",
     "type":"healthSystem.staff",
     "lastModifiedDate":"2025-03-11T22:32:27.564Z",
     "lastModifiedUser":"migrationClient",
     "createDate":"2025-03-11T22:38:05.108Z",
     "nameFirst":"Birendra",
     "nameLast":"Piya",
     ...
     "clinician":{
        "id":"6328500c-12c1-40c9-bf66-fbbc623fb5cf",
        "type":"healthSystem.clinician",
        "lastModifiedDate":"2025-03-11T22:32:27.564Z",
        "lastModifiedUser":"migrationClient",
        "createDate":"2025-03-11T22:38:05.162Z",
        ...

You can control the specific referenced entities returned using the resolveAllRefs (a Boolean), the refs parameters (an array of referenced entity names). This allows you to significantly reduce the size payload and the time a query takes to run by limiting the number of references that are returned.

curl --header "Content-Type: application/json" \
--request POST \
-H "x-api-key: <YourApiKey>" \
-H "Content-Type: application/json" \
--data '{  "namespace":"healthSystem", 
	         "type":"staff", 
	         "offset":0, 
	         "limit":2, 
	         "resolveAllRefs": false,
	         "refs" : [ "clinician" ]
	          }' \
https://entities-service.<BASEURL>/v1/pdm/batch

Filtering

The filters property of the entities API allows you to narrow the list of entities returned based on the values of different fields found on the entity as described in its schema.

For example, if you wanted to search for locations in the state of Washington (i.e. WA) you could execute a query as follows:

curl --header "Content-Type: application/json" \
  --request POST \
  -H "x-api-key: <YourApiKey>" \
  -H "Content-Type: application/json" \
  --data '{
   "namespace":"healthSystem",
   "type":"location",
   "offset":0,
   "limit":2,
   "filters": [
    {
    "field": "state",
    "value": "WA"
    }
  ]   
}' \
https://<BASE_URL>/v1/pdm/batch

Multiple filters are combined with an “AND” logical operator, meaning each filter criteria must be met in order for an entity to be returned in the batch result set,.