# xCures API

# Authentication
Our API requires a Bearer Token in the `Authorization` header for auth. Most of our endpoints also require a `ProjectId` header to set the context of the request. It must be one of the projects the api client has permissions to.

### Getting a token
To get a token, use your `client_id` and `client_secret` to execute a client credentials exchange.

#### 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"}'
        
#### Response:

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

### Using the token with our API:
Now just include that bearer token in the `Authorization` header of your requests to our API.

#### Example 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}'

Version: V1

## Servers

```
https://partner.xcures.com
```

## Security

### bearer

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[xCures API](https://docs.xcures.com/_bundle/apis/current.yaml)

## OAuth

All API requests to xCures must provide an access token, retrieved via the standard OAuth authorization flow below.

### Get Token

 - [POST /oauth/token](https://docs.xcures.com/apis/current/oauth/publicoauthcontroller_token.md): Obtain an access token that is authorized to make API calls.

## Subject

An individual patient created on the xCures Platform.

### Search Subjects

 - [GET /api/v1/patient-registry/subject](https://docs.xcures.com/apis/current/subject/publicsubjectcontroller_search.md): Search subjects

### Create Subjects

 - [POST /api/v1/patient-registry/subject](https://docs.xcures.com/apis/current/subject/publicsubjectcontroller_create.md): Creates all the subjects defined in the array. Maximum of 10 subjects allowed.

### Get Subject

 - [GET /api/v1/patient-registry/subject/{id}](https://docs.xcures.com/apis/current/subject/publicsubjectcontroller_get.md): Get a specific subject by ID.

### Update Subject

 - [PUT /api/v1/patient-registry/subject/{id}](https://docs.xcures.com/apis/current/subject/publicsubjectcontroller_update.md): Update a subject.

### Get Clinical Concepts Status

 - [GET /api/v1/patient-registry/subject/{id}/status/clinical-concepts](https://docs.xcures.com/apis/current/subject/publicsubjectcontroller_getclinicalconceptsstatus.md): Get information regarding the availability of clinical concepts for a subject.

### Create Subject V2

 - [POST /api/v2/patient-registry/subject](https://docs.xcures.com/apis/current/subject/publicsubjectcontrollerv2_create.md): Creates and returns the subject.

## Query

A specified, approved request for patient records across the network (e.g., via Carequality/TEFCA to support treatment activities, via TEFCA for IAS queries) with an associated status (e.g., “completed”).

### Search Queries

 - [GET /api/v1/patient-registry/query](https://docs.xcures.com/apis/current/query/publicquerycontroller_search.md): Search Queries

### Create Query

 - [POST /api/v1/patient-registry/query](https://docs.xcures.com/apis/current/query/publicquerycontroller_create.md): Create a new query by providing the necessary details. The query will be stored and can be used for further operations.

### Get Query

 - [GET /api/v1/patient-registry/query/{id}](https://docs.xcures.com/apis/current/query/publicquerycontroller_get.md): Get a specific query by ID.

## Document

Patient records retrieved by the xCures platform and/or loaded by platform users.

### Create a Document

 - [POST /api/v1/patient-registry/document](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_create.md): Create a new document for a subject and get a signed URL to upload the document.

### Search Documents

 - [GET /api/v1/patient-registry/document](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_getall.md): Get a paginated list of documents for a subject.

### Get Document

 - [GET /api/v1/patient-registry/document/{documentId}](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_getbyid.md): Get a specific document by id.

### Update Document

 - [PUT /api/v1/patient-registry/document/{documentId}](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_update.md): Update a document.

### Publish Document

 - [PUT /api/v1/patient-registry/document/{documentId}/reciprocity](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_reciprocity.md): Publish a document for reciprocity to the EHR network. Can be used to update the template used for reciprocity as well. Note that the project's Reciprocity must be enabled and Requester Information and Encounter Information need to be properly set up in the Administration UI.

### Unpublish Document

 - [DELETE /api/v1/patient-registry/document/{documentId}/reciprocity](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_unpublish.md): Unpublish a document from reciprocity in the EHR network.

### Get Document PDF URL

 - [GET /api/v1/patient-registry/document/{documentId}/pdf](https://docs.xcures.com/apis/current/document/publicdocumentcontroller_getpdfbyid.md): Get a signed URL to download the PDF version of a document.

## FHIR

**F**ast **H**ealthcare **I**nteroperability **R**esource is an international data model specification developed by HL7 International to enable healthcare data exchange and interoperability between different systems.

### Allergy Intolerances

 - [GET /api/v1/patient-registry/fhir/allergyintolerance](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_allergyintolerance.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Basics

 - [GET /api/v1/patient-registry/fhir/basic](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_basic.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Care Plans

 - [GET /api/v1/patient-registry/fhir/careplan](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_careplan.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Coverages

 - [GET /api/v1/patient-registry/fhir/coverage](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_coverage.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Conditions

 - [GET /api/v1/patient-registry/fhir/condition](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_condition.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Diagnostic Reports

 - [GET /api/v1/patient-registry/fhir/diagnosticreport](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_diagnosticreport.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Encounters

 - [GET /api/v1/patient-registry/fhir/encounter](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_encounter.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Medication Statements

 - [GET /api/v1/patient-registry/fhir/medicationstatement](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_medicationstatement.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Patients

 - [GET /api/v1/patient-registry/fhir/patient](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_patient.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Procedures

 - [GET /api/v1/patient-registry/fhir/procedure](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_procedure.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Observations

 - [GET /api/v1/patient-registry/fhir/observation](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_observation.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Specimens

 - [GET /api/v1/patient-registry/fhir/specimen](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_specimen.md): Search the specific FHIR resources by subjectId. For the latest documentation of the response, please see the Resource Bundle definition in the FHIR spec.

### Export FHIR Resources

 - [GET /api/v1/patient-registry/fhir/_export](https://docs.xcures.com/apis/current/fhir/publicfhircontroller_export.md): Export a FHIR Bundle containing all of the subject's resources. The resulting FHIR Bundle will be in JSON Lines format.

## Clinical Concepts

Clinical concepts is a proprietary xCures higher-level, flattened, filtered, opinionated view of medical record information, structured around FHIR guidelines.

### Search Clinical Concepts Conditions

 - [GET /api/v1/patient-registry/clinical-concepts/condition](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchconditions.md): Search for condition clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Condition

 - [GET /api/v1/patient-registry/clinical-concepts/condition/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getcondition.md): Retrieve a specific condition clinical concept associated with a subject by its ID.

### Search Clinical Concepts Medications

 - [GET /api/v1/patient-registry/clinical-concepts/medication](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchmedications.md): Search for medication clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Medication

 - [GET /api/v1/patient-registry/clinical-concepts/medication/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getmedication.md): Retrieve a specific medication clinical concept associated with a subject by its ID.

### Search Clinical Concepts Allergies

 - [GET /api/v1/patient-registry/clinical-concepts/allergy](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchallergies.md): Search for allergy clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Allergy

 - [GET /api/v1/patient-registry/clinical-concepts/allergy/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getallergy.md): Retrieve a specific allergy clinical concept associated with a subject by its ID.

### Search Clinical Concepts Procedures

 - [GET /api/v1/patient-registry/clinical-concepts/procedure](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchprocedures.md): Search for procedure clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Procedure

 - [GET /api/v1/patient-registry/clinical-concepts/procedure/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getprocedure.md): Retrieve a specific procedure clinical concept associated with a subject by its ID.

### Search Clinical Concepts Biomarkers

 - [GET /api/v1/patient-registry/clinical-concepts/biomarker](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchbiomarkers.md): Search for biomarker clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Biomarker

 - [GET /api/v1/patient-registry/clinical-concepts/biomarker/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getbiomarker.md): Retrieve a specific biomarker clinical concept associated with a subject by its ID.

### Search Clinical Concepts Coverage

 - [GET /api/v1/patient-registry/clinical-concepts/coverage](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchcoverage.md): Search for coverage clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Coverage

 - [GET /api/v1/patient-registry/clinical-concepts/coverage/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getcoverage.md): Retrieve a specific coverage clinical concept associated with a subject by its ID.

### Search Clinical Concepts Demographics

 - [GET /api/v1/patient-registry/clinical-concepts/demographic](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchdemographics.md): Search for demographic clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Demographic

 - [GET /api/v1/patient-registry/clinical-concepts/demographic/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getdemographic.md): Retrieve a specific demographic clinical concept associated with a subject by its ID.

### Search Clinical Concepts Encounters

 - [GET /api/v1/patient-registry/clinical-concepts/encounter](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchencounters.md): Search for encounter clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Encounter

 - [GET /api/v1/patient-registry/clinical-concepts/encounter/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getencounter.md): Retrieve a specific encounter clinical concept associated with a subject by its ID.

### Search Clinical Concepts Family History

 - [GET /api/v1/patient-registry/clinical-concepts/family_history](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchfamilyhistory.md): Search for family history clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Family History

 - [GET /api/v1/patient-registry/clinical-concepts/family_history/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getfamilyhistory.md): Retrieve a specific family history clinical concept associated with a subject by its ID.

### Search Clinical Concepts Imaging

 - [GET /api/v1/patient-registry/clinical-concepts/imaging](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchimaging.md): Search for imaging clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Imaging

 - [GET /api/v1/patient-registry/clinical-concepts/imaging/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getimaging.md): Retrieve a specific imaging clinical concept associated with a subject by its ID.

### Search Clinical Concepts Labs

 - [GET /api/v1/patient-registry/clinical-concepts/lab](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchlabs.md): Search for lab clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Lab

 - [GET /api/v1/patient-registry/clinical-concepts/lab/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getlab.md): Retrieve a specific lab clinical concept associated with a subject by its ID.

### Search Clinical Concepts Social History

 - [GET /api/v1/patient-registry/clinical-concepts/social_history](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchsocialhistory.md): Search for social history clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Social History

 - [GET /api/v1/patient-registry/clinical-concepts/social_history/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getsocialhistory.md): Retrieve a specific social history clinical concept associated with a subject by its ID.

### Search Clinical Concepts Surveys

 - [GET /api/v1/patient-registry/clinical-concepts/survey](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchsurveys.md): Search for survey clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Survey

 - [GET /api/v1/patient-registry/clinical-concepts/survey/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getsurvey.md): Retrieve a specific survey clinical concept associated with a subject by its ID.

### Search Clinical Concepts Radiation

 - [GET /api/v1/patient-registry/clinical-concepts/radiation](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchradiation.md): Search for radiation clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Radiation

 - [GET /api/v1/patient-registry/clinical-concepts/radiation/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getradiation.md): Retrieve a specific radiation clinical concept associated with a subject by its ID.

### Search Clinical Concepts Vitals

 - [GET /api/v1/patient-registry/clinical-concepts/vital](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_searchvitals.md): Search for vital clinical concepts associated with a specific subject. Supports filtering by search term, date range, code, and code system. Results are paginated.

### Get Clinical Concept Vital

 - [GET /api/v1/patient-registry/clinical-concepts/vital/{id}](https://docs.xcures.com/apis/current/clinical-concepts/publicclinicalconceptscontroller_getvital.md): Retrieve a specific vital clinical concept associated with a subject by its ID.

## Checklist

AI-powered feature leveraging xCures’ targeted data extraction/processing to populate validated, customizable question/answer-style items. Responses can be highly flexible and every item returns a justification, supporting documents, and structured data to guide decisions in real time.

### Get Checklists

 - [GET /api/v1/patient-registry/checklist](https://docs.xcures.com/apis/current/checklist/publicchecklistcontroller_list.md): Get the set of checklists configured for the project.

### Evaluate Checklist

 - [POST /api/v1/patient-registry/checklist/{checklistId}/evaluate](https://docs.xcures.com/apis/current/checklist/publicchecklistcontroller_evaluate.md): Evaluate a checklist for a subject.

### Submit Checklist Item Feedback

 - [POST /api/v1/patient-registry/checklist/{checklistId}/item/{checklistItemId}/feedback](https://docs.xcures.com/apis/current/checklist/publicchecklistcontroller_submititemfeedback.md): Submit feedback on a specific checklist item for a subject.

## Summary

The AI-generated summary of a patient’s overall records and condition(s).

### Subject Summary

 - [GET /api/v1/patient-registry/summary/subject/{subjectId}](https://docs.xcures.com/apis/current/summary/publicsummarycontroller_subjectsummary.md): Fetches the summary for a given subject. Throws a Forbidden error if the summary feature is disabled for the project.

## Application

Account creation (e.g., identity proofing, eConsent) that is required for a patient to progress on the xCures Platform.

### Get Application

 - [GET /api/v1/patient-registry/application/{id}](https://docs.xcures.com/apis/current/application/publicapplicationcontroller_get.md): Get a specific application by ID.

### Create Application

 - [POST /api/v1/patient-registry/application](https://docs.xcures.com/apis/current/application/publicapplicationcontroller_create.md): Create a new application. The application will be created in the system and an email will be sent to the applicant requesting consent.

### Resend Application Invite

 - [POST /api/v1/patient-registry/application/{id}/resend-verification](https://docs.xcures.com/apis/current/application/publicapplicationcontroller_resendverification.md): Resends an email to the applicant requesting consent. Also updates the webhooks for the application.

## Reciprocity Template

Reciprocity or "Responder" workflows refer to the process of sharing clinical documentation housed within your system with other organizations/providers, when participating in health data exchange networks (e.g., Carequality, TEFCA).

### List Reciprocity Templates

 - [GET /api/v1/patient-registry/reciprocity-template](https://docs.xcures.com/apis/current/reciprocity-template/publicreciprocitytemplatecontroller_list.md): Get a list of all reciprocity document templates available under this project.