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:{id}

Required Headers

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

Field Required Value Description
content-type application/json Defines the format of the data sent to the API.
accept application/json Defines the desired output format.

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.


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

Endpoints Header Value
/mpi x-api-key YOUR_MAIN_API_KEY
/monitoring Authorization Basic YOUR_METRICS_API_KEY or Basic BASE64_STRING with a base-64 encoded string consisting of bmpi:YOUR_METRICS_API_KEY.
/hash None The hashing service is normally protected with a secure, isolated network connection rather than an API key.

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.


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:

Code Description
200 Success The request was successful.
400 Bad Request There was a problem with your request parameters.
403 Forbidden Check your API key (see Required Headers).
429 Too Many Requests You have submitted too many requests in a short period of time. This can occur if you are attempting to add multiple records concurrently. For batch loading, we recommend no more than 60 concurrent requests. For details, see Maximizing Throughput.
500 Internal Server Error There was an unknown issue processing the request. Check the response body for details.