NAV Navbar
Logo cerner
Ruby Shell

Consumer API v1

HealtheIntent Service exposing operations to work with Consumers.

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

Consumer

A consumer represents a person as an active or potential target of health care or other services provided by a HealtheIntent tenant. If the person is also a user of HealtheIntent applications, the consumer is used to control access to data and functionality.

To uniquely identify a HealtheIntent consumer, you can configure one or more source identifiers for the consumer. Source IDs are defined as a combination of a unique local source ID and a data partition ID. These source IDs are usually back-end database IDs rather than user-facing IDs such as medical record numbers (MRNs) or financial numbers (FINs). For example, for data from Cerner Millennium, the local identifier would be the Cerner Millennium person ID (MPI) rather than an MRN. Cerner provides the data partition ID when the data source and partition are onboarded, and the ID remains constant for all look-up requests. Within a given tenant, no two consumers can have the same combination of a local source ID and a data partition ID.

You should add source IDs to consumers and use them as query parameters if the system interacting with the Consumer API is a data source for your HealtheIntent tenant. To uniquely identify a HealtheIntent consumer, you configure one or more source IDs for the consumer.

Create a Consumer

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/consumer/v1/consumers', headers: headers, body: {"patients":[{"id":"87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e","populationId":"aaa111bb-2222-cccc-3333-ddd444eee555"}],"birthDate":"1991-11-12","gender":"MALE","name":{"formatted":"Jason Brown Jr.","family":"Brown","given":"Jason","middle":"","prefix":"","suffix":"Jr."},"addresses":[{"use":"WORK","text":"8779 Hillcrest Rd, Bldg#1024","city":"Kansas City","state":"Missouri","lines":["8779 Hillcrest Rd","Bldg#1024"],"postalCode":"64138","country":"United States of America"}],"aliases":[{"value":"8cbbffdc-acfe-11e7-abc4-cec278b6b50c","system":"2.16.840.1.113883.4.6","type":"USER"}],"telecoms":[{"system":"EMAIL","value":"jasonbrown@cerner.com"},{"system":"PHONE","value":"8162211024"}],"sourceIdentifiers":[{"id":"1f9fd5bd-e83a-406f-9d39-3e0a33211f09","dataPartitionId":"f9716527-cf7b-4575-a232-a0fdfb4ae4f7"}]}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X POST https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"patients":[{"id":"87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e","populationId":"aaa111bb-2222-cccc-3333-ddd444eee555"}],"birthDate":"1991-11-12","gender":"MALE","name":{"formatted":"Jason Brown Jr.","family":"Brown","given":"Jason","middle":"","prefix":"","suffix":"Jr."},"addresses":[{"use":"WORK","text":"8779 Hillcrest Rd, Bldg#1024","city":"Kansas City","state":"Missouri","lines":["8779 Hillcrest Rd","Bldg#1024"],"postalCode":"64138","country":"United States of America"}],"aliases":[{"value":"8cbbffdc-acfe-11e7-abc4-cec278b6b50c","system":"2.16.840.1.113883.4.6","type":"USER"}],"telecoms":[{"system":"EMAIL","value":"jasonbrown@cerner.com"},{"system":"PHONE","value":"8162211024"}],"sourceIdentifiers":[{"id":"1f9fd5bd-e83a-406f-9d39-3e0a33211f09","dataPartitionId":"f9716527-cf7b-4575-a232-a0fdfb4ae4f7"}]}

Example response

{
  "id": "2151bf31-8655-4788-9756-9f1cfe3009f5",
  "name": {
    "formatted": "Jason Brown Jr.",
    "family": "Brown",
    "given": "Jason",
    "middle": "",
    "prefix": "",
    "suffix": "Jr."
  },
  "addresses": [
    {
      "use": "WORK",
      "text": "8779 Hillcrest Rd, Bldg#1024",
      "city": "Kansas City",
      "state": "Missouri",
      "lines": [
        "8779 Hillcrest Rd",
        "Bldg#1024"
      ],
      "postalCode": "64138",
      "country": "United States of America"
    }
  ],
  "aliases": [
    {
      "value": "8cbbffdc-acfe-11e7-abc4-cec278b6b50c",
      "system": "2.16.840.1.113883.4.6",
      "type": "USER"
    }
  ],
  "telecoms": [
    {
      "system": "EMAIL",
      "value": "jasonbrown@cerner.com"
    },
    {
      "system": "PHONE",
      "value": "8162211024"
    }
  ],
  "patients": [
    {
      "id": "87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e",
      "populationId": "aaa111bb-2222-cccc-3333-ddd444eee555"
    }
  ],
  "sourceIdentifiers": [
    {
      "id": "1f9fd5bd-e83a-406f-9d39-3e0a33211f09",
      "dataPartitionId": "f9716527-cf7b-4575-a232-a0fdfb4ae4f7"
    }
  ],
  "birthDate": "1991-11-12",
  "createdAt": "2018-02-21T16:30:55Z",
  "updatedAt": "2018-02-21T16:30:55Z"
}

POST /consumers

Creates a consumer.

Parameters

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

Response Statuses

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

Retrieve a List of Consumers

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/consumer/v1/consumers',
  query: {
  'aliasValue' => 'string'
}, headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers?aliasValue=type,string \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

Example response

{
  "items": [
    {
      "id": "2151bf31-8655-4788-9756-9f1cfe3009f5",
      "name": {
        "formatted": "Jason Brown Jr.",
        "family": "Brown",
        "given": "Jason",
        "middle": "",
        "prefix": "",
        "suffix": "Jr."
      },
      "addresses": [
        {
          "use": "WORK",
          "text": "8779 Hillcrest Rd, Bldg#1024",
          "city": "Kansas City",
          "state": "Missouri",
          "lines": [
            "8779 Hillcrest Rd",
            "Bldg#1024"
          ],
          "postalCode": "64138",
          "country": "United States of America"
        }
      ],
      "aliases": [
        {
          "value": "8cbbffdc-acfe-11e7-abc4-cec278b6b50c",
          "system": "2.16.840.1.113883.4.6",
          "type": "USER"
        }
      ],
      "telecoms": [
        {
          "system": "EMAIL",
          "value": "jasonbrown@cerner.com"
        },
        {
          "system": "PHONE",
          "value": "8162211024"
        }
      ],
      "patients": [
        {
          "id": "87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e",
          "populationId": "aaa111bb-2222-cccc-3333-ddd444eee555"
        }
      ],
      "sourceIdentifiers": [
        {
          "id": "1f9fd5bd-e83a-406f-9d39-3e0a33211f09",
          "dataPartitionId": "f9716527-cf7b-4575-a232-a0fdfb4ae4f7"
        }
      ],
      "birthDate": "1991-11-12",
      "gender": "MALE",
      "createdAt": "2018-02-21T16:30:55Z",
      "updatedAt": "2018-02-21T16:30:55Z"
    },
    {
      "id": "f7dc6dc2-ad00-48cf-a820-c1c0caedac8c",
      "name": {
        "formatted": "Jason Smith",
        "family": "Smith",
        "given": "Jason",
        "middle": "",
        "prefix": "",
        "suffix": ""
      },
      "addresses": [
        {
          "use": "WORK",
          "text": "2800 Rock Creek Pkwy, Suite#100",
          "city": "Kansas City",
          "state": "Missouri",
          "lines": [
            "2800 Rock Creek Pkwy",
            "Suite#100"
          ],
          "postalCode": "64117",
          "country": "United States of America"
        }
      ],
      "aliases": [
        {
          "value": "9bbaffdc-acfe-11e7-abc4-cec278b6b50c",
          "system": "3.16.840.1.113883.4.6",
          "type": "USER"
        }
      ],
      "telecoms": [
        {
          "system": "EMAIL",
          "value": "jasonsmith@cerner.com"
        },
        {
          "system": "PHONE",
          "value": "8162201024"
        }
      ],
      "patients": [
        {
          "id": "696601a8-efd1-485a-94ee-376f9438f217",
          "populationId": "aaa111bb-2222-cccc-3333-ddd444eee555"
        }
      ],
      "sourceIdentifiers": [
        {
          "id": "1f9fd5bd-e83a-406f-9d39-3e0a33211f09",
          "dataPartitionId": "f9716527-cf7b-4575-a232-a0fdfb4ae4f7"
        }
      ],
      "birthDate": "1990-01-12",
      "gender": "MALE",
      "createdAt": "2018-02-21T16:41:24Z",
      "updatedAt": "2018-02-21T16:46:12Z"
    }
  ],
  "totalResults": 2,
  "firstLink": "https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers?formattedName=jason&orderBy=givenName&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers?formattedName=jason&orderBy=givenName&offset=0&limit=20"
}

GET /consumers

Returns a list of consumers.

Parameters

Parameter In Type Required Default Description Accepted Values
formattedName query string false N/A The formatted name of the consumer. Filtering by a partial match is allowed. -
aliasType query string false N/A The type of alias to search. Requires aliasValue. EXTERNAL, MRN, USER
aliasValue query string true N/A The unique identifier of alias to search. Requires aliasType or aliasSystem. -
aliasSystem query string false N/A The source of the alias value. This is needed because an alias value that is unique within a given assigning authority is not guaranteed to be unique across sources. Requires aliasValue. -
patientId query string false N/A The patient ID to filter by. -
sourceId query string false N/A The source ID to filter by. -
dataPartitionId query string false N/A The data partition ID to filter by. -
offset query integer(int32) false N/A 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 formattedName A comma-separated list of fields by which to sort. formattedName, -formattedName, familyName, -familyName, givenName, -givenName

Response Statuses

Status Meaning Description Schema
201 Created Collection of Consumer objects ConsumerEntities
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error

Remove a Consumer

Example Request:


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

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

result = HTTParty.delete('https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers/21fa3619-9569-4ba1-b8fe-95e5f4fc4212', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X DELETE https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers/21fa3619-9569-4ba1-b8fe-95e5f4fc4212 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

DELETE /consumers/{consumerId}

Removes a consumer.

Parameters

Parameter In Type Required Default Description Accepted Values
consumerId path string true N/A The ID of the consumer. -

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

Update a Consumer

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/consumer/v1/consumers/2151bf31-8655-4788-9756-9f1cfe3009f5', headers: headers, body: {"patients":[{"id":"87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e","populationId":"aaa111bb-2222-cccc-3333-ddd444eee555"}],"birthDate":"1991-11-12","gender":"MALE","name":{"formatted":"Jason Brown Jr.","family":"Brown","given":"Jason","middle":"","prefix":"","suffix":"Jr."},"addresses":[{"use":"WORK","text":"8779 Hillcrest Rd, Bldg#1024","city":"Kansas City","state":"Missouri","lines":["8779 Hillcrest Rd","Bldg#1024"],"postalCode":"64138","country":"United States of America"}],"aliases":[{"value":"8cbbffdc-acfe-11e7-abc4-cec278b6b50c","system":"2.16.840.1.113883.4.6","type":"USER"}],"telecoms":[{"system":"EMAIL","value":"jasonbrown@cerner.com"},{"system":"PHONE","value":"8162211024"}],"sourceIdentifiers":[{"id":"1f9fd5bd-e83a-406f-9d39-3e0a33211f09","dataPartitionId":"f9716527-cf7b-4575-a232-a0fdfb4ae4f7"}]}.to_json )

print JSON.pretty_generate(result)




# You can also use wget
curl -X PUT https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers/2151bf31-8655-4788-9756-9f1cfe3009f5 \
-H 'Authorization: {auth_header}' \
-H 'Content-Type: application/json' \ \
-H 'Accept: application/json' \
-d {"patients":[{"id":"87a61ec1-ccd8-46e1-a720-1a8d34bf2a7e","populationId":"aaa111bb-2222-cccc-3333-ddd444eee555"}],"birthDate":"1991-11-12","gender":"MALE","name":{"formatted":"Jason Brown Jr.","family":"Brown","given":"Jason","middle":"","prefix":"","suffix":"Jr."},"addresses":[{"use":"WORK","text":"8779 Hillcrest Rd, Bldg#1024","city":"Kansas City","state":"Missouri","lines":["8779 Hillcrest Rd","Bldg#1024"],"postalCode":"64138","country":"United States of America"}],"aliases":[{"value":"8cbbffdc-acfe-11e7-abc4-cec278b6b50c","system":"2.16.840.1.113883.4.6","type":"USER"}],"telecoms":[{"system":"EMAIL","value":"jasonbrown@cerner.com"},{"system":"PHONE","value":"8162211024"}],"sourceIdentifiers":[{"id":"1f9fd5bd-e83a-406f-9d39-3e0a33211f09","dataPartitionId":"f9716527-cf7b-4575-a232-a0fdfb4ae4f7"}]}

PUT /consumers/{consumerId}

Updates a consumer.

Parameters

Parameter In Type Required Default Description Accepted Values
consumerId path string true N/A The ID of the consumer. -
body body putConsumers 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 Consumer

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/consumer/v1/consumers/2151bf31-8655-4788-9756-9f1cfe3009f5', headers: headers)

print JSON.pretty_generate(result)


# You can also use wget
curl -X GET https://cernerdemo.api.us.healtheintent.com/consumer/v1/consumers/2151bf31-8655-4788-9756-9f1cfe3009f5 \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'

GET /consumers/{consumerId}

Returns a single consumer.

Parameters

Parameter In Type Required Default Description Accepted Values
consumerId path string true N/A The ID of the consumer. -

Response Statuses

Status Meaning Description Schema
200 OK Retrieve a Single Consumer ConsumerEntity
400 Bad Request Bad Request Error
401 Unauthorized Unauthorized Error
403 Forbidden Forbidden Error
404 Not Found Not Found Error

Schema Definitions

postConsumers

Name Type Required Description Accepted Values
patients [object] false The patient records of the consumer. -
» id string true The identifier for the consumer’s patient record within a HealtheIntent population. -
» populationId string true The identifier for the HealtheIntent population to which the patient identifier belongs. -
birthDate string(date-time) false The date of birth in YYYY-MM-DD format of the consumer. -
gender string false The gender of the consumer. MALE, FEMALE, OTHER, UNKNOWN
name object true The name components of the consumer. -
» given string true The given name, usually the first name. -
» family string true The family name, usually the last name. -
» prefix string false The prefix portion of the provider’s name; such as Mr., Mrs., Dr., etc. -
» suffix string false The suffix portion of the person’s name; such as Jr., Sr., MD., RN., etc. -
» middle string false The person’s middle name. -
» formatted string false The fully formatted name. This is created from the discrete components (prefix, given, middle, family, and suffix). -
addresses [object] false The addresses of the consumer. -
» postalCode string false Postal code of the address, example: 64137 -
» country string false Country of the address, example USA -
» use string false The type of the address. -
» text string false The formatted display text of the address. -
» city string false The city of the address. -
» state string false The state of the address. -
» lines string false The street component of the address. -
aliases [object] false The aliases of the consumer. -
» type string true The type of the alias. -
» value string true The unique identifier used to identify the person. -
» system string true The source of the alias value. This is needed because an alias value that is unique within a given assigning authority (such as Medical Record Number (MRN) or Cerner Millennium) is not guaranteed to be unique across sources; for example, a MRN of 12345 from Cerner Millennium can represent one person while the MRN of 12345 from Allscripts represents another person. This overlap presents security and data integrity concern such as data being linked to the wrong organization or provider. -
telecoms [object] false The contact details of the consumer. -
» system string true The type of telecom system being used. -
» value string true The value of the telecom. -
sourceIdentifiers [object] false IDs linking the consumer to an external source. -
» id string true An ID that uniquely identifies the consumer in a data partition. -
» dataPartitionId string true The data partition ID should match the HealtheIntent partition ID for the data source. -

ConsumerEntity

Name Type Required Description Accepted Values
id string true The ID of the consumer. -
name Name true The name components of the consumer. -
addresses [Address] false The addresses of the consumer. -
aliases [Alias] false The aliases of the consumer. -
telecoms [Telecom] false The contact details of the consumer. -
patients [Patient] false The patient records of the consumer. -
sourceIdentifiers [SourceIdentifier] false IDs linking the consumer to an external source. -
birthDate string false The date of birth in YYYY-MM-DD format of the consumer. -
gender string false No description MALE, FEMALE, OTHER, UNKNOWN
createdAt string(date-time) true The date and time in YYYY-MM-DDThh:mm:ssZ format when this consumer was created. -
updatedAt string(date-time) true The date and time in YYYY-MM-DDThh:mm:ssZ format of the most recent update to this consumer. -

Name

Name Type Required Description Accepted Values
prefix string false The prefix portion of the provider’s name; such as Mr., Mrs., Dr., etc. -
given string true The given name, usually the first name. -
middle string false The person’s middle name. -
family string true The family name, usually the last name. -
suffix string false The suffix portion of the person’s name; such as Jr., Sr., MD., RN., etc. -
formatted string true The fully formatted name. This is created from the discrete components (prefix, given, middle, family, and suffix). -

Address

Name Type Required Description Accepted Values
postalCode string false Postal code of the address, example: 64137 -
country string false Country of the address, example USA -
use string false The type of the address. HOME, WORK
text string false The formatted display text of the address. -
city string false The city of the address. -
state string false The state of the address. -
lines [string] false The street component of the address. -

Alias

Name Type Required Description Accepted Values
type string true The type of the alias. EXTERNAL, MRN, USER
value string true The unique identifier used to identify the person. -
system string true The source of the alias value. This is needed because an alias value that is unique within a given assigning authority (such as Medical Record Number (MRN) or Cerner Millennium) is not guaranteed to be unique across sources; for example, a MRN of 12345 from Cerner Millennium can represent one person while the MRN of 12345 from Allscripts represents another person. This overlap presents security and data integrity concern such as data being linked to the wrong organization or provider. -

Telecom

Name Type Required Description Accepted Values
system string true The type of telecom system being used. PHONE, EMAIL, OTHER
value string true The value of the telecom. -

Patient

Name Type Required Description Accepted Values
id string true The identifier for the consumer’s patient record within a HealtheIntent population. -
populationId string true The identifier for the HealtheIntent population to which the patient identifier belongs. -

SourceIdentifier

Name Type Required Description Accepted Values
id string true An ID that uniquely identifies the consumer in a data partition. -
dataPartitionId string true The data partition ID should match the HealtheIntent partition ID for the data source. -

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. -

ConsumerEntities

Name Type Required Description Accepted Values
items [ConsumerEntity] true No description -
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. -
totalResults integer(int32) true The total number of results for the specified parameters. -

putConsumers

Name Type Required Description Accepted Values
patients [Patient] false The patient records of the consumer. -
birthDate string(date-time) false The date of birth in YYYY-MM-DD format of the consumer. -
gender string false The gender of the consumer. MALE, FEMALE, OTHER, UNKNOWN
name Name true The name components of the consumer. -
addresses [Address] false The addresses of the consumer. -
aliases [Alias] false The aliases of the consumer. -
telecoms [Telecom] false The contact details of the consumer. -
sourceIdentifiers [SourceIdentifier] false IDs linking the consumer to an external source. -