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.

Standard Treatment Workflow

The diagram below shows the standard Treatment workflow end to end, from the first API call through an evaluated checklist. Each box maps to one of the endpoints listed above. When you create a subject, xCures automatically dispatches an EHR query; allow roughly 30 minutes for results to populate before you poll query status.

Bring Your Own Data (BYOD) Workflow

BYOD projects upload patient records directly to xCures instead of querying health information networks. xCures ingests the documents, normalizes them, and converts them to FHIR R4 and Clinical Concepts so that you can run Checklists on your patient population. Those endpoints behave exactly as they do in the Treatment workflow above. Set options.initiateEhrQuery to false when you create the subject so no EHR query fires. Because BYOD projects do not query QHIN-connected networks, the Reciprocity requirement does not apply.

Retrieval Only Workflow

Retrieval Only projects query health information networks and return raw documents to your system. xCures does not extract, normalize, or run Clinical Concepts processing on retrieved records, that work happens in your own pipeline. Polling and signed document URLs behave the same as the Treatment workflow above. Retrieval Only customers are also required to contribute documentation back to the network.

Existing Patient / Requery Workflow

Use this flow when a patient already exists in xCures and needs a fresh query, for example a roster onboarded weeks ago, or a patient whose previous query errored or returned thin data. Locate the subject, inspect their existing queries, then dispatch a new one and poll it the same way as a new patient. Skipping a requery when a prior query completed within the last 30 days is a reasonable starting point; tune the window to your own workflow.

Bulk Patient Onboarding

To onboard many patients at once, batch subject creation in groups of up to 10 per request, then dispatch one query per successfully created subject. Each result in the batch response reports success or failure independently, so a few bad rows never block the rest of the group.

Reciprocity Workflow

As a QHIN network participant, Standard Treatment Workflow and Retrieval Only projects are obligated to share clinical documentation back to the health information network for any patient whose records they retrieved. BYOD projects never query the network, so this requirement does not apply to them. The diagram below shows the full publish sequence: list a template, create the document record, upload the file bytes to the signed S3 URL, then publish.

AI Agent Skills

AI coding agents that integrate with the xCures API can fetch step-by-step instructions instead of guessing from this reference. xCures publishes these as machine-readable guides called Agent Skills.

Each skill covers one workflow: the endpoints to call, in order, and the fields each request requires. An agent using them never attempts a call your credentials cannot make.

• Standard Treatment Workflow: register a new patient and retrieve their existing records from connected health information networks. SKILL.md
• Bring Your Own Data (BYOD) Ingestion: upload records you already hold so xCures normalizes them into FHIR and Clinical Concepts. SKILL.md
• Retrieval Only: retrieve raw documents from health information networks with no xCures processing. SKILL.md
• Existing Patient / Requery: check whether a registered patient needs a fresh query, and dispatch one if so. SKILL.md
• Bulk Patient Onboarding: register and query a large roster of patients at once, safely and with per-patient failure isolation. SKILL.md
• Reciprocity: publish a clinical document back to a health information network to satisfy a project's network participation obligation. SKILL.md

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