NAV
Ruby Shell

Provider Search Public API v2

The Oracle Health Data Intelligence Provider Search service enables you to search for provider personnel and organizations using configured workflows. V2 accepts a JSON POST body containing search criteria, pagination, and ordering controls.

A workflow can use parameter-based search or configured algorithms. When an algorithm qualifies for a request, the workflow uses its algorithmic ranking. See Ordering and Name Relevance for name-based searches when no algorithm qualifies.

URL: https://cernerdemo.api.us-1.healtheintent.com/provider-search/v2

The V1 GET search endpoints remain available. Use the Provider Search API V1 to manage workflows, workflow versions, algorithms, and their configuration. V2 provides the two search operations documented on this page.

Search Request

Both search operations require a JSON object in the request body. Authentication and workflow authorization use the same platform mechanism as V1.

Header Required Value
Authorization true The authorization header for the caller.
Content-Type true application/json
Accept Recommended application/json

Request Controls

Name Type Required Description
filter object false Search criteria in a root AND object. See Filter Criteria.
page object false Pagination controls.
page.limit integer false Maximum results per page, from 1 to 100. Send a JSON integer, not a string or fractional number.
page.offset integer false Zero-based number of results to skip, from 0 to 2147483647. Send a JSON integer.
orderBy array of objects false A nonempty, ordered list of sort fields and directions. Each entry requires field and direction.
orderBy[].field string true, for each entry name or providerRelationshipScore.
orderBy[].direction string true, for each entry asc or desc.
includeProviders boolean false Organization search only. When true, includes associated personnel in items[].providerPersonnels. This controls response expansion; provider criteria still filter organization eligibility when expansion is omitted.

Omitting filter applies no caller-supplied filter. Send explicit pagination values when you need a particular page size. An omitted orderBy uses the workflow’s default ordering described under Ordering and Name Relevance.

Filter Criteria

The current release supports a root AND containing criteria, including nested AND expressions. All criteria must match. Arbitrary OR combinations are not supported in this release.

For an exact criterion, multiple entries in values represent a union: any value can match. Repeated source-attribute criteria in AND require every value group to match. For example, one criterion whose values array contains both Refer From and Refer To matches either value; two criteria with one value each require both values.

Criterion type Required properties Description
field type, field, match, values Uses a supported field and its match mode from the endpoint’s field table below. values is a nonempty array of strings.
text type, query Broad text search across the existing V1 q fields. query is a nonblank string. This is not an exact field filter.
alias type, match, aliasSystem, aliasValue Matches an identity alias using match set to exact. Both the system and value are required.
geoDistance type, match, origin, radius Matches locations within a radius using match set to within. See Geographic Search.
sourceAttribute type, attributeName, match, values Organization search only. Matches an organization’s source attributes using match set to exact.
organizationSourceAttribute type, attributeName, match, values Personnel search only. Matches the assigning organization’s source attributes using match set to exact.

For both source-attribute criterion types, attributeName must be ORGANIZATION_TYPE or ORGANIZATION_ASSOCIATION_TYPE. values must contain one or more nonblank strings. Classification values are separate array entries, such as Refer From and Refer To; do not send one pipe-delimited value.

Personnel Search Fields

Field names Match Description
name, givenName, familyName partial Provider personnel name. Use name for canonical full-name relevance.
id, specialtyId, healthcareServiceId, serviceTypeId, serviceCategoryId, networkId, payerId, planId, locationId, organizationId, linkPersonnelId exact Entity identifiers. Multiple values in one criterion use union semantics.
language, gender, state, postalCode exact Language, gender, or location eligibility. Gender codes are male, female, other, and unknown.
specialtyName, healthcareServiceName, serviceTypeName, serviceCategoryName, networkName, payerName, planName, locationName, city, organizationName partial Names of related services, networks, locations, or assigning organizations.

Organization Search Fields

Field names Match Description
name, specialtyName, networkName, payerName, planName, locationName, city partial Organization name or names associated with its provider relationships.
id, specialtyId, networkId, payerId, planId, locationId, linkOrganizationId exact Entity identifiers. Multiple values in one criterion use union semantics.
state, postalCode exact Organization location eligibility.
providerPersonnelGender, providerPersonnelLanguage exact Eligibility of associated provider personnel. Gender codes are male, female, other, and unknown.
providerPersonnelName partial Name of associated provider personnel.

One associated provider must satisfy all supplied provider-personnel criteria. An organization with no associated providers, or with no single provider satisfying the complete expression, is excluded. When includeProviders is true and provider-personnel criteria are supplied, providerPersonnels contains the matching personnel.

Ordering and Name Relevance

Filtering determines eligibility before ordering and pagination. Use orderBy to request a supported sort field and direction. To use the default name-relevance behavior, omit orderBy.

For personnel search in a non-algorithmic workflow, a name criterion ranks eligible providers by how closely their names match the supplied text. This also applies when a workflow has algorithms but none meets its activation conditions. Other criteria, such as specialtyName and organizationName, narrow eligibility without contributing to the provider-name score. When an algorithm qualifies, its existing algorithmic ranking applies.

For organization search without a qualifying algorithm, the default behavior depends on the name criteria:

Name criteria Eligibility and ordering
name only Matches organization names and retains organization-name ordering.
name and providerPersonnelName Both must match. Organization-name ordering remains primary.
providerPersonnelName only Requires a matching associated provider and orders organizations by their best associated-provider name relevance.

Workflow activation conditions can depend on alias criteria. Include an alias criterion only when the identity filter is intended; it can activate a configured algorithm and therefore change ranking.

Provider Personnel Search

Search Provider Personnel

POST /workflows/{workflowId}/provider-personnel-search

Returns provider personnel satisfying the search criteria. This example searches for a provider named Julie at a practice site matching Baseline, where the assigning organization is External and has either the Refer From or Refer To association.

All organizationSourceAttribute criteria must match one assigning-organization relationship. Values from different assigning organizations cannot be combined to satisfy the expression.

Example Request:

require 'httparty'
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

body = JSON.parse(<<~JSON)
{
  "filter": {
    "AND": [
      {
        "type": "field",
        "field": "name",
        "match": "partial",
        "values": [
          "Julie"
        ]
      },
      {
        "type": "field",
        "field": "organizationName",
        "match": "partial",
        "values": [
          "Baseline"
        ]
      },
      {
        "type": "organizationSourceAttribute",
        "attributeName": "ORGANIZATION_TYPE",
        "match": "exact",
        "values": [
          "External"
        ]
      },
      {
        "type": "organizationSourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer From",
          "Refer To"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}
JSON

result = HTTParty.post(
  'https://cernerdemo.api.us-1.healtheintent.com/provider-search/v2/workflows/{workflowId}/provider-personnel-search',
  headers: headers,
  body: body.to_json
)

print JSON.pretty_generate(result)

curl -X POST 'https://cernerdemo.api.us-1.healtheintent.com/provider-search/v2/workflows/{workflowId}/provider-personnel-search' \
  -H 'Authorization: {auth_header}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary @- <<'JSON'
{
  "filter": {
    "AND": [
      {
        "type": "field",
        "field": "name",
        "match": "partial",
        "values": [
          "Julie"
        ]
      },
      {
        "type": "field",
        "field": "organizationName",
        "match": "partial",
        "values": [
          "Baseline"
        ]
      },
      {
        "type": "organizationSourceAttribute",
        "attributeName": "ORGANIZATION_TYPE",
        "match": "exact",
        "values": [
          "External"
        ]
      },
      {
        "type": "organizationSourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer From",
          "Refer To"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}
JSON

Example response

{
  "items": [
    {
      "id": "11f185063881e20395a8bb4ee73b1ec2",
      "name": {
        "text": "Sheets MD, Julie",
        "family": "Sheets",
        "given": [
          "Julie"
        ],
        "suffix": [
          "MD"
        ]
      },
      "aliases": [
        {
          "system": "MILLENNIUM",
          "type": "ID",
          "value": "4601845"
        }
      ],
      "providerRelationships": [
        {
          "assigningOrganization": {
            "id": "11f185063af77671a7033521ce9a80e5",
            "name": "Baseline Practice",
            "telecoms": [
              {
                "system": "PHONE",
                "value": "(816) 555-0104",
                "use": "WORK",
                "rank": 1
              }
            ],
            "aliases": [
              {
                "system": "MILLENNIUM",
                "type": "ID",
                "value": "88003"
              }
            ],
            "sourceAttributes": [
              {
                "name": "ORGANIZATION_TYPE",
                "values": [
                  "External"
                ]
              },
              {
                "name": "ORGANIZATION_ASSOCIATION_TYPE",
                "values": [
                  "Employed",
                  "Refer From",
                  "Refer To"
                ]
              }
            ]
          }
        }
      ],
      "gender": {
        "code": "female",
        "system": "http://hl7.org/fhir/administrative-gender",
        "display": "Female"
      },
      "communications": [
        {
          "code": {
            "codings": [
              {
                "code": "en-US",
                "system": "BCP-47",
                "display": "English (United States)"
              }
            ],
            "text": "English"
          }
        }
      ]
    }
  ],
  "totalResults": 1,
  "page": {
    "limit": 20,
    "offset": {
      "current": 0,
      "first": 0,
      "previous": null,
      "next": null,
      "last": 0
    }
  }
}

Personnel Search Parameters

Parameter In Type Required Description
workflowId path string true The ID of the configured search workflow.
body body postWorkflowsWorkflowidProviderPersonnelSearch true The JSON search request.

Personnel Search Response Statuses

Status Description Schema
200 Search completed. PersonnelResult
400 Invalid JSON, filter, pagination, or ordering. Error
401 Authentication failed. Error
403 The caller is not authorized for the workflow or tenant. Error

See Error Handling for additional platform responses.

Provider Organization Search

Search Provider Organizations

POST /workflows/{workflowId}/provider-organization-search

Returns provider organizations satisfying the search criteria. This example requires an External organization with either the Refer From or Refer To association and at least one female provider who communicates in English. It expands the response to include matching providers.

Example Request:

require 'httparty'
require 'json'

headers = {
  'Authorization' => '<auth_header>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

body = JSON.parse(<<~JSON)
{
  "filter": {
    "AND": [
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_TYPE",
        "match": "exact",
        "values": [
          "External"
        ]
      },
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer From",
          "Refer To"
        ]
      },
      {
        "type": "field",
        "field": "providerPersonnelGender",
        "match": "exact",
        "values": [
          "female"
        ]
      },
      {
        "type": "field",
        "field": "providerPersonnelLanguage",
        "match": "exact",
        "values": [
          "English"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  },
  "includeProviders": true,
  "orderBy": [
    {
      "field": "name",
      "direction": "asc"
    }
  ]
}
JSON

result = HTTParty.post(
  'https://cernerdemo.api.us-1.healtheintent.com/provider-search/v2/workflows/{workflowId}/provider-organization-search',
  headers: headers,
  body: body.to_json
)

print JSON.pretty_generate(result)

curl -X POST 'https://cernerdemo.api.us-1.healtheintent.com/provider-search/v2/workflows/{workflowId}/provider-organization-search' \
  -H 'Authorization: {auth_header}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary @- <<'JSON'
{
  "filter": {
    "AND": [
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_TYPE",
        "match": "exact",
        "values": [
          "External"
        ]
      },
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer From",
          "Refer To"
        ]
      },
      {
        "type": "field",
        "field": "providerPersonnelGender",
        "match": "exact",
        "values": [
          "female"
        ]
      },
      {
        "type": "field",
        "field": "providerPersonnelLanguage",
        "match": "exact",
        "values": [
          "English"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  },
  "includeProviders": true,
  "orderBy": [
    {
      "field": "name",
      "direction": "asc"
    }
  ]
}
JSON

Example response

{
  "items": [
    {
      "id": "11f185063af77671a7033521ce9a80e5",
      "name": "Baseline Practice",
      "aliases": [
        {
          "system": "MILLENNIUM",
          "type": "ID",
          "value": "88003"
        }
      ],
      "sourceAttributes": [
        {
          "name": "ORGANIZATION_TYPE",
          "values": [
            "External"
          ]
        },
        {
          "name": "ORGANIZATION_ASSOCIATION_TYPE",
          "values": [
            "Employed",
            "Refer From",
            "Refer To"
          ]
        }
      ],
      "telecoms": [
        {
          "system": "PHONE",
          "value": "(816) 555-0104",
          "use": "WORK",
          "rank": 1
        }
      ],
      "providerPersonnels": [
        {
          "id": "11f185063881e20395a8bb4ee73b1ec2",
          "name": {
            "text": "Sheets MD, Julie",
            "family": "Sheets",
            "given": [
              "Julie"
            ],
            "suffix": [
              "MD"
            ]
          },
          "aliases": [
            {
              "system": "MILLENNIUM",
              "type": "ID",
              "value": "4601845"
            }
          ],
          "providerRelationships": [
            {
              "assigningOrganization": {
                "id": "11f185063af77671a7033521ce9a80e5",
                "name": "Baseline Practice",
                "telecoms": [
                  {
                    "system": "PHONE",
                    "value": "(816) 555-0104",
                    "use": "WORK",
                    "rank": 1
                  }
                ],
                "aliases": [
                  {
                    "system": "MILLENNIUM",
                    "type": "ID",
                    "value": "88003"
                  }
                ],
                "sourceAttributes": [
                  {
                    "name": "ORGANIZATION_TYPE",
                    "values": [
                      "External"
                    ]
                  },
                  {
                    "name": "ORGANIZATION_ASSOCIATION_TYPE",
                    "values": [
                      "Employed",
                      "Refer From",
                      "Refer To"
                    ]
                  }
                ]
              }
            }
          ],
          "gender": {
            "code": "female",
            "system": "http://hl7.org/fhir/administrative-gender",
            "display": "Female"
          },
          "communications": [
            {
              "code": {
                "codings": [
                  {
                    "code": "en-US",
                    "system": "BCP-47",
                    "display": "English (United States)"
                  }
                ],
                "text": "English"
              }
            }
          ]
        }
      ]
    }
  ],
  "totalResults": 1,
  "page": {
    "limit": 20,
    "offset": {
      "current": 0,
      "first": 0,
      "previous": null,
      "next": null,
      "last": 0
    }
  }
}

Organization Search Parameters

Parameter In Type Required Description
workflowId path string true The ID of the configured search workflow.
body body postWorkflowsWorkflowidProviderOrganizationSearch true The JSON search request.

Organization Search Response Statuses

Status Description Schema
200 Search completed. OrganizationResult
400 Invalid JSON, filter, pagination, or ordering. Error
401 Authentication failed. Error
403 The caller is not authorized for the workflow or tenant. Error

See Error Handling for additional platform responses.

Search Examples

These JSON bodies use the same POST endpoints and headers shown above.

Canonical Provider Name

Send this body to personnel search to find Sheets MD, Julie. Omit orderBy to use default name relevance when no algorithm qualifies. Additional criteria can narrow eligibility without adding to the name-relevance score.

{
  "filter": {
    "AND": [
      {
        "type": "field",
        "field": "name",
        "match": "partial",
        "values": [
          "Sheets MD, Julie"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

Organization and Associated Provider Names

Send this body to organization search. Both the organization name and an associated provider name must match. Organization-name ordering remains primary, and the expanded personnel list contains matching providers.

{
  "filter": {
    "AND": [
      {
        "type": "field",
        "field": "name",
        "match": "partial",
        "values": [
          "Baseline"
        ]
      },
      {
        "type": "field",
        "field": "providerPersonnelName",
        "match": "partial",
        "values": [
          "Julie"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  },
  "includeProviders": true
}

To search solely by associated provider name, omit the name criterion. When no algorithm qualifies and orderBy is omitted, organizations are ordered by their best associated-provider name relevance.

Require Both Organization Associations

Send this body to organization search to require both Refer From and Refer To. Both criteria must match the same organization’s source attribute. To filter personnel by the assigning organization instead, change each criterion’s type to organizationSourceAttribute and use the personnel search endpoint.

{
  "filter": {
    "AND": [
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer From"
        ]
      },
      {
        "type": "sourceAttribute",
        "attributeName": "ORGANIZATION_ASSOCIATION_TYPE",
        "match": "exact",
        "values": [
          "Refer To"
        ]
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

Identity Alias

Send this body to organization search to match an identity alias. Both aliasSystem and aliasValue are required. Use source-attribute criteria for organization classifications.

{
  "filter": {
    "AND": [
      {
        "type": "alias",
        "match": "exact",
        "aliasSystem": "MILLENNIUM",
        "aliasValue": "88003"
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

Broad Text Search

Send this body to either search endpoint for the broad search previously requested with the V1 q parameter. To search specifically by provider name, use the personnel name field criterion instead.

{
  "filter": {
    "AND": [
      {
        "type": "text",
        "query": "Cardiology"
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

A geoDistance criterion accepts an origin containing both numeric latitude and longitude, or a postal-code origin containing a string value. Supply a radius with numeric value and unit set to mi. The match value is within.

Send this body to either endpoint to search within 25 miles of the supplied coordinates:

{
  "filter": {
    "AND": [
      {
        "type": "geoDistance",
        "match": "within",
        "origin": {
          "latitude": 40.0423,
          "longitude": -75.6323
        },
        "radius": {
          "value": 25,
          "unit": "mi"
        }
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

For a postal-code origin, use this body:

{
  "filter": {
    "AND": [
      {
        "type": "geoDistance",
        "match": "within",
        "origin": {
          "value": "19020"
        },
        "radius": {
          "value": 25,
          "unit": "mi"
        }
      }
    ]
  },
  "page": {
    "limit": 20,
    "offset": 0
  }
}

Pagination

Both endpoints return items, totalResults, and page. totalResults is the number of matching results before pagination. The response page.offset is an object containing numeric page positions; the request page.offset is a single integer.

Response field Description
page.limit The page size applied to the request.
page.offset.current The offset of the current page.
page.offset.first The first page’s offset, 0.
page.offset.previous The previous page’s offset, or null when there is no previous page.
page.offset.next The next page’s offset, or null when there is no next page.
page.offset.last The offset of the last page.

To retrieve the next page, resubmit the same filter, limit, ordering, and expansion controls, changing only the request’s page.offset to the response’s page.offset.next. Stop when next is null. V2 uses these offsets instead of V1 pagination links.

For example, a result set of 45 organizations with a page size of 20 has offsets 0, 20, and 40. On the second page, the response pagination is:

{
  "limit": 20,
  "offset": {
    "current": 20,
    "first": 0,
    "previous": 0,
    "next": 40,
    "last": 40
  }
}

Organization Source Attributes

Organization classification metadata is represented by sourceAttributes, an array of objects containing name and values. Identity aliases, such as a Millennium ID, remain in aliases.

Search endpoint Response location Filter criterion type
Organization items[].sourceAttributes sourceAttribute
Personnel items[].providerRelationships[].assigningOrganization.sourceAttributes organizationSourceAttribute

The Provider API V2 supports reading, creating, and updating source attributes on provider organizations. Provider Search currently supports exact classification filters for ORGANIZATION_TYPE and ORGANIZATION_ASSOCIATION_TYPE.

Error Handling

Invalid requests return 400 Bad Request, including malformed JSON, a body that is not an object, unsupported filters, missing criterion properties, invalid source-attribute values, and invalid pagination or ordering. Correct the request before retrying it. The public error envelope contains an integer HTTP status code, a message, and optional errorDetails.

For example, a JSON array instead of an object produces:

{
  "code": 400,
  "message": "Bad Request",
  "errorDetails": [
    {
      "message": "body must be a JSON object"
    }
  ]
}

Authentication and authorization failures return 401 or 403. The platform can also return 415 for an unsupported media type, 429 for rate or concurrency limits, and 5xx for service failures. Send Content-Type: application/json, honor Retry-After when supplied, and use bounded retry with backoff for retryable failures. Use the HTTP status and error code rather than parsing prose messages.

Migrating from V1

V1 request or response V2 equivalent
GET /provider-search/v1/workflows/{workflowId}/provider-personnel-search POST /provider-search/v2/workflows/{workflowId}/provider-personnel-search with a JSON body.
GET /provider-search/v1/workflows/{workflowId}/provider-organization-search POST /provider-search/v2/workflows/{workflowId}/provider-organization-search with a JSON body.
Search query parameters Supported typed criteria inside filter.AND. Use the endpoint-specific field and match tables.
q A text criterion with query.
aliasSystem and aliasValue One alias criterion containing both values.
Organization classification alias values sourceAttribute for organizations, or organizationSourceAttribute for personnel.
Latitude/longitude or postal code with distance A geoDistance criterion with origin and radius.
limit and offset page.limit and page.offset in the body.
orderBy An array of objects containing field and direction.
includeProviders A top-level boolean on organization search only.
Pagination links Numeric offsets in the response page.offset object.

Keep the existing authorization header and add Content-Type: application/json. Compare results for your configured workflows before moving an integration to V2.

Schema Definitions

PersonnelResult

Name Type Required Description Accepted Values
totalResults integer(int32) true Total number of matching results before pagination. -
page Page true Pagination details for this response. -
items [V2ProviderPersonnel] true The matching personnel on this page. -

Page

Name Type Required Description Accepted Values
limit integer(int32) true The page size applied to the request. -
offset Offset true Numeric page positions for this response. -

Offset

Name Type Required Description Accepted Values
current integer(int32) true The current page offset. -
first integer(int32) true The first page offset, 0. -
last integer(int32) true The last page offset. -
previous integer(int32)\ null true The previous page offset, or null when unavailable.
next integer(int32)\ null true The next page offset, or null when unavailable.

V2ProviderPersonnel

Name Type Required Description Accepted Values
id string true The unique ID of the Oracle Health Data Intelligence provider personnel entity. -
name Name false The name associated with the provider personnel entity. -
gender GenderCode false The gender of the provider personnel entity. -
age integer(int32) false The age of the provider personnel entity. -
communications [Communication] false The language or languages the provider personnel entity can use in patient communication. -
photo Photo false The image associated with the provider personnel entity. -
telecoms [DemographicTelecom] false The contact details for the provider personnel entity that apply to all roles. -
qualifications [Qualification] false The certification, licenses, or training associated with the provider personnel entity that pertain to the provision of care. -
link Link false A reference to another personnel entity who is identified as the same person described in this provider personnel entity. See the Personnel section on the Personnel API v1 page for more information. -
isPcp boolean false Indicates whether the provider personnel entity is a primary care physician (PCP). -
aliases [V2Alias] false Identity aliases for this entity. -
providerRelationships [V2ProviderRelationships] false The provider personnel relationships. -

Name

Name Type Required Description Accepted Values
text string false The text representation of the full name. -
family string false The family name or surname of the provider personnel entity. -
given [string] false The given names of the provider personnel entity, including the middle name. -
prefix [string] false The prefix of the name. -
suffix [string] false The suffix of the name. -

GenderCode

Name Type Required Description Accepted Values
code string true The unique ID of the gender code. The following values are available: male, female, other, and unknown. male, female, other, unknown
system string true The ID of the coding system associated with the code. -
display string false The human-readable representation of the gender code. Male, Female, Other, Unknown

Communication

Name Type Required Description Accepted Values
code Language true The language code the practitioner can use in patient communication. -

Language

Name Type Required Description Accepted Values
codings [LanguageCode] true A list of codified values from a standard code system. -
text string false The text representation of a language. -

LanguageCode

Name Type Required Description Accepted Values
code string true The unique ID of the language code. -
system string true The ID of the coding system associated with the language code. -
display string false A human-readable representation of the language code. -

Photo

Name Type Required Description Accepted Values
contentType string true The mime type of the content. The following values are possible: IMAGE/JPG, IMAGE/JPEG, IMAGE/GIF, and IMAGE/PNG. IMAGE/JPG, IMAGE/JPEG, IMAGE/GIF, IMAGE/PNG
url string true The reference to the physical location of the photo. -
title string false The name of the photo. -

DemographicTelecom

Name Type Required Description Accepted Values
system string true The system associated with the contact point for a provider personnel entity. The following values are available: EMAIL, PHONE, FAX, SMS, URL, DIRECT, and OTHER. EMAIL, PHONE, FAX, SMS, URL, DIRECT, OTHER
value string true The contact point details for a provider personnel entity. If you specify a value, system is required. -
use string false The purpose for which the contact details can be used. The following values are available: HOME, MOBILE, OLD, TEMP, and WORK. HOME, MOBILE, OLD, TEMP, WORK
rank integer(int32) false The rank based on other provided telecoms. This must be a numeric value that is greater than zero. Telecoms without a rank are considered equal to other unranked telecoms. Ranked telecoms are ordered above unranked telecoms. -

Qualification

Name Type Required Description Accepted Values
identifier string false The ID for this qualification for the provider personnel entity. -
type Code false Indicates whether this qualification is associated with a degree, training, certification, or license. -
text string true The text associated with the qualification. -
code QualificationCode false The code associated with the qualification. -
period Period false The time period during which the qualification is valid. -
reverificationDate string false The date when the qualification must be reverified, in ISO 8601 formatting with precision ranging from YYYY to YYYY-MM-DD. -
issuer QualificationIssuer false The organization that regulates and issues the qualification. You can use either the name or reference. -

Code

Name Type Required Description Accepted Values
code string true The unique ID of the code. -
display string false A human-readable representation of the code. -
system string true The ID of the coding system that gives meaning to the code. -

QualificationCode

Name Type Required Description Accepted Values
codings [Code] false A list of codified values from a standard code system. -
text string false The text that represents the consolidated display of different codings inside the code object. -

Period

Name Type Required Description Accepted Values
start string false The start date of the effective period of the qualification, in ISO 8601 format with precision ranging from YYYY to YYYY-MM-DD. -
end string false The end date of the effective period of the qualification, in ISO 8601 format with precision ranging from YYYY to YYYY-MM-DD. -

QualificationIssuer

Name Type Required Description Accepted Values
name string false The name of the issuer. -
reference string false The reference associated with the issuer. -

Name Type Required Description Accepted Values
target Target true No description -

Target

Name Type Required Description Accepted Values
id string true The unique ID of the targeted provider personnel reference. -
display string false The name of the provider personnel entity. -

V2Alias

Name Type Required Description Accepted Values
system string true The authority responsible for assigning the alias value. Alias values are unique within this system namespace but not across systems. -
value string true The unique ID of the alias associated with the system or assigning authority. -
type string false The source-system alias type. -

V2ProviderRelationships

Name Type Required Description Accepted Values
locations [Location] false The name of a location where the provider personnel entity offers care. -
telecoms [DemographicTelecom] false The contact details for the provider personnel relationship. -
networks [Network] false The list of networks with which the provider personnel entity has a contractual relationship to provide services. -
specialties [Specialty] false The specialties of the provider personnel entity. -
healthcareServices [HealthcareService] false The healthcare services associated with the provider personnel entity. -
acceptingPatients boolean false Indicates whether the provider personnel entity is accepting patients. -
providerRelationshipScore [ProviderRelationshipScore] false The custom score based on the algorithm’s factors calculated for each provider. A provider relationship score is calculated for each role and location of the provider. The highest provider relationship score calculated for each provider is used to identify the ranking of providers in the ordered search result based on the filter conditions applied in the search request. -
assigningOrganization V2Organization false The organization assigning the provider relationship. -

Location

Name Type Required Description Accepted Values
id string true The unique ID of the location. -
name string false The name of the location. -
text string false The consolidated display of location name and fully formatted address. -
use string false The purpose of the address. The following values are possible: HOME, BILLING, OLD, TEMP, WORK, and PRIMARY. HOME, BILLING, OLD, TEMP, WORK, PRIMARY
lines [string] false An ordered list of address lines indicating the house number, apartment number, street name, street direction, PO Box number, and similar address information. -
city string false The name of the city, town, or village. -
state string false The state or other subunit of a country. -
country string false The nation specified for this address. -
postalCode string false The region defined by the postal service for this address. -
telecoms [DemographicTelecom] false The contact details for the location. -
geoLocation GeoLocation false The geographic location of a location for this address. -
distance Distance false The distance of this provider location from a specified point. -
managingOrganization ManagingOrganization false The organization responsible for the provisioning and upkeep of the location. This organization can also be used as part of the organizational hierarchy where this location provides services. -
aliases [Alias] false The aliases of the provider location. -

GeoLocation

Name Type Required Description Accepted Values
latitude number(float) true The latitude coordinate of the location. In ISO 6709 format, the standard representation of geographic point location by coordinates, the format, and precision ranges from +/-DD.DDDD to +/-DD.DDDDDD. -
longitude number(float) true The longitude coordinate of the location. In ISO 6709, the standard representation of geographic point location by coordinates, the format, and precision ranges from +/-DD.DDDD to +/-DD.DDDDDD. -

Distance

Name Type Required Description Accepted Values
value number(float) true The actual value of the distance. A unit is required if a value is provided. -
unit string true The unit that represents the distance. The following values are possible: mi, yd, ft, in, km, m, cm, mm, nm. mi, yd, ft, in, km, m, cm, mm, nm

ManagingOrganization

Name Type Required Description Accepted Values
id string true The unique ID of the provider organization. -
name string false The name of the provider organization. -
aliases [Alias] false The aliases of the provider organization. -

Alias

Name Type Required Description Accepted Values
system string true The authority responsible for assigning the alias value. Alias values are unique within this system namespace but not across systems. -
type string false The type of alias. The following values are available: SPI, NPI, DEA, TAX, SL, EXTERNAL, UPIN, USER, and UNKNOWN. SPI, NPI, DEA, TAX, SL, EXTERNAL, UPIN, USER, UNKNOWN
value string true The unique ID of the alias associated with the system or assigning authority. -

Network

Name Type Required Description Accepted Values
id string true The unique ID for the provider network. -
name string false The name of the provider network. -
payer Payer true The payers associated with the network. -
plan Plan true The plan for which a network is defined. -
relationshipType string false The type of contractual relationship the provider has with the specified provider network. -

Payer

Name Type Required Description Accepted Values
id string true The unique ID of the provider personnel payer. -
name string false The name of the provider personnel payer. -

Plan

Name Type Required Description Accepted Values
id string true The unique ID of the plan. -
name string false The name of the plan. -

Specialty

Name Type Required Description Accepted Values
id string true The unique ID of the specialty. -
name string false The name of the specialty. -
taxonomy Taxonomy true The taxonomy ID and taxonomy name that is related to the provider specialty. -
isPrimary boolean false Indicates whether a specialty is the primary specialty. -

Taxonomy

Name Type Required Description Accepted Values
id string true The unique ID of the taxonomy. -
name string true The name of the taxonomy. -

HealthcareService

Name Type Required Description Accepted Values
id string true The unique ID of the healthcare service. -
name string false The name of the healthcare service. -
serviceType ServiceType false The service type associated with the healthcare service. -
serviceCategory ServiceCategory false The service category associated with the healthcare service. -

ServiceType

Name Type Required Description Accepted Values
id string true The unique ID of the service type. -
name string false The name of the service type. -

ServiceCategory

Name Type Required Description Accepted Values
id string true The unique ID of the service category. -
name string false The name of the service category. -

ProviderRelationshipScore

Name Type Required Description Accepted Values
score integer(int32) false The composite score of the provider personnel relationship. -
calculatedBy CalculatedBy false The algorithm used to calculate the provider relationship composite score. -
basis [Basis] false Indicates the concept that has a direct relation to the provider relationship score calculation. -

CalculatedBy

Name Type Required Description Accepted Values
id string true The unique ID of the provider search algorithm. -
title string false The title of the provider search algorithm. -
factors [Factor] false The group of individual components that contribute to calculating the provider relationship score as part of the provider search outcomes. -

Factor

Name Type Required Description Accepted Values
id string true The unique ID of the algorithm factor. -
title string false The title of the algorithm factor. -
score integer(int32) true The score calculated for the algorithm factor. -

Basis

Name Type Required Description Accepted Values
id string true The unique provider location ID that has a direct relation to the provider relationship score calculation. -
kind string true The name of the concept with a direct relation to the provider relationship score calculation. -

V2Organization

Name Type Required Description Accepted Values
id string true The unique ID for the provider organization. -
name string false The name of the provider organization. -
telecoms [DemographicTelecom] false The contact details for the provider organization relationship. -
aliases [V2Alias] false Identity aliases for this entity. -
sourceAttributes [SourceAttribute] false Source-system attributes associated with this organization. -

SourceAttribute

Name Type Required Description Accepted Values
name string true The source attribute name. -
values [string] true The individual values of the source attribute. -

OrganizationResult

Name Type Required Description Accepted Values
totalResults integer(int32) true Total number of matching results before pagination. -
page Page true Pagination details for this response. -
items [V2ProviderOrganization] true The matching organizations on this page. -

V2ProviderOrganization

Name Type Required Description Accepted Values
id string true The unique ID for the provider organization. -
name string false The name of the provider organization. -
telecoms [DemographicTelecom] false The contact details for the provider organization entity that apply to all roles. -
link Link false A reference to another organization entity who is identified as the same person described in this provider organization entity. See the Organization section on the Organization API v1 page for more information. -
providerRelationships [OrganizationProviderRelationships] false The specific set of an organization’s relationships to locations, specialties, networks, and services that they may perform at an organization. -
partOf PartOf false The parent or owning organization. -
aliases [V2Alias] false Identity aliases for this entity. -
sourceAttributes [SourceAttribute] false Source-system attributes associated with this organization. -
providerPersonnels [V2ProviderPersonnel] false Associated personnel included when includeProviders is true; filtered by supplied provider-personnel criteria. -

OrganizationProviderRelationships

Name Type Required Description Accepted Values
locations [Location] false The name of a location where the provider organization entity offers care. -
telecoms [DemographicTelecom] false The contact details for the provider organization relationship. -
networks [Network] false The list of networks with which the provider organization entity has a contractual relationship to provide services. -
specialties [Specialty] false The specialties of the provider organization entity. -
providerRelationshipScore [ProviderRelationshipScore] false The custom score based on the algorithm’s factors calculated for each provider. A provider relationship score is calculated for each role and location of the provider. The highest provider relationship score calculated for each provider is used to identify the ranking of providers in the ordered search result based on the filter conditions applied in the search request. -
acceptingPatients boolean false Indicates whether the provider organization entity is accepting patients. -

PartOf

Name Type Required Description Accepted Values
id string false The ID of the parent organization. -
display string false The display name of the parent organization. -
aliases [Alias] false The aliases of the parent organization. -

postWorkflowsWorkflowidProviderOrganizationSearch

Name Type Required Description Accepted Values
filter object false A root AND containing the supported Filter Criteria. Organization search uses sourceAttribute; personnel search uses organizationSourceAttribute. -
page object false Pagination object with optional limit (1-100) and non-negative offset. -
» limit integer(int32) false Maximum number of results to return (1-100). -
» offset integer(int32) false Zero-based number of results to skip, from 0 to 2147483647. -
orderBy [object] false A nonempty array of sort objects. Each contains a supported field and an asc or desc direction. -
» field string true The field to sort by. name, providerRelationshipScore
» direction string true Sort direction. asc, desc
includeProviders boolean false When true, include the provider personnel associated with each returned organization. -

Error

Name Type Required Description Accepted Values
code integer(int32) true The HTTP response status code that represents the error. -
message string true A human-readable description of the error. -
errorDetails [ErrorDetail] false A list of additional error details. -

ErrorDetail

Name Type Required Description Accepted Values
domain string false A subsystem or context where an error occurred. -
reason string false A codified value that represents the specific error that caused the current error status. -
message string false A human-readable description of an error. -
locationType string false The location or type of the field that caused an error. query, header, path, formData, body
location string false The name of the field that caused an error. -

postWorkflowsWorkflowidProviderPersonnelSearch

Name Type Required Description Accepted Values
filter object false A root AND containing the supported Filter Criteria. Organization search uses sourceAttribute; personnel search uses organizationSourceAttribute. -
page object false Pagination object with optional limit (1-100) and non-negative offset. -
» limit integer(int32) false Maximum number of results to return (1-100). -
» offset integer(int32) false Zero-based number of results to skip, from 0 to 2147483647. -
orderBy [object] false A nonempty array of sort objects. Each contains a supported field and an asc or desc direction. -
» field string true The field to sort by. name, providerRelationshipScore
» direction string true Sort direction. asc, desc
Ruby Shell