Using the API

The Identity API is a REST-based interface, which means that applications make requests to the API by accessing specific URLs using HTTP.

Base URL

The base URL will depend on the specifics of your implementation. Please contact us if you do not know your base URL.

In the API documentation, URLs are given relative to your base url. For example:

POST /mpi/v1/person/{id}

would become:

https://youruniqueidentityurl.careevolution.com/mpi/v1/person/{id}

Required Headers

Every API call requires the following fields in the HTTP request header:

For authorization-related headers, see Authorization.

Data Formats

All data sent to and received from the Identity API will be in JSON format, so both the content-type and accept headers will be application/json.

Authorization

CareEvolution will provide you with two separate API Keys, a ‘main’ one for regular operations and a ‘metrics’ one for metrics.

REST Basics

This section gives a brief introduction to REST APIs in general, and discusses how that model applies to the Identity API.

HTTP Verbs

Every API call uses a specific HTTP verb, which tells the system what kind of action you want to take with the resource. Different verbs are supported for each resource; consult the API documentation for details. Operations will generally use the GET verb to request matches and the POST verb to add or update data.

Parameters

Many API calls use query parameters and/or request body data to send data to the server. For example, a POST to the mpi/v1/record/{source}/{identifier} API might contain the body data:

{
  "firstName": "John",
  "lastName": "Doe",
  //...
}

Error Handling

The response header for each request contains a status code indicating whether the request was successful. Common status codes you will encounter are: