Introduction to the xCures® API

Important URLs

API Credential Management

1Create New API Keys

Once you receive your xCures patient registry portal credentials from your Customer Success Manager, open the dropdown in the top-right of your screen 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 for this set of credentials. Once assigned, 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

Call the List Projects endpoint to retrieve every project your credentials can access. No ProjectId header is required for this call.

Example request

curl --request GET \
    --url https://partner.xcures.com/api/v1/patient-registry/project \
    --header 'authorization: Bearer {your_access_token}'

Example response

[
  {
    "id": "e6b01018-a333-4732-917e-fe38e91b0fdf",
    "name": "My Project",
    "created": "2025-05-26T23:30:40.912Z",
    "updated": "2025-05-26T23:30:40.912Z"
  }
]

Copy the id value for the project you want to work with. The majority of xCures API endpoints require a ProjectId header in every 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_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_access_token}'

Postman Collection

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

Available Endpoints

Authentication done, here are the xCures API endpoints. The endpoint table and demo patients below cover the common workflows and let you test API behavior safely.

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 a problem with the request. Codes in the 5xx range indicate a problem on the xCures side.

Next Steps