xCures · Example Payload
Xcures Workflow Playbook.Postman_Collection
HealthHealthcareMedical RecordsInteroperabilityFHIROncologyReal World DataClinical DataArtificial IntelligenceTEFCACarequalityPatient DataHITRUSTHIPAA
Xcures Workflow Playbook.Postman_Collection is an example object payload from xCures, with 3 top-level fields. It illustrates the shape of data this provider's APIs accept or return.
Top-level fields
infovariableitem
Example Payload
{
"info": {
"name": "xCures SDK — Workflow Playbook",
"_postman_id": "xcures-sdk-workflows-v1",
"description": "Workflow-first Postman collection mirroring every example in the xCures SDK docs.\n\nSetup (do this once):\n1. Click the collection → Variables tab\n2. Fill in client_id, client_secret, project_id\n3. Run '0.1 Get Bearer Token' — it auto-saves the token to {{bearer_token}}\n4. Run folders top-to-bottom — each step saves IDs that the next step needs\n\nNote: Real query polling takes 20–30 minutes in production. In Postman, use the 'Poll Query Status' request manually until ccdaStatus = 'completed' or 'exhausted'.",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"variable": [
{
"key": "base_url",
"value": "https://partner.xcures.com"
},
{
"key": "client_id",
"value": "PASTE_YOUR_CLIENT_ID_HERE"
},
{
"key": "client_secret",
"value": "PASTE_YOUR_CLIENT_SECRET_HERE"
},
{
"key": "project_id",
"value": "PASTE_YOUR_PROJECT_ID_HERE"
},
{
"key": "bearer_token",
"value": ""
},
{
"key": "subject_id",
"value": ""
},
{
"key": "query_id",
"value": ""
},
{
"key": "document_id",
"value": ""
},
{
"key": "checklist_id",
"value": ""
},
{
"key": "template_id",
"value": ""
},
{
"key": "application_id",
"value": ""
}
],
"item": [
{
"name": "0 — Auth (run first)",
"description": "Run 0.1 before anything else. The SDK fetches a bearer token on the first call, attaches it — and the required ProjectId header — to every request, and refreshes silently when the token expires. In Postman, the test script saves the token to {{bearer_token}} automatically.",
"item": [
{
"name": "0.1 Get Bearer Token",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"pm.test('access_token present', () => pm.expect(j.access_token).to.be.a('string'));",
"if (j.access_token) { pm.collectionVariables.set('bearer_token', j.access_token); console.log('✓ Token saved to bearer_token'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"client_id\": \"{{client_id}}\",\n \"client_secret\": \"{{client_secret}}\",\n \"grant_type\": \"client_credentials\"\n}"
},
"url": {
"raw": "{{base_url}}/oauth/token",
"host": [
"{{base_url}}"
],
"path": [
"oauth",
"token"
]
}
}
}
]
},
{
"name": "1 — Your First Call",
"description": "Search for subjects to verify your credentials and connection. If this runs without an error, you're set up correctly. If you see a 401, double-check your client_id and client_secret. If you see a 403, double-check your project_id.",
"item": [
{
"name": "1.1 Search Subjects (first page)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"pm.test('results array present', () => pm.expect(j.results).to.be.an('array'));",
"console.log('Total subjects:', j.totalCount);",
"j.results.forEach(s => console.log(s.identifier, s.firstName, s.lastName));",
"if (j.results && j.results[0]) { pm.collectionVariables.set('subject_id', j.results[0].id); console.log('✓ subject_id saved:', j.results[0].id); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/subject?pageNumber=1&pageSize=10",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"subject"
],
"query": [
{
"key": "pageNumber",
"value": "1"
},
{
"key": "pageSize",
"value": "10"
}
]
}
}
}
]
},
{
"name": "2 — Patient Creation",
"description": "The simplest operation: register one patient in xCures with a single call. Use this when you want to create patient records without immediately dispatching a query — for example, pre-loading a roster you'll query later, or registering patients triggered by an upstream event.",
"item": [
{
"name": "2.1 Create Subject (v2 — returns subject immediately)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"pm.test('subject id present', () => pm.expect(j.id).to.be.a('string'));",
"if (j.id) { pm.collectionVariables.set('subject_id', j.id); console.log('✓ subject_id saved:', j.id, '-', j.identifier); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"birthDate\": \"1980-03-15\",\n \"gender\": \"F\",\n \"addressPostalCode\": \"55401\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v2/patient-registry/subject",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v2",
"patient-registry",
"subject"
]
}
}
}
]
},
{
"name": "3 — Patient Creation & Query",
"description": "Register a patient and immediately dispatch a query to start record retrieval. Two calls in sequence: create subject, then create query. Use this when you want to start record retrieval but handle polling, document reading, and downstream processing elsewhere — for example, in a webhook handler or a separate worker process.",
"item": [
{
"name": "3.1 Create Subject",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"if (j.id) { pm.collectionVariables.set('subject_id', j.id); console.log('✓ subject_id saved:', j.id); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"birthDate\": \"1980-03-15\",\n \"gender\": \"F\",\n \"addressPostalCode\": \"55401\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v2/patient-registry/subject",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v2",
"patient-registry",
"subject"
]
}
}
},
{
"name": "3.2 Create Query (dispatches to health network)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"if (j.id) { pm.collectionVariables.set('query_id', j.id); console.log('✓ query_id saved:', j.id, '| status:', j.ccdaStatus); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"subjectId\": \"{{subject_id}}\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/query",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"query"
]
}
}
}
]
},
{
"name": "4 — Standard Treatment Workflow",
"description": "The complete Treatment workflow from first API call to evaluated checklist — the full sequence:\n\n1. Create subject (initiateEhrQuery defaults to true, so the EHR query is dispatched as part of this call)\n2. List Queries for Subject to locate the auto-fired query and save its id\n3. Poll until completed or exhausted (~20–30 min for production patients). If status = error, run step 4.3b to requery.\n4. Search documents\n5. Poll Clinical Concepts status until loaded = true (xCures normalizes documents asynchronously)\n6. Get checklists and evaluate\n7. (Optional) Get document signed S3 URL for download\n\nYou have a working end-to-end Treatment flow — subject, query, documents, Clinical Concepts, and a checklist evaluation. The sections below cover individual operations you can perform on a patient's data after the query completes.",
"item": [
{
"name": "4.1 Create Subject",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"if (j.id) { pm.collectionVariables.set('subject_id', j.id); console.log('✓ Step 1 done — subject_id:', j.id, '(EHR query auto-fired by subject creation)'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"birthDate\": \"1980-03-15\",\n \"gender\": \"F\",\n \"addressPostalCode\": \"55401\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v2/patient-registry/subject",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v2",
"patient-registry",
"subject"
]
}
}
},
{
"name": "4.2 List Queries for Subject (find the auto-fired query)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"const results = j.results || [];",
"if (results.length === 0) {",
" console.log('⚠ No query found for subject yet — the auto-fire may still be in progress; re-run 4.2 in a few seconds.');",
" return;",
"}",
"const q = results[0];",
"pm.collectionVariables.set('query_id', q.id);",
"console.log('✓ Step 2 done — query_id:', q.id, '| ccdaStatus:', q.ccdaStatus);"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/query?subjectId={{subject_id}}&pageNumber=1&pageSize=1&sortField=created&sortIsDescending=true",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"query"
],
"query": [
{
"key": "subjectId",
"value": "{{subject_id}}"
},
{
"key": "pageNumber",
"value": "1"
},
{
"key": "pageSize",
"value": "1"
},
{
"key": "sortField",
"value": "created"
},
{
"key": "sortIsDescending",
"value": "true"
}
]
}
}
},
{
"name": "4.3 Poll Query Status (repeat until completed or exhausted)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"const j = pm.response.json();",
"const status = j.ccdaStatus;",
"console.log('ccdaStatus:', status);",
"if (status === 'completed' || status === 'exhausted') { console.log('✓ Step 3 done — proceed to 4.4'); }",
"else if (status === 'error') { console.log('⚠ status=error — run 4.3b Requery to restart'); }",
"else { console.log('Still in progress (' + status + ') — wait 30s and run this request again'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/query/{{query_id}}",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"query",
"{{query_id}}"
]
}
}
},
{
"name": "4.3b Requery (only if status = error)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"if (j.id) { pm.collectionVariables.set('query_id', j.id); console.log('✓ Requery dispatched — new query_id:', j.id, '— resume polling with 4.3'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"subjectId\": \"{{subject_id}}\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/query",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"query"
]
}
}
},
{
"name": "4.4 Search Documents",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"console.log('✓ Step 4 done —', j.totalCount, 'documents retrieved');",
"if (j.results && j.results[0]) { pm.collectionVariables.set('document_id', j.results[0].id); console.log('document_id saved:', j.results[0].id); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/document?subjectId={{subject_id}}&pageNumber=1&pageSize=50",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"document"
],
"query": [
{
"key": "subjectId",
"value": "{{subject_id}}"
},
{
"key": "pageNumber",
"value": "1"
},
{
"key": "pageSize",
"value": "50"
}
]
}
}
},
{
"name": "4.5 Poll Clinical Concepts Status (repeat until loaded = true)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"const j = pm.response.json();",
"if (j.loaded) { console.log('✓ Step 5 done — Clinical Concepts loaded, proceed to 4.6'); }",
"else { console.log('Clinical Concepts still processing — wait 30s and run again'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/subject/{{subject_id}}/status/clinical-concepts",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"subject",
"{{subject_id}}",
"status",
"clinical-concepts"
]
}
}
},
{
"name": "4.6 Get Checklists",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"if (j && j[0]) { pm.collectionVariables.set('checklist_id', j[0].id); console.log('✓ Step 6a done — checklist_id saved:', j[0].id); }",
"else { console.log('No checklists configured for this project'); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/checklist?type=questionnaire",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"checklist"
],
"query": [
{
"key": "type",
"value": "questionnaire"
}
]
}
}
},
{
"name": "4.7 Evaluate Checklist",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 201', () => pm.response.to.have.status(201));",
"const j = pm.response.json();",
"if (j.criteria) { j.criteria.forEach(c => console.log(c.result ? '✓' : '✗', c.description)); }",
"console.log('✓ Step 6 done — checklist evaluated');"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"subjectId\": \"{{subject_id}}\"\n}"
},
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/checklist/{{checklist_id}}/evaluate",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"checklist",
"{{checklist_id}}",
"evaluate"
]
}
}
},
{
"name": "4.8 Get Document (signed S3 URL for download) [optional]",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"const docs = Array.isArray(j) ? j : [j];",
"if (docs[0] && docs[0].signedS3Url) { console.log('✓ Step 7 done — Download URL:', docs[0].signedS3Url); console.log('Filename:', docs[0].fileName); }",
"else { console.log('Response:', JSON.stringify(docs[0], null, 2)); }"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/document/{{document_id}}",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"document",
"{{document_id}}"
]
}
}
}
]
},
{
"name": "5 — List Subjects",
"description": "To enumerate every patient in your project, use the subject search endpoint. Pass no filters to list the entire project, or pass parameters like lastName, firstName, or createdStart / createdEnd to scope the listing. The response always includes a totalCount regardless of pageSize — you don't need to paginate to get a count.",
"item": [
{
"name": "5.1 List Subjects (with optional filters)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"console.log('Total:', j.totalCount, '| Page size:', j.results.length);",
"j.results.forEach(s => console.log(s.identifier, s.firstName, s.lastName));"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/subject?pageNumber=1&pageSize=50",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"subject"
],
"query": [
{
"key": "pageNumber",
"value": "1"
},
{
"key": "pageSize",
"value": "50"
},
{
"key": "sortField",
"value": "identifier",
"disabled": true
},
{
"key": "sortIsDescending",
"value": "false",
"disabled": true
},
{
"key": "firstName",
"value": "",
"disabled": true
},
{
"key": "lastName",
"value": "",
"disabled": true
},
{
"key": "email",
"value": "",
"disabled": true
},
{
"key": "birthDate",
"value": "",
"disabled": true
},
{
"key": "city",
"value": "",
"disabled": true
},
{
"key": "state",
"value": "",
"disabled": true
},
{
"key": "postalCode",
"value": "",
"disabled": true
},
{
"key": "gender",
"value": "",
"disabled": true
},
{
"key": "identifier",
"value": "",
"disabled": true
},
{
"key": "deleted",
"value": "false",
"disabled": true
},
{
"key": "createdStart",
"value": "2025-01-01T00:00:00Z",
"disabled": true
},
{
"key": "createdEnd",
"value": "2025-12-31T23:59:59Z",
"disabled": true
}
]
}
}
}
]
},
{
"name": "6 — Document Count",
"description": "To get the total number of documents retrieved for a patient, call document search with pageSize=1. The server always returns the full totalCount in the response envelope regardless of page size, so there is no need to paginate through all results just to count them. If totalCount is 0 after a query completes, verify the patient's demographics and requery.",
"item": [
{
"name": "6.1 Document Count (pageSize=1, read totalCount)",
"event": [
{
"listen": "test",
"script": {
"exec": [
"pm.test('Status 200', () => pm.response.to.have.status(200));",
"const j = pm.response.json();",
"console.log('Document count:', j.totalCount);"
],
"type": "text/javascript"
}
}
],
"request": {
"method": "GET",
"header": [
{
"key": "Authorization",
"value": "Bearer {{bearer_token}}"
},
{
"key": "ProjectId",
"value": "{{project_id}}"
}
],
"url": {
"raw": "{{base_url}}/api/v1/patient-registry/document?subjectId={{subject_id}}&pageNumber=1&pageSize=1",
"host": [
"{{base_url}}"
],
"path": [
"api",
"v1",
"patient-registry",
"document"
],
"query": [
{
"key": "subjectId",
"value": "{{subject_id}}"
},
{
"key": "pageNumber",
"value": "1"
},
{
"key": "pageSize",
"value": "1"
}
]
# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/xcures/refs/heads/main/examples/xcures-workflow-playbook.postman_collection.json
Work with this as data
Every example here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for examples
4 MCP tools reach this
find_examplesBrowse and filter every example in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This example
curl "https://apis.io/api/v1/examples/xcures-workflow-playbook.postman_collection"
All examples
curl "https://apis.io/api/v1/examples?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.