NAV Navbar
Logo cerner
Ruby Shell

Specialty API v1

The Specialty API enables systems to interact with and define the specialties and taxonomies of specialties that service providers can practice in a health care system. The Specialty API is especially useful for referral management, orders processing, and scheduling systems.

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

Taxonomies

Taxonomies are hierarchies of specialties and subspecialties that provide context for a curated list of specialties and can be associated with health care services and providers in HealtheIntent. Taxonomies are derived from the Centers for Medicare & Medicaid Services (CMS) Healthcare Provider Taxonomy Code Set. See the following examples:

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 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 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. See the following examples:

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","aliases":[{"system":"CMS","value":"03"},{"system":"NUCC","value":"207K00000X"}]}.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","aliases":[{"system":"CMS","value":"03"},{"system":"NUCC","value":"207K00000X"}]}

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": "Family Medicine",
      "description": "Family Medicine is the medical specialty that is concerned with the total health care of the individual and the family. It integrates the biological, clinical, and behavioral sciences and is not limited by age, sex, organ system, or disease.",
      "taxonomy": {
        "id": "2d33c102f21e11e7a3d646705f8c9e77",
        "name": "NUCC Taxonomy"
      },
      "status": "ACTIVE",
      "aliases": [
        {
          "system": "NUCC",
          "value": "207Q00000X"
        }
      ],
      "updatedAt": "2018-04-21T16:14:53Z",
      "createdAt": "2018-04-21T16:14:53Z"
    },
    {
      "id": "ff647cb635e411e8bb469f2d0284914c",
      "name": "Neurocritical Care",
      "description": "The subspecialty of Neurocritical Care is devoted to the comprehensive, multisystem care of critically-ill neurological patients. Like other intensivists, a neurointensivist generally assumes the primary role of coordinating the neurological and medical care of his or her patients in the ICU. He or she may also provide consultative services for these patients as requested in the health system.",
      "parent": {
        "id": "ff647cc035e411e8bb469f2d0284914c",
        "name": "Neurology"
      },
      "taxonomy": {
        "id": "92dfef1235df11e8bb469f2d0284914c",
        "name": "NUCC Taxonomy"
      },
      "status": "ACTIVE",
      "aliases": [
        {
          "system": "NUCC",
          "value": "2084A2900X"
        },
        {
          "system": "CMS",
          "value": "13"
        }
      ],
      "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. -
aliasSystem query string false N/A The authority responsible for assigning the specialty ID. If aliasSystem is specified, aliasValue is required. -
aliasValue query string false N/A The value or ID of the specialty in the context of the assigning authority. If aliasValue is specified, aliasSystem is required. -
offset query integer(int32) false 0 The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. -
limit query integer(int32) false 20 The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 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","aliases":[{"system":"CMS","value":"03"},{"system":"NUCC","value":"207K00000X"}]}.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","aliases":[{"system":"CMS","value":"03"},{"system":"NUCC","value":"207K00000X"}]}

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"
  },
  "aliases": [
    {
      "system": "CMS",
      "value": "03"
    },
    {
      "system": "NUCC",
      "value": "207K00000X"
    }
  ],
  "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 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. -

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
aliases [object] false The list of specialty aliases. -
» 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 provider in the context of the system or assigning authority. -
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 -
aliases [Alias] false The list of specialty aliases. -
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. -

Alias

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

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
aliases [object] false The list of specialty aliases. -
» 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 provider in the context of the system or assigning authority. -
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. -