{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d62c8932-9d49-46f7-a6b1-34e70ec72d3f","name":"HealthMark Exchange","description":"# 🏥 HMG's HealthMark **Exchange**\n\n## **Overview**\n\n**'HealthMark Exchange'** is HealthMark Group's Release of Information (ROI) API. This API represents HealthMark Group's latest product capability, designed for tech-savvy partners that require seamless, programmatic access to Release of Information workflows. The RoI API capability from HealthMark Group extends and enhances our existing Release of Information services by enabling direct system-to-system integration.\n\nThrough these FHIR R4-based APIs, requestors can automate the end-to-end process of submitting medical records requests, querying real-time request status updates, and securely retrieving completed record deliveries. This modern architecture reduces manual intervention, improves throughput, and ensures scalable, compliant exchange of health information.\n\nHMG's HealthMark Exchange platform supports two broad use cases for record retrieval:\n\n**CORE** — Requests for Continuity of Care, patient requests, insurance and disability requests, and attorney requests are collectively considered as belonging to CORE usecase.\n\n**AUDIT** — Requests from payers, and on their behalf, for the purpose of Risk Adjustment, audits such as RAD-V, and quality programs such as HEDIS are collectively considered as belonging to AUDIT usecase.\n\nThe overall flow differs slightly between CORE and AUDIT use cases (described below). As a requester, it is critical that you work with HMG's HealthMark Exchange support team to ensure your client/user credentials are set up accurately within the HealthMark Exchange platform to reflect your specific use case(s).\n\nThe API supports the following authentication methods:\n\n- **User-Based:** Individual clinicians/staff with Cognito credentials\n    \n- **Machine-to-Machine (M2M):** System-to-system integration with client credentials\n    \n\n## Key Features\n\n🔐 **Enterprise Security** - OAuth 2.0, HIPAA compliance, encryption, audit logging  \n⚡ **Fast & Reliable** - Real-time updates  \n📊 **Complete Visibility** - Request tracking and Error handling  \n🏥 **FHIR R4 Standard** - Industry-standard healthcare data format.\n\n---\n\n## Overall Flow - CORE\n\n<img src=\"https://content.pstmn.io/4541a08a-6014-4203-9a54-b6f7943a3c3c/aW1hZ2UucG5n\" width=\"414\" height=\"727\">\n\nThe workflow begins with user registration and authentication, followed by an optional org search within HealthMark Group's data source directory. Requestors can then submit RoI requests via Task resources and monitor their progress until completion.\n\n1. **Authenticate** → Get New Access Token\n    \n2. **Search Organizations (Optional but strongly recommended)** → Find the healthcare provider/record source\n    \n3. **Create Task** → Submit ROI request\n    \n4. **Check Status** → Monitor request progress\n    \n5. **Retrieve Records** → Download completed medical records\n    \n\n## Overall Flow - AUDIT\n\n<img src=\"https://content.pstmn.io/380674b3-9a7a-4fc3-9a3c-167ba04e8dfb/aW1hZ2UucG5n\" width=\"793\" height=\"727\">\n\nThe workflow begins with user registration and authentication, followed by an optional org search within HealthMark Group's data source directory. Requsters must also search for a Payer . Requestors must then submit a Batch Task . Once the Batch task has been accepted by the HealthMark Exchange Platform, Requsters can proceed to add the individual AUDIT requsts or child Tasks to the open Batch task. Requsters will then continue to monitor the progress of the child Tasks until completion.\n\n1. **Authenticate** → Get New Access Token\n    \n2. **Search Organizations (Optional but strongly recommended)** → Find the healthcare provider/record source\n    \n3. **Search Payer (mandatory)**\n    \n4. **Create Batch Task**\n    \n5. **Create Child Task and add it to Batch task** → Submit ROI request\n    \n6. **Check Status of Child Tasks** → Monitor request progress\n    \n7. **Retrieve Records** → Download completed medical records\n    \n\n---\n\n## 🚀 Quick Start\n\n## 1: MACHINE-TO-MACHINE (M2M) AUTHENTICATION (Preferred)\n\n## 1.1 Registration (M2M Clients)\n\n### For System-to-System Integration:\n\n1. A requestor organization initiates the registration process by contacting the HealthMark Group RoI API support team at \"[MedExchangeSupport@healthmark-group.com](https://mailto:RoIAPIsupport@healthmark-group.com/)\".\n    \n2. A Test client account will be generated by HealthMark Group with the requestor's **System name** (your organization/application).\n    \n3. HealthMark Group's support team will share credentials via secure mail.\n    \n4. Upon successful registration, the user will be able to submit FHIR transactions with the **TEST account**.\n    \n5. Once connectivity and end to end testing has been completed using the Test account, the user will also be commissioned with a **PROD account**.\n    \n\n---\n\n## 1.2 Authentication Details (M2M)\n\n- **baseURL**: [https://roiapi.healthmark-group.com](https://roiapi.healthmark-group.com/)\n    \n- **client_id** and **client_secret**: The credentials can be requested by contacting the HealthMark Group support team at \"[MedExchangeSupport@healthmark-group.com](https://mailto:RoIAPIsupport@healthmark-group.com/)\".\n    \n- **auth_URL**: [https://roiapiauth.healthmark-group.com/oauth2/authorize](https://roiapiauth.healthmark-group.com/oauth2/authorize)\n    \n- **access_token_URL**: [https://roiapiauth.healthmark-group.com/oauth2/token](https://roiapiauth.healthmark-group.com/oauth2/token)\n    \n- **Redirect URI**: `https://localhost`\n    \n- **Grant Type**: Client Credentials\n    \n- **Token Lifetime**: 1 hour (re-authenticate when expired)\n    \n- **Scope**: Leave empty\n    \n\n---\n\n## 1.3 Supported OAuth Scopes (User)\n\nThe access token supports these scopes:\n\n- `system/Organization.r` - Read organizations\n    \n- `system/Organization.s` - Search organizations\n    \n- `system/Task.c` - Create tasks\n    \n- `system/Task.r` - Read tasks\n    \n- `system/Task.s` - Search tasks\n    \n\n**Note:** System scopes follow SMART on FHIR (FHIR R4 resource-based access control pattern). These Oauth scopes are pre-configured for the requester accounts.\n\n---\n\n## 1.4 Token Generation - Option 1: Postman\n\n**For testing and development**\n\n### Setup in Postman:\n\n1. Open any API request in Postman\n    \n2. Go to **Authorization** tab\n    \n3. Select **OAuth 2.0** from dropdown\n    \n4. Click **Get New Access Token**\n    \n5. Configure:\n    \n    - **Token Name:** MedExchange-M2M-Token\n        \n    - **Grant Type:** Client Credentials\n        \n    - **Access Token URL:** `https://roiapi.healthmark-group.com/oauth2/token`\n        \n    - **Client ID:** \\[Provided by HealthMark Group\\]\n        \n    - **Client Secret:** \\[Provided by HealthMark Group\\]\n        \n6. Click **Get New Token**\n    \n7. **Token generated immediately** (no browser login required)\n    \n8. Click **Use Token** to apply to requests\n    \n\n✅ **Token now available for all API calls (valid for 24 hour)**\n\n---\n\n## 1.5 Token Generation - Option 2: Programmatically\n\n**Recommended for production integrations**\n\n### Python Implementation: Use Python to automate the above mentioned process\n\n**Key Points:**\n\n- No user credentials needed (no password)\n    \n- Tokens generated immediately\n    \n- Ideal for background jobs and automated integrations\n    \n- Store `CLIENT_SECRET` securely (never commit to version control)\n    \n\n---\n\n## 2: USER-BASED AUTHENTICATION\n\n## 2.1 Registration (User Accounts)\n\n### For Individual Users:\n\n1. The system currently supports individual end users registered for a specific User ID and Password.\n    \n2. A user initiates the registration process by contacting the HealthMark Group RoI API support team at \"[MedExchangeSupport@healthmark-group.com](https://mailto:RoIAPIsupport@healthmark-group.com/)\".\n    \n3. A Test account will be generated by HealthMark Group with the requestor's Username and Password.\n    \n4. HealthMark Group's support team will share credentials via secure mail.\n    \n5. Upon successful registration, the user will be able to submit FHIR transactions with the **TEST account**.\n    \n6. Once connectivity and end to end testing has been completed using the Test account, the user will also be commissioned with a **PROD account**.\n    \n\n---\n\n## 2.2 Authentication Details (User)\n\n- **baseURL**: [https://roiapi.healthmark-group.com](https://roiapi.healthmark-group.com/)\n    \n- **client_id** and **client_secret**: The credentials can be requested by contacting the HealthMark Group support team at \"[MedExchangeSupport@healthmark-group.com](https://mailto:RoIAPIsupport@healthmark-group.com/)\".\n    \n- **auth_URL**: [https://roiapiauth.healthmark-group.com/oauth2/authorize](https://roiapiauth.healthmark-group.com/oauth2/authorize)\n    \n- **access_token_URL**: [https://roiapiauth.healthmark-group.com/oauth2/token](https://roiapiauth.healthmark-group.com/oauth2/token)\n    \n- **Redirect URI**: `https://localhost`\n    \n- **Grant Type**: Authorization Code (with PKCE)\n    \n- **Token Lifetime**: 1 hour (re-authenticate when expired)\n    \n- **Scope**: Leave empty\n    \n- **Code Challenge Method:** Leave empty\n    \n- **Code Verifier:** Leave empty\n    \n- **State:** Leave empty\n    \n\n---\n\n## 2.3 Supported OAuth Scopes (User)\n\nThe access token supports these scopes:\n\n- `openid` - OpenID Connect authentication\n    \n- `email` - Access to email claim\n    \n- `phone` - Access to phone claim\n    \n- `system/Organization.r` - Read organizations\n    \n- `system/Organization.s` - Search organizations\n    \n- `system/Task.c` - Create tasks\n    \n- `system/Task.r` - Read tasks\n    \n- `system/Task.s` - Search tasks\n    \n\n**Note:** System scopes follow SMART on FHIR (FHIR R4 resource-based access control pattern). These Oauth scopes are pre-configured for the requester accounts.\n\n---\n\n## 2.4 Token Generation - Option 1: Postman GUI\n\n### Setup in Postman:\n\n1. Open any API request in Postman\n    \n2. Go to **Authorization** tab\n    \n3. Select **OAuth 2.0** from dropdown\n    \n4. Click **Get New Access Token**\n    \n5. Configure:\n    \n    - **Token Name:** HealthMarkExchange-User-Token\n        \n    - **Grant Type:** Authorization Code (With PKCE)\n        \n    - **Callback URL:** `https://localhost`\n        \n    - **Auth URL:** `https://roiapiauth.healthmark-group.com/oauth2/authorize`\n        \n    - **Access Token URL:** `https://roiapiauth.healthmark-group.com/oauth2/token`\n        \n    - **Client ID:** \\[Provided by HealthMark Group\\]\n        \n    - **Client Secret:** \\[Provided by HealthMark Group\\]\n        \n6. Click **Get New Token**\n    \n7. **Browser window opens** → Enter your Cognito username and password\n    \n8. **Postman captures token automatically**\n    \n9. Click **Use Token** to apply to requests\n    \n\n✅ **Token now available for all API calls (valid for 24 hour)**\n\n---\n\n## ⚠️ Troubleshooting Authentication\n\n### Issue: \"401 Unauthorized\" Error\n\n**Cause**: Token expired or invalid  \n**Solution**: Click \"Get New Access Token\" and re-authenticate with your Cognito credentials\n\n### Issue: \"**403 Forbidden**\" Error\n\n**Cause**: Insufficient scopes  \n**Solution**: Request additional scopes during registration\n\n### Issue: \"**400 Bad Request**\" Error\n\n**Cause**: Malformed request  \n**Solution**: Verify headers, Content-Type, JSON format\n\n### Issue: \"**404 Not Found**\" Error\n\n**Cause**: Wrong endpoint or environment  \n**Solution**: Check Base URL\n\n### Issue: \"**500 Internal Server Error**\"\n\n**Cause**: Server issue  \n**Solution**: Retry with exponential backoff\n\n### Issue: Browser Redirect Not Working\n\n**Cause**: Redirect URI mismatch  \n**Solution**: Ensure redirect URI is set to `https://localhost` in the Authorization tab\n\n### Issue: Can't Get New Token\n\n**Cause**: Invalid Cognito credentials  \n**Solution**:\n\n- Verify your username/password are correct\n    \n- Contact \" [MedExchangeSupport@healthmark-group.com](https://mailto:MedExchangeSupport@healthmark-group.com) \" If you have forgotten credentials\n    \n- Check if your account is active\n    \n\n### Issue: Token Works Then Stops\n\n**Cause**: Token expired (1 hour lifetime)  \n**Solution**: Get a new token - this is expected behavior\n\n---\n\n## 🔐 Security Notes\n\n🔐 **User Accounts:**\n\n- Never share your Cognito password\n    \n- Change password regularly\n    \n- Clear old tokens from Postman periodically\n    \n- Use Prod credentials only in production\n    \n\n🔐 **M2M Clients:**\n\n- **NEVER commit Client Secret to version control**\n    \n- Store secrets in secure vaults (AWS Secrets Manager, HashiCorp Vault, etc.)\n    \n- Rotate Client Secrets annually (minimum)\n    \n- Log all M2M API usage for audit purposes\n    \n- Restrict scopes to minimum required\n    \n- Use separate M2M credentials per environment (Test vs Prod)\n    \n\n---\n\n## 📞 Support\n\n- **Email**: \"[MedExchangeSupport@healthmark-group.com](https://mailto:RoIAPIsupport@healthmark-group.com)\".","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"50239956","team":3739664,"collectionId":"d62c8932-9d49-46f7-a6b1-34e70ec72d3f","publishedId":"2sBXcBmMix","public":true,"publicUrl":"https://developer.healthmark-group.com","privateUrl":"https://go.postman.co/documentation/50239956-d62c8932-9d49-46f7-a6b1-34e70ec72d3f","customColor":{"top-bar":"FFFFFF","right-sidebar":"505B5F","highlight":"548B59"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/90ed82f4-5709-4934-aba1-ab594a30fafd/aG1nLmxvZ28ucG5n","colors":{"top-bar":"212121","right-sidebar":"505B5F","highlight":"548B59"}},{"name":"light","logo":"https://content.pstmn.io/90ed82f4-5709-4934-aba1-ab594a30fafd/aG1nLmxvZ28ucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"505B5F","highlight":"548B59"}}]}},"version":"8.11.4","publishDate":"2026-02-12T23:52:45.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/90ed82f4-5709-4934-aba1-ab594a30fafd/aG1nLmxvZ28ucG5n","logoDark":"https://content.pstmn.io/90ed82f4-5709-4934-aba1-ab594a30fafd/aG1nLmxvZ28ucG5n"}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/687c12121958e5762f7e5b56ad7cb7a503580344512ffa73ed6d730ce25c8ed6","favicon":"https://healthmark-group.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developer.healthmark-group.com/view/metadata/2sBXcBmMix"}