NAV Navbar
Logo cerner
Ruby Shell

Specialty Open API v1

The Specialty API allows you to create, update, and retrieve the definition of specialties that may be practiced by service providers in a health care system. You also can use the API to create or retrieve specialty concepts in the context of a taxonomy. A taxonomy supports a hierarchy of specialty and subspecialty definitions that an enterprise can associate with health care services and providers in HealtheIntent. After you define taxonomies, you can define specialty instances to assign specialties to specific taxonomies. The Specialty API is especially useful for referral management, orders processing, and scheduling systems.

A taxonomy is a hierarchical code set definition consisting of specialties and subspecialties. A taxonomy provides a context for a curated list of specialties that may be practiced by one or more health care professionals. See the following examples of taxonomy definitions:

A specialty is a specialized medical practice offered by a clinician or provider based on their training or clinical focus. You can define the specialities that are available to your organizations See the following examples of specialties:

URL: https://cernerdemo.api.us.healtheintent.com/specialty/v1

Taxonomies

Taxonomies are derived from the Centers for Medicare & Medicaid Services (CMS) Healthcare Provider Taxonomy Code Set. The taxonomy provides a context for a curated list of specialties that may be practiced by one or more health care professionals.

Create a Taxonomy

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.post('https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies', headers: headers, body: {"name":"CMS Taxonomy","description":"CMS Healthcare Provider Taxonomy Code Set"}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X POST https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"name":"CMS Taxonomy","description":"CMS Healthcare Provider Taxonomy Code Set"}

POST /taxonomies

Creates a taxonomy.

Parameters

Parameter In Type Required Default Description Accepted Values
body body postTaxonomies true N/A No description -

Response Statuses

Status Meaning Description Schema
201 Created No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
409 Conflict Conflict Error

Response Headers

Status Header Type Format Description
201 Location string The URL of the created taxonomy.

Retrieve a List of Taxonomies

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "id": "cc46c4c2deac11e7a3d646705f8c9e77",
      "name": "CMS Taxonomy",
      "description": "CMS Healthcare Provider Taxonomy Code Set",
      "createdAt": "2018-04-21T16:14:53Z",
      "updatedAt": "2018-04-21T16:14:53Z"
    },
    {
      "id": "533cfba4dead11e7a3d646705f8c9e77",
      "name": "NUCC Taxonomy",
      "description": "NUCC Health Care Provider Taxonomy",
      "createdAt": "2018-04-21T16:14:53Z",
      "updatedAt": "2018-04-21T16:14:53Z"
    }
  ],
  "totalResults": 2,
  "firstLink": "http://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies?offset=0&limit=20",
  "lastLink": "http://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies?offset=0&limit=20"
}

GET /taxonomies

Retrieves a list of taxonomies.

Parameters

Parameter In Type Required Default Description Accepted Values
ids query array[string] false N/A The taxonomy IDs to filter by. If you specify this paramater, the API ignores the other parameters. The maximum number of IDs that can be specified is 100. -
name query string false N/A The name of the taxonomy. Filtering by a partial match is allowed. -
offset query integer(int32) false N/A Indicates the starting index of the paginated collection. -
limit query integer(int32) false 20 Indicates the number of results returned in a single page. The value set must be between 1 and 100. -
orderBy query string false name Sorts results by a given value in ascending or descending alphabetic order; to specify descending, prefix the value with a hyphen (-). name, -name, updatedAt, -updatedAt

Response Statuses

Status Meaning Description Schema
200 OK Collection of Taxonomy objects Taxonomies
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Update a Taxonomy

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.put('https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies/cc46c4c2deac11e7a3d646705f8c9e77', headers: headers, body: {"name":"CMS Taxonomy","description":"CMS Healthcare Provider Taxonomy Code Set"}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X PUT https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies/cc46c4c2deac11e7a3d646705f8c9e77 \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"name":"CMS Taxonomy","description":"CMS Healthcare Provider Taxonomy Code Set"}

PUT /taxonomies/{taxonomyId}

Updates a taxonomy.

Parameters

Parameter In Type Required Default Description Accepted Values
taxonomyId path string true N/A No description -
body body putTaxonomies true N/A No description -

Response Statuses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error
409 Conflict Conflict Error

Retrieve a Single Taxonomy

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies/cc46c4c2deac11e7a3d646705f8c9e77', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/specialty/v1/taxonomies/cc46c4c2deac11e7a3d646705f8c9e77 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "id": "cc46c4c2deac11e7a3d646705f8c9e77",
  "name": "CMS Taxonomy",
  "description": "CMS Healthcare Provider Taxonomy Code Set",
  "createdAt": "2018-04-21T16:14:53Z",
  "updatedAt": "2018-04-21T16:14:53Z"
}

GET /taxonomies/{taxonomyId}

Retrieves a single taxonomy by ID.

Parameters

Parameter In Type Required Default Description Accepted Values
taxonomyId path string true N/A No description -

Response Statuses

Status Meaning Description Schema
200 OK A Taxonomy object Taxonomy
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Specialties

A specialty is a specialized medical practice offered by a clinician or provider based on their training or clinical focus.

Create a Specialty

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.post('https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties', headers: headers, body: {"name":"Allergy & Immunology","description":"An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system","taxonomy":{"id":"cc46c4c2deac11e7a3d646705f8c9e77"},"status":"ACTIVE"}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X POST https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"name":"Allergy & Immunology","description":"An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system","taxonomy":{"id":"cc46c4c2deac11e7a3d646705f8c9e77"},"status":"ACTIVE"}

POST /specialties

Creates a specialty.

Parameters

Parameter In Type Required Default Description Accepted Values
body body postSpecialties true N/A No description -

Response Statuses

Status Meaning Description Schema
201 Created No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
409 Conflict Conflict Error

Response Headers

Status Header Type Format Description
201 Location string The URL of the created specialty.

Retrieve a List of Specialties

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "id": "92dfef3035df11e8bb469f2d0284914c",
      "name": "Allergy & Immunology",
      "description": "An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system.",
      "children": [
        {
          "id": "92dfef3135df11e8bb469f2d0284914c",
          "name": "Allergy"
        },
        {
          "id": "ff647c8e35e411e8bb469f2d0284914c",
          "name": "Clinical & Laboratory Immunology"
        }
      ],
      "taxonomy": {
        "id": "2d33c102f21e11e7a3d646705f8c9e77",
        "name": "NUCC Taxonomy"
      },
      "status": "ACTIVE",
      "updatedAt": "2018-04-21T16:14:53Z",
      "createdAt": "2018-04-21T16:14:53Z"
    },
    {
      "id": "ff647cb635e411e8bb469f2d0284914c",
      "name": "Clinical Pharmacology",
      "description": "Clinical pharmacology encompasses the spectrum of activities related to the discovery, development, regulation, and utilization of safe and effective drugs.",
      "taxonomy": {
        "id": "2d33c102f21e11e7a3d646705f8c9e77",
        "name": "NUCC Taxonomy"
      },
      "status": "ACTIVE",
      "updatedAt": "2018-04-21T16:14:53Z",
      "createdAt": "2018-04-21T16:14:53Z"
    },
    {
      "id": "ff647cb635e411e8bb469f2d0284914c",
      "name": "Medical Toxicology",
      "description": "Medical toxicologists are physicians who specialize in the prevention, evaluation, treatment, and monitoring of injury and illness from exposures to drugs and chemicals, as well as biological and radiological agents.",
      "parent": {
        "id": "ff647cc035e411e8bb469f2d0284914c",
        "name": "Toxicology"
      },
      "taxonomy": {
        "id": "92dfef1235df11e8bb469f2d0284914c",
        "name": "NUCC Taxonomy"
      },
      "status": "ACTIVE",
      "updatedAt": "2018-04-21T16:14:53Z",
      "createdAt": "2018-04-21T16:14:53Z"
    }
  ],
  "totalResults": 2,
  "firstLink": "http://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties?offset=0&limit=20",
  "lastLink": "http://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties?offset=0&limit=20"
}

GET /specialties

Retrieves a list of specialties.

Parameters

Parameter In Type Required Default Description Accepted Values
ids query array[string] false N/A Filters by specialty IDs. If you specify this parameter, the API ignores the other parameters. The maximum nuber of IDs that can be specified is 100. -
name query string false N/A The name or partial name of the specialty. -
parentId query string false N/A The ID of the parent of the specialty. -
status query string false N/A The status of the specialty. ACTIVE, INACTIVE
taxonomyId query string false N/A The ID of the taxonomy of the specialty. -
offset query integer(int32) false N/A Indicates the starting index of the paginated collection. -
limit query integer(int32) false 20 Indicates the number of results returned in a single page. The value set must be between 1 and 100. -
orderBy query string false name Sorts results by a given value in ascending or descending alphabetic order; to specify descending, prefix the value with a hyphen (-). name, -name, updatedAt, -updatedAt

Response Statuses

Status Meaning Description Schema
200 OK Collection of Specialty objects Specialties
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Update a specialty

Example Request:




require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.put('https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties/f9ed82acf21c11e7a3d646705f8c9e77', headers: headers, body: {"name":"Allergy & Immunology","description":"An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system","status":"ACTIVE"}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X PUT https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties/f9ed82acf21c11e7a3d646705f8c9e77 \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"name":"Allergy & Immunology","description":"An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system","status":"ACTIVE"}

PUT /specialties/{specialtyId}

Updates a specialty.

Parameters

Parameter In Type Required Default Description Accepted Values
specialtyId path string true N/A No description -
body body putSpecialties true N/A No description -

Response Statuses

Status Meaning Description Schema
204 No Content No Content None
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error
409 Conflict Conflict Error

Retrieve a Single Specialty

Example Request:


require 'httparty' # Using HTTParty 0.16.2
require 'json'

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

result = HTTParty.get('https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties/f9ed82acf21c11e7a3d646705f8c9e77', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/specialty/v1/specialties/f9ed82acf21c11e7a3d646705f8c9e77 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "id": "f9ed82acf21c11e7a3d646705f8c9e77",
  "name": "Allergy & Immunology",
  "description": "An allergist-immunologist is trained in the evaluation, physical and laboratory diagnosis, and management of disorders involving the immune system",
  "parent": {
    "id": "11e85d0cc3f0f83c9d27b1575fbb44c4",
    "name": "Asthma, Allergy & Immunology"
  },
  "children": [
    {
      "id": "92dfef3135df11e8bb469f2d0284914c",
      "name": "Allergy"
    },
    {
      "id": "ff647c8e35e411e8bb469f2d0284914c",
      "name": "Clinical & Laboratory Immunology"
    }
  ],
  "taxonomy": {
    "id": "cc46c4c2deac11e7a3d646705f8c9e77",
    "name": "CMS Taxonomy"
  },
  "createdAt": "2018-04-21T16:14:53Z",
  "updatedAt": "2018-04-21T16:14:53Z"
}

GET /specialties/{specialtyId}

Retrieves a single specialty by ID.

Parameters

Parameter In Type Required Default Description Accepted Values
specialtyId path string true N/A No description -

Response Statuses

Status Meaning Description Schema
200 OK A Specialty object Specialty
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Schema Definitions

postTaxonomies

Name Type Required Description Accepted Values
name string true The name of the taxonomy. -
description string false The description of the taxonomy -

Error

Name Type Required Description Accepted Values
code integer(int32) true Http response status code representing the error. -
message string true Human readable description of the error. -
errorDetails [ErrorDetail] false 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 Codified value representing the specific error resulting in the current error status. -
message string false Human readable description of an error. -
locationType string false Location or type of the field that caused an error. query, header, path, formData, body
location string false Name of the field that caused an error. -

Taxonomies

Name Type Required Description Accepted Values
items [Taxonomy] true No description -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

Taxonomy

Name Type Required Description Accepted Values
id string true The unique ID of the taxonomy. -
name string true The formatted display text of the taxonomy. -
description string false The description of the taxonomy definition. -
createdAt string true The date and time when the taxonomy was created, in International Organization for Standardization (ISO) 8601 format (YYYY-MM-DDThh:mm:ssZ). -
updatedAt string true The date and time when the taxonomy was most recently updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). -

putTaxonomies

Name Type Required Description Accepted Values
name string true The name of the taxonomy. -
description string false The description of the taxonomy -

postSpecialties

Name Type Required Description Accepted Values
name string true The name of the specialty. -
description string false The description of the specialty. -
taxonomy object true The taxonomy of the specialty. -
» id string true The unique ID of the taxonomy. -
status string true The status of the specialty. ACTIVE, INACTIVE
parent object false The parent of the specialty in the context of the same taxonomy. Root level specialties have a null parent. -
» id string true The unique ID of the specialty. -

Specialties

Name Type Required Description Accepted Values
items [Specialty] true No description -
totalResults integer(int32) false The total number of results for the specified parameters. -
firstLink string true The first page of results. -
lastLink string false The last page of results. -
prevLink string false The previous page of results. -
nextLink string false The next page of results. -

Specialty

Name Type Required Description Accepted Values
id string true The unique ID of the specialty. -
name string true The name of the specialty. -
description string false The description of the specialty definition. -
parent SpecialtyIdName false No description -
children [SpecialtyIdName] false The list of subspecialties associated with this specialty. -
status string true The status of the specialty. ACTIVE, INACTIVE
taxonomy TaxonomyIdName true No description -
createdAt string true The date and time when the specialty was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). -
updatedAt string true The date and time when the specialty was most recently updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ). -

SpecialtyIdName

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

TaxonomyIdName

Name Type Required Description Accepted Values
id string false The unique ID of the taxonomy. -
name string false The formatted display text of the taxonomy. -

putSpecialties

Name Type Required Description Accepted Values
name string true The name of the specialty. -
description string false The description of the specialty. -
status string true The status of the specialty. ACTIVE, INACTIVE
parent object false The parent of the specialty. -
» id string true The unique ID of the specialty. -

SpecialtyId

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

TaxonomyId

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