Overview

All Patient Data APIs are protected using OAuth authentication. This method requires a first call to the API with user credentials, with subsequent requests using the token provided in response to the first call. All requests to the API use POST. The OAuth authentication endpoint expects a form-url-encoded body while all other endpoints expect raw JSON. The test environment will host these APIs at the following URL: https://service.gehrimed.com/PatientService. Each Endpoint listed below is a relative URL to the root URL.

OAuth Token and x-scope Header

This service is meant to be accessed by API Consumer's on behalf of integrated GEHRIMED groups. To facilitate this, the service will offer the ability to subscribe to a webhook for a particular Group's notifications, or a x-scope, at which point the consumer can authenticate via OAuth, and use the x-scope for a particular group's data requests.

Invalid x-scope Response

Using an invalid x-scope header will return a HttpStatusCode of 401 Unauthorized.

Data Types

Fields designated as date are expressed in the format "yyyy-MM-dd". Fields designated as datetime are adjusted to universal time and sent in the format "yyyy-MM-ddTHH:mm:ss.fffZ" (eg: "2018-09-12T16:44:25.850Z"). This follows the ISO 8601 standard.

Response Formats

All responses will be JSON. Successful requests will contain metadata related to the API call. The metadata will include the identity of the sender, the consumer, and the time the message was generated. Unsuccessful requests will contain error data but no metadata; see the Errors section below for more details.

{
    "Metadata": {
        "ApiSender": "GEHRIMED",
        "ApiConsumer": "client_id",
        "MessageDateTime": "2018-01-30T19:20:30.45.000Z"
    },
    "Data": {
        ...
    }
}

Field	Data Type	Comments
Metadata.ApiSender	String	Name of sender - "GEHRIMED".
Metadata.ApiConsumer	String	Client_id for current request.
Metadata.MessageDateTime	Datetime	UTC datetime that message was generated.
Data	Data	Content inside data will vary based on request type.

Errors

Any input validation errors result in a 400 HTTP status code with a Errors field in a JSON-encoded response. The Errors can be presented to end users.

Any server-side errors result in a 500 HTTP status code with a Errors field in a JSON-encoded response describing the error. This type of error should not be presented to end users; the error likely contains technical detail useful only for root-cause analysis.

{
    "Errors": {
        "First": [
            "The First field is required."
        ],
        "Last": [
            "The Last field is required."
        ],
        "DOB": [
            "The DOB field is required."
        ],
        "SSN": [
            "The SSN field is required."
        ]
    }
}

The Errors object will contain one to many keys, and each key will contain an array of errors. Each key corresponds to a specific field from the request that was not valid; a general key may be present if there are validation errors not specific to a single field.

Groups Access

Groups Access Status

Groups Access refers to the Api Access provided by a company / group for an Api Consumer. The Groups Access status can be as follows:

1 = Active
2 = Revoked

Subscriptions and Events

Subscription and Event Types

Subscriptions and Events have the same value for what "type" they are, which is as follows:

1 = Patient
2 = Billing
3 = Customer
4 = Document

Subscription Status

Subscription status definitions are as follows:

0 = Unsubscribed
1 = Subscribed

Versioning

The API version consists of four 16-bit integer parts: major, minor, build, and revision, in the format: major.minor.build.revision. The major.minor part of the version corresponds to the version of this document. The build and revision components are for informational/diagnostic purposes only and are not to be used for version checks. These two numbers are updated before each candidate build of the API is made available.

The API is designed to be backward-compatible whenever possible. Breaking changes will be explicitly called out in this document.

X-Version Header

Every response from the API service will include a header named X-Version with the value equal to the formatted version of the API.

Calls

OAuth

Subscription

Overview ​

OAuth Token and x-scope Header ​

Invalid x-scope Response ​

Data Types ​

Response Formats ​

Errors ​

Groups Access ​

Groups Access Status ​

Subscriptions and Events ​

Subscription and Event Types ​

Subscription Status ​

Versioning ​

X-Version Header ​

Calls ​

OAuth ​

Billing ​

Customer ​

Document ​

Encounter ​

Group ​

HIE ​

MessageProcessing ​

Patient ​

Subscription ​

Overview

OAuth Token and x-scope Header

Invalid x-scope Response

Data Types

Response Formats

Errors

Groups Access

Groups Access Status

Subscriptions and Events

Subscription and Event Types

Subscription Status

Versioning

X-Version Header

Calls

OAuth

Billing

Customer

Document

Encounter

Group

HIE

MessageProcessing

Patient

Subscription