Introduction to the xCures® API

Important URLs

API Credential Management

1Create New API Keys

Once you have received your xCures patient registry portal login information from your Customer Success Manager, head over to the dropdown in the top-right of your screen where your initials are, click the down arrow, and select Administration.

From here, click the API Keys tab and then click + Add:

First, set a name for your set of credentials in the API Key Name field:

Next, select which Projects these API credentials will have access to:

Then, select the permissions assigned to this set of credentials. Once you've assigned the appropriate permissions, click Save:

You will now be presented with your client_id and client_secret:

2Deactivate API Credentials

If the need to deactivate active API credentials arises, you can easily deactivate by toggling the ACTIVE button:

You'll then be presented with a confirmation modal:

3Rotate API Credentials

Rotating API credentials is a standard security practice. It reduces the risk of unauthorized access by limiting how long any single key or token remains valid. Generating new credentials on a schedule and retiring old ones limits the impact of accidental exposure, leaked secrets, or compromised environments. Planned, well-documented rotation procedures keep the service continuous through every change.

To rotate existing API credentials, click the name of the credentials:

At the bottom of the page, you will now see the option to Rotate your key:

Once your credentials have been rotated, you will be presented with the new credentials:

Authentication

The xCures API requires a Bearer Token in the Authorization header for authentication. Most xCures endpoints also require a ProjectId header to set the context of the request. The ProjectId must match a project the API client has permission to access.

Where to Find Your Project IDs

To find the ProjectId for each of your projects, click the Projects tab under the Administration menu on the left-hand sidebar. To copy the ProjectId, click the copy button.

The majority of the xCures API endpoints will require a ProjectId value to be submitted in the header of the request.

Obtaining a Bearer Token

To get a token, exchange your client_id and client_secret against the xCures OAuth endpoint using the client credentials grant.

Example cURL command

curl --request POST \
    --url https://partner.xcures.com/oauth/token \
    --header 'content-type: application/json' \
    --data '{
      "client_id": "{your_client_id}",
      "client_secret": "{your_client_secret}",
      "grant_type": "client_credentials"
    }'

Bearer token response

{
  "access_token": "{your_temporary_access_token}",
  "token_type": "Bearer"
}

Using the Bearer Token with the xCures API

Include the bearer token in the Authorization header of every request to the xCures API.

Example of an authorized request

curl --request GET \
    --url https://partner.xcures.com/api/v1/patient-registry/subject \
    --header 'ProjectId: {your_project_id}' \
    --header 'authorization: Bearer {your_temporary_access_token}'

Postman Collection

The xCures Postman collection lets you call the API directly without writing any code. Download it below, add your client_id, client_secret, and ProjectId to the collection's Variables tab, and run the included Get Bearer Token request — authentication is handled automatically for every call after that.

Available Endpoints

With authentication covered, the next section turns to the xCures API endpoints. The available endpoints and demo patient examples below support exploration of real-world data flows and safe testing of API behavior.

De-Identified Demo Patients for Testing

The xCures API ships with a small set of test patients for hands-on exploration. These are fully de-identified patients and cover a broad spectrum of use cases and conditions.

Best Practices for Patient Matching

Accurate and complete patient creation lays the groundwork for reliable data matching across the network. Using CSV uploads or API-based creation supports scalable and consistent record management while reducing duplication and errors.

Patient matching improves as you provide more demographic detail. Core identifiers such as full name, birth date, gender, and complete address information create the strongest matching signal. Prior addresses, alternate names, and external identifiers offer additional anchors that help unify records from past encounters or different health systems.

Required Demographic and Identifier Data

When creating a new Subject (patient) in the xCures system, use the Subject endpoint. Supplying as many of these fields as possible strengthens match confidence and improves the ability to locate a patient's longitudinal record across participating EHRs and national exchange networks.

API Error Handling

xCures uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided.

Next Steps