Skip to content

Medical Records Requester API

Overview

Welcome to the Sharecare Requester API! This API allows you to submit and manage medical record requests on behalf of a requester. This guide covers how to onboard and use the API.

Prerequisites

To integrate the Sharecare Requester API into your system, you will need an API key for your Sharecare requester account, which will be passed with each API request to authenticate you. See Getting started

Getting Started

  • Sign up To get started with the API please email requester-support@sharecare.com with your business name and a breif summary of what you are looking to achieve with the requester API, and our team will guide you through the setup process.
  • Read ahead Look at our examples and instructions below to see how to integrate with each of our endpoints.

What you can do with the API

Create or Update Requests

  • Purpose: Create new requests for medical records by calling this endpoint is a new unique reference number. Update existing requests by sending the changed fields with an existing reference number.
  • Endpoint: /medical-records/requester/
  • How to Use: Send a PATCH request with a list of requests. The API will decide whether to create new requests or update existing ones based on the provided information.

Search Requests

  • Purpose: Search for requests based on specific filters. Any one of these fields patient reference, patient firstName, patient lastName and patient dob is mandatory for this endpoint.
  • Endpoint: /medical-records/requester/
  • How to Use: Send a POST request with the filters you want to use. The API call supports pagination.

Delete a Request

  • Purpose: Delete a specific request based on its reference number. Reference number is mandatory for this endpoint.
  • Endpoint: /medical-records/requester/{referenceNumber}
  • How to Use: Send a DELETE request with the reference number of the request you want to delete.

Get Request Types

  • Purpose: Retrieve a list of available request type and subtype for your account.
  • Endpoint: /medical-records/requester/requestTypes
  • How to Use: Send a GET request to get a JSON list of request types.

Key Concepts

  • Request: Represents a request for medical information. Includes details about the patient, provider, and type of request.
  • Response: The reply you get from the API after making a request. Includes the status of the request and any relevant data.
  • Request Types: Different reasons for making the request for medical information you can make, such as for legal cases, audits or continuing care.

Search Requests

POST /medical-records/requester

  • Description: Searches one or more medical record requests.
  • Request: POST with a list of request objects criteria to be searched.
  • Content Type: application/json
  • Response:
  • 200 OK: Returns a list of requestes based on search criteria.
  • 400 Bad Request: Returns an error if the request is malformed or if there are any validation errors.

API

API Documentation

Refer to our API documentation for the most up to date specifications Simply click "Try it out" then "Execute" with the default values to see a live response.

Open In a New Window

Example

Try out the curl as is for a response

Request
curl -L 'https://gateway.stage.sharecare.com/medical-records/requester' \
    -H 'X-API-Key: <API_KEY_HERE>' \
    -H 'X-API-Version: 1.0.0' \
    -H 'accept: application/json'
    -H 'Content-Type: application/json' \
    -d '{
        "page": 1,
        "limit": 100,
        "sort": {},
        "filter": [
          {
            "patient": {
              "firstName": "John",
              "type": "",
              "reference": "",
              "zip": "",
              "lastName": "",
              "dob": ""
            },
            "request": {
              "type": "Authorization",
              "subTyp": "Continuing Care"
            }
          }
        ]
      }'

Returns the original query along with the results array containing the response data

Sample Response
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "page": 1,
      "limit": 100,
      "sort": {},
      "filter": [
        {
          "patient": {
            "type": "",
            "reference": "",
            "zip": "",
            "firstName": "John",
            "lastName": "",
            "dob": ""
          },
          "request": {
            "type": "Authorization",
            "subTyp": "Continuing Care"
          }
        }
      ],
      "results": [
        {
          "referenceNumber": "ORDER_REF_NO_1221",
          "patient": {
            "type": "PATIENT_DETAILS",
            "reference": "A1B2C3",
            "zip": "12345",
            "firstName": "John",
            "lastName": "Doe",
            "dob": "01/01/1980"
          },
          "provider": {
            "type": "PROVIDER_DETAILS",
            "id": "P12345",
            "groupName": "Health Group",
            "npi": "1234567890",
            "firstName": "Jane",
            "lastName": "Smith",
            "address1": "123 Main St",
            "address2": "Suite 100",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345",
            "phone": "555-123-2221",
            "fax": "555-567-2321",
            "contact": "jane.smith@example.com"
          },
          "request": {
            "type": "",
            "requestType": "Authorization",
            "requestSubType": "Continuing Care",
            "datesOfService": {
              "type": "startEnd",
              "start": "01/01/2023",
              "end": "01/31/2023"
            },
            "disclosures": ["abstract", "history_and_physical"]
          },
          "webhook": {
            "sendStatusChange": false,
            "url": ""
          },
          "authorizationUploadUrl": "https://testlink.com",
          "status": {
            "documentAvailable": false,
            "status": "Received",
            "updated": "07/10/2024 13:20:57",
            "processed": null,
            "processedPlatform": null,
            "authorizationName": "3bd93e82-515d-44fc-8ce5-84ccfbea3a5d"
          }
        }
      ]
    }
  ]
}
- 400 Response Body 
{
  "code": 400,
  "message": "Fail to process request: {\"code\":400,\"message\":\"Bad request\",\"errors\":[{\"code\":0,\"message\":\"Please ensure Patient#1 has  valid search parameter.\"}]}",
  "errors": [
    {
      "code": 400,
      "message": "Fail to process request: {\"code\":400,\"message\":\"Bad request\",\"errors\":[{\"code\":0,\"message\":\"Please ensure Patient#1 has  valid search parameter.\"}]}",
      "exception": null
    }
  ]
}

Payload Details

Legends: Y: Yes N: No C: Conditional (At least one patient-related field is required to conduct the search.)

Field Name Description Is Required
page page no when the search result returns more than 1 page Y
limit no of records returned in each search Y
sort <not available> N
filter
patient Minimum one field related to patient is required to perform search
patient.type Patient type C
patient.reference Patient reference number C
patient.zip Patient ZIP code C
patient.firstName Patient FirstName C
patient.lastName Patient LastName C
patient.dob Patient Date of birth C
request
request.type Request Type Y
request.subType Request Sub type Y

Create or Update Request of Medical Information (ROI)

PATCH /medical-records/requester

  • Description:

    • Creates or updates one or more Request of Medical Information (ROI) objects. The HTTP request always takes an array of ROI objects.
    • The referenceNumber field is required to determine which specific ROI you are referring to.
    • Fields set to null will delete the value, and fields not included in the request body will retain their current values for existing ROIs.
    • Additionally, each call will return an authorizationUploadUrl which provides the URL for uploading the authorization PDF.
    • This URL is referenced in the Upload section below and must be used appropriately; otherwise, the underlying ROI for information will not be processed.

  • Request: PATCH with a list of request objects.

  • Content Type: application/json

  • Response:

  • 200 OK: Returns a list of created or updated requests.

  • 400 Bad Request: Returns an error if the request is malformed or if there are any validation errors.

API

API Documentation

Refer to our API documentation for the most up to date specifications Simply click "Try it out" then "Execute" with the default values to see a live response.

Open In a New Window

Example

A list of requests to create or update, the API will decide whether to create or update these requests based on whether the id is provided.

Try out the curl as is for a response

Request
curl -X 'PATCH' 'https://gateway.stage.sharecare.com/medical-records/requester' \
    -H 'X-API-Key: <API_KEY_HERE>' \
    -H 'X-API-Version: 1.0.0' \
    -H 'accept: application/json'
    -H 'Content-Type: application/json' \
    -d '[
          {
            "referenceNumber": "ORDER_REF_NO_1221",
            "patient": {
              "type": "PATIENT_DETAILS",
              "reference": "A1B2C3",
              "zip": "12345",
              "firstName": "John",
              "lastName": "Doe",
              "dob": "1980-01-01"
            },
            "provider": {
              "type": "PROVIDER_DETAILS",
              "id": "P12345",
              "groupName": "Health Group",
              "npi": "1234567890",
              "firstName": "Jane",
              "lastName": "Smith",
              "address1": "123 Main St",
              "address2": "Suite 100",
              "city": "Anytown",
              "state": "CA",
              "zip": "12345",
              "phone": "555-123-2221",
              "fax": "555-567-2321",
              "contact": "jane.smith@example.com"
            },
            "request": {
              "type": "",
              "requestType": "Authorization",
              "requestSubType": "Continuing Care",
              "datesOfService": {
                "type": "startEnd",
                "start": "2023-01-01",
                "end": "2023-01-31"
              },
              "disclosures": ["abstract", "history_and_physical"]
            },
            "webhook": {
              "sendStatusChange": false,
              "url": ""
            }
          }
        ]'
  • Success Response (200)
    Sample Response
    {
    "code": 200,
    "message": "Success",
    "data": [
        {
            "referenceNumber": "ORDER_REF_NO_1221",
            "patient": {
                "type": "PATIENT_DETAILS",
                "reference": "A1B2C3",
                "zip": "12345",
                "firstName": "John",
                "lastName": "Doe",
                "dob": "01/01/1980"
            },
            "provider": {
                "type": "PROVIDER_DETAILS",
                "id": "P12345",
                "groupName": "Health Group",
                "npi": "1234567890",
                "firstName": "Jane",
                "lastName": "Smith",
                "address1": "123 Main St",
                "address2": "Suite 100",
                "city": "Anytown",
                "state": "CA",
                "zip": "12345",
                "phone": "555-123-2221",
                "fax": "555-567-2321",
                "contact": "jane.smith@example.com"
            },
            "request": {
                "type": "",
                "requestType": "Authorization",
                "requestSubType": "Continuing Care",
                "datesOfService": {
                "type": "startEnd",
                "start": "01/01/2023",
                "end": "01/31/2023"
                },
                "disclosures": ["abstract", "history_and_physical"]
            },
            "webhook": {
                "sendStatusChange": false,
                "url": ""
            },
            "authorizationUploadUrl": "https://testlink.com",
            "status": {
                "documentAvailable": false,
                "status": "Received",
                "updated": "07/10/2024 13:20:57",
                "processed": null,
                "processedPlatform": null,
                "authorizationName": "3bd93e82-515d-44fc-8ce5-84ccfbea3a5d"
            }
        }
    ]
}
  • 400 Response Body
{
  "code": 400,
  "message": "Fail to process request: {\"code\":400,\"message\":\"Bad request\",\"errors\":[{\"code\":1,\"message\":\"Please ensure that Patient First name is not null or empty. \\nRequest block 1 of 1.\"}]}",
  "errors": [
    {
      "code": 400,
      "message": "Fail to process request: {\"code\":400,\"message\":\"Bad request\",\"errors\":[{\"code\":1,\"message\":\"Please ensure that Patient First name is not null or empty. \\nRequest block 1 of 1.\"}]}",
      "exception": null
    }
  ]
}

Payload Details

Legends: Y:Yes N:No

Field Name Description Is Required
referenceNumber Unique Reference Number for each request. Y
patient
patient.type Patient Type N
patient.reference Patient Reference Number N
patient.zip Patient Zip Code N
patient.firstName Patient First Name Y
patient.lastName Patient Last Name Y
patient.dob Patient Date of birth in YYYY-MM-DD format. Y
provider
provider.type Provider Type N
provider.id Provider Id Y
provider.groupName Provider Group Name N
provider.npi Provider NPI N
provider.firstName Provider First Name N
provider.lastName Provider Last Name N
provider.address1 Provider Address1 N
provider.address2 Provider Address2 N
provider.city Provider City N
provider.state Provider State N
provider.zip Provider ZIP N
provider.phone Provider Phone N
provider.fax Provider Fax N
provider.contact Provider contact details N
request
request.type Send "", if value not available Y
request.requestType Request Type. This is an important field. Please make sure
to send the proper data here.		 Y
request.requestSubtype Request Subtype. This is an important field. Please make sure
to send proper data here.		 Y
request.dateOfService Request Date of service Y
request.dateOfService.type date of service type. By default assign "startEnd" Y
request.dateOfService.start Start date of service  in YYYY-MM-DD format. Y
request.dateOfService.end End date of service in YYYY-MM-DD format. Y
request.disclosures List of disclosures.Please refer to the disclosure list at the bottom of the document. N
webhook
webhook.sendStatusChange For future usage. N
webhook.url For future usage, Send "". Y

Upload Authorization PDF file.

  • For every Insert or Update request, the API generates an "authorizationUploadUrl" (Please refer to Response Body of Example Usage --> Create or Update Requests ) to facilitate the uploading of the "Authorization PDF" document.
  • Send a PUT HTTP request to the URL, including the Authorization PDF document in binary format.
  • The above request uploads the PDF file to cloud storage.
  • This "authorizationUploadUrl" has an expiry of 30 mins.
  • A new request must be sent if the URL has expired.
  • The API will not process the request until the Authorization File is uploaded.

Delete Request

DELETE /medical-records/requester/{referenceNumber}

  • Description: Deletes a specific medical record request using the reference number.
  • Deletion is only permitted before the authorization document is submitted. If the document has already been submitted, you may receive the following error message: 400 Bad Request: Reference Number not found or Request already processed.

  • Parameters:

  • referenceNumber (string): The unique identifier of the request to be deleted.

  • Responses:

  • 200 OK: Details of the request as response body.

  • 400 Bad Request: If the reference number is invalid.
  • 400 Bad Request: Reference Number not found Or Request already processed.

API

API Documentation

Refer to our API documentation for the most up to date specifications Simply click "Try it out" then "Execute" with the default values to see a live response.

Open In a New Window

Example

Try out the curl as is for a response

Request
curl -X 'DELETE' 'https://gateway.stage.sharecare.com/medical-records/requester/ORDER_REF_NO_1221' \
    -H 'X-API-Key: <API_KEY_HERE>' \
    -H 'X-API-Version: 1.0.0' \
    -H 'accept: application/json'
- 200 OK Response Body
Sample Response
{
    "code": 200,
    "message": "Success",
    "data": [
      {
        "referenceNumber": "ORDER_REF_NO_1221",
        "patient": {
          "type": "PATIENT_DETAILS",
          "reference": "A1B2C3",
          "zip": "12345",
          "firstName": "John",
          "lastName": "Doe",
          "dob": "01/01/1980"
        },
        "provider": {
          "type": "PROVIDER_DETAILS",
          "id": "P12345",
          "groupName": "Health Group",
          "npi": "1234567890",
          "firstName": "Jane",
          "lastName": "Smith",
          "address1": "123 Main St",
          "address2": "Suite 100",
          "city": "Anytown",
          "state": "CA",
          "zip": "12345",
          "phone": "555-123-2221",
          "fax": "555-567-2321",
          "contact": "jane.smith@example.com"
        },
        "request": {
          "type": "",
          "requestType": "Authorization",
          "requestSubType": "Continuing Care",
          "datesOfService": {
            "type": "startEnd",
            "start": "01/01/2023",
            "end": "01/31/2023"
          },
          "disclosures": ["abstract", "history_and_physical"]
        },
        "webhook": {
          "sendStatusChange": false,
          "url": ""
        },
        "authorizationUploadUrl": "https://testlink.com",
        "status": {
          "documentAvailable": false,
          "status": "Received",
          "updated": "07/10/2024 13:20:57",
          "processed": null,
          "processedPlatform": null,
          "authorizationName": "3bd93e82-515d-44fc-8ce5-84ccfbea3a5d"
        }
      }
    ]
}
- 400 Response Body

{
  "code": 400,
  "message": "Fail to process request: {\"code\":400,\"message\":\"Bad Request\",\"errors\":[{\"code\":0,\"message\":\"Reference Number not found Or Request already processed.\"}]}",
  "errors": [
    {
      "code": 400,
      "message": "Fail to process request: {\"code\":400,\"message\":\"Bad Request\",\"errors\":[{\"code\":0,\"message\":\"Reference Number not found Or Request already processed.\"}]}",
      "exception": null
    }
  ]
}

Get Request Types

GET /medical-records/requester/requestTypes

  • Description: Retrieves a list of available request types that can be submitted for the logged in user.

  • Responses:

  • 200 OK: Returns a list of request types.

  • 400 Bad Request: If the request cannot be processed.

API

API Documentation

Refer to our API documentation for the most up to date specifications Simply click "Try it out" then "Execute" with the default values to see a live response.

Open In a New Window

Example

Try out the curl as is for a response

Request
curl -X 'GET' 'https://gateway.stage.sharecare.com/medical-records/requester/requestTypes' \
    -H 'X-API-Key: <API_KEY_HERE>' \
    -H 'X-API-Version: 1.0.0' \
    -H 'accept: application/json'

Sample Response
{
    "code": 200,
    "message": "Success",
    "data": [
      [
        {
          "id": "Authorization",
          "name": "Authorization",
          "requestSubType": [
            {
              "id": "Continuing Care",
              "name": "Continuing Care",
              "disabled": null
            }
          ]
        }
      ]
    ]
}
- 400 Bad Request: Missing required fields or invalid data. 
{
  "code": 400,
  "message": "Bad Request",
  "errors": [
    {
      "code": 0,
      "message": "Missing required 'patient' block of request 2 of 4"
    }
  ]
}

Disclosures List

  1. any_and_all
  2. immunizations
  3. lab_reports
  4. medication_records
  5. newborn_birth_records
  6. nurse_notes
  7. operative_report
  8. pathology
  9. pft
  10. progress_notes
  11. radiology_imaging_films
  12. sleep_study
  13. treatment_plans
  14. therapy_notes
  15. transfer_notes
  16. wound_care
  17. x_ray_reports
  18. history_and_physical
  19. abstract
  20. billing_records
  21. commitment_papers
  22. consultation
  23. xray_reports
  24. disclosure_summary
  25. discharge_instructions
  26. discharge_summary
  27. doctor_orders
  28. echo
  29. ekc_ecg_tests
  30. ekg
  31. er_record
  32. facesheet
  33. fetal_heart_monitor_strips
  34. growth_chart
  35. consent