Documents

Web Services Overview

Introduction

The ClearGage web services are implemented using a RESTful API. All calls are made using HTTPS to provide security and reliability.

Client Registration

You must register your application with ClearGage prior to using the web service APIs. Once you have registered, you will be given a username and password which will be used to authenticate your request.

Security

All web service calls are secured with high grade 256-bit encryption using HTTPS requests. The SSL certificate is currently issued by GeoTrust, Inc., so ensure your root certificate authority keystore is up to date, if necessary.

Authentication

Basic authentication is used to control access to the API. Your username and password will be provided to you when you register.

The Authorization header should be used to pass the authentication credentials.

Example
Authorization: Basic RUxXMVE5T1IxNFhHNzJGNDo1akg5REFQZnd0MmRnbUEvTk9IWk9WSnhuNVR4VlkvSw==

Identification

Each client that registers will be assigned a single username and password for accessing the API. However, within the client's software, there may be a number of different users. It would be impractical to keep a synchronized list of users between the API and the client's software. A custom header value is used to keep track of which users within the client's software are accessing the API.

The value of the header can be anything that uniquely identifies a user within the client's software. A suggested practice would be to include the user's ID value, followed by a ":" separator, and the user's full name.

The cg-userid header should be used to pass the user information from the client's software.

Example
cg-userid: 1204:John Doe

Masquerading

For users that have access to multiple clients and branches, you can set the context of the API call to a particular client or branch by passing the associated Client ID in the header. The Client ID is an 8 character alpha-numeric string that uniquely identifies each client or branch that you have access to.

The cg-clientid header should be used to pass the optional Client ID information.

Example
cg-clientid: JDE13972

Response Format

Most calls can return either JSON or XML. Unless specified otherwise, a call will return JSON by default. To specify a particular return type, use the standard Accept header, or append .json or .xml to the URL.

JSON Header Example
Accept: application/json

XML Header Example
Accept: application/xml

JSON URL Example
GET /api/pp/patients/12345.json

XML URL Example
GET /api/pp/patients/12345.xml

Response Codes

The ClearGage API uses conventional HTTP response codes to indicate success or failure of a request. Codes in the 200-299 range indicate success. Codes in the 400-499 range indicate an error that resulted due to information passed from the client. Codes in 500-599 range indicate an error with ClearGage API servers.

Dates and Times

Unless specified otherwise, dates and times are formatted in ISO 8601 format and expressed in UTC.

Example
2013-01-31T16:30:00Z

Server Environments

Demo

We provide a Demo environment where you can test your calls. All financial transactions are simulated and no emails are sent to any patients in the Demo environment.

The URL you use to make calls to the Demo environment should begin with:

https://demo.acceleratepayments.com/

Production

When you are ready to launch your product, we will provide you a new set of username, password, and token to use for connecting to the Production environment. All calls made in the Production environment are real and may result in actual financial transactions taking place, and emails to patients may be sent, where appropriate.

The URL you use to make calls to the Production environment should begin with:

https://www.acceleratepayments.com/

Changes and Versioning

When a change is made to the API that is not backwards compatible, the version number of the API will be incremented. Changes that are backwards compatible will not result in a change of the API version number.

Examples of changes that would be backwards compatible are:

  • Adding optional request parameters
  • Adding response parameters
  • Changing the order of response parameters

Examples of changes that would not be backwards compatible are:

  • Adding required request parameters
  • Changing or deleting response parameters