How to use the API
Step 1: Get Token
Obtaining a token is the first step when using the API. An active token is required to search and retrieve patient documents from health information exchanges, summarize clinical documents, and push treatment records back into the system. Once you have an active token, it can be reused across all API operations — there’s no need to request a new token for each task.
Description
Retrieves an authentication token (valid for 60 minutes)
Method
POST
Parameters
user_api_email
The email address you registered with Abstractive Health
username_api
Your API username (provided by Abstractive Health)
user_api_password
Your authentication password provided to you by the Abstractive Health team.
Responses
200
Success
401
Unauthorized
Important Notes
Step 2. Search for a Patient (Optional)
With minimally required patient demographic information - first name, last name, date of birth, and gender - you can initiate a powerful query that retrieves a patient’s lifetime of clinical documentation. We search across 70,000+ healthcare organization connected via the Carequality® health information exchange, returning a wide range of document types including CDA, FHIR, PDF, TIFF, and JPEG formats. These retrieved documents form the foundation for generating a complete and clinically accurate medical record summary—delivered directly to you through our API.
Search Patient
Description
Provide a set of patient metadata to kick off an asynchronous Carequality® search.
Method
POST
Limitations
We will take up to 15 of the patient metadata objects.
Parameters
user_api_email
Your email that was configured by the Abstractive Health team.
conversation_id
A unique ID associated with your Carequality® search request that is used in the “Retrieve Patient Documents” API for capturing your results once processing has completed.
token
The token retrieved from the Get Token API endpoint.
patient_metadata
List of patients and their metadata
demographics
Patient demographic details
given_name
Patient first name (if they have a middle name it should still be included here)
family_name
Patient last name
administrative_gender_code
Patient gender
birth_time
Patient birth date
phone_number
Patient phone number
Patient email
addresses
A list of address where the patient has lived throughout their life as dictionaries with the keys given below (street_address_line, city, state, postal_code, country).
street_address_line
Street address of where the patient lives
city
City that the patient lives in
state
State that the patient lives in
postal_code
Postal/ZIP code where the patient lives
country
Country where the patient lives
robustness
A string integer between 1-100 where 20 represents an optimized search (3-4 mi), 70 represents a thorough search (5-7min), and 100 represents a robust search (8-10min).
test
A boolean that enables/disables demo mode with test patient data
Responses
202
Processing
400
Invalid
401
Unauthorized
500
Submission Failure
processing
Confirmation that the request was successful.
conversation_id
A unique ID associated with your Carequality® search request that is used in the “Retrieve Patient Documents” API for capturing your results once processing has completed.
Important Notes
Retrieve Patient Documents
Description
After a few minutes, attempt retrieval of the patient documents in the requested format.
Method
POST
Parameters
conversation_id
The ID returned from the “Request Patient Documents” API endpoint.
user_api_email
Your email that was configured by the Abstractive Health team.
token
The token retrieved from the Get Token API endpoint.
patient_id
Unique patient identifier that was provided in “Request Patient Documents" API endpoint.
test
A boolean that enables/disables demo mode with test patient data
200
Success
202
Processing
401
Unauthorized
404
Conversation_id not recognized
500
Failure
posted
Confirmation that the patient documents are available to retrieve.
conversation_id
The ID returned from the “Request Patient Documents” API endpoint.
url
Location to retrieve the patient documents from Carequalty® once processing has finished.
URL Retrieval
If the retrieval is successful, you can download the zipped folder from the pre-signed URL.
Important Notes
Step 3. Bulk Document Upload (Optional)
Upload multiple PDF, JPEG/JPG, TIFF/tiff, PNG, CDA or FHIR documents to generate a medical summary from the documents themselves, or to include with the documents you retrieved from Carequality® in step 2. This step is for net new documents, you do not need to resend us the documents that you retrieved in step 2.
Description
Upload the documents you want to use to generate a medical summary or include with the documents you retrieved from Carequality® in step 2
Method
POST
Parameters
user_api_email
Your email that was configured by the Abstractive Health team.
conversation_id
A unique ID associated with your Carequality® search request that is used in the “Retrieve Patient Documents” API for capturing your results once processing has completed.
token
The token retrieved from the Get Token API endpoint.
patient_metadata
Patient Metadata Dictionary
demographics
Patient demographic details
given_name
Patient first name (if they have a middle name it should still be included here)
family_name
Patient last name
administrative_gender_code
Patient gender
birth_time
Patient birth date
phone_number
Patient phone number
Patient email
addresses
A list of address where the patient has lived throughout their life as dictionaries with the keys given below (street_address_line, city, state, postal_code, country).
street_address_line
Street address of where the patient lives
city
City that the patient lives in
state
State that the patient lives in
postal_code
Postal/ZIP code where the patient lives
country
Country where the patient lives
files
Dictionary of different file types
non_text
An array of Base64 encoded PDF, JPEG/JPG, TIFF/tiff, PNG, files
cda
An array of Base64 encoded CDA files
fhir
An array of Base64 encoded FHIR files
Responses
200
Success
202
Processing
400
Invalid
401
Unauthorized
500
Submission Failure
status
Confirmation that the request was successful.
conversation_id
A unique ID associated with your summary request that is used in the “Retrieve a Summary” API for capturing your results once processing has completed.
files_processed
Number of files successfully uploaded
4. Request a Summary (From Patient Search and/or From Bulk Upload Documents)
Using the clinical documents retrieved from a patient search—along with any additional documents you choose to include—we generate a comprehensive medical summary that surfaces key clinical insights. The summary includes:
Medical history, past clinical events, family history, social history, allergies
Medications, labs, vitals
Radiology findings, follow-up recommendations, and care team information
Designed for clinical treatment workflows, our summaries support clinicians before a visit, during care handoffs, and at discharge—ensuring clinicians have the right information at the right time.
In addition, each summary includes structured medical entities extracted from the record, including ICD-10, CPT, and HCC codes, enabling downstream use in risk adjustment, billing, and care coordination.
Description
Generate a medical summary based on the documents retrieved from patient search and/or bulk upload endpoints.
Method
POST
Parameters
conversation_id
The ID returned from the “Request Patient Documents” API endpoint.
user_api_email
Your email that was configured by the Abstractive Health team.
token
The token retrieved from the Get Token API endpoint.
patient_id
Unique patient identifier that was provided in “Request Patient Documents" API endpoint.
test
A boolean that enables/disables demo mode with test patient data
Responses
202
Processing
400
Invalid
401
Unauthorized
500
Submission Failure
processing
Confirmation that the request was successful.
conversation_id
A unique ID associated with your summary request that is used in the “Retrieve a Summary” API for capturing your results once processing has completed.
Important Notes
Retrieve a Summary
Description
Retrieve summary of the PDFs you uploaded
Method
POST
Parameters
conversation_id
The ID returned from the “Request a Summary” API endpoint.
user_api_email
Your email that was configured by the Abstractive Health team.
token
The token retrieved from the Get Token API endpoint.
patient_id
Unique patient identifier that was provided in “Request Patient Documents" API endpoint.
test
A boolean that enables/disables demo mode with test patient data
Responses
200
Success
202
Processing
401
Unauthorized
404
Conversation_id not recognized
500
System failure
posted
Confirmation that the summary is available to retrieve.
conversation_id
The ID returned from the “Request a Summary” API endpoint.
url
Location to retrieve the summary result once processing has finished.
URL Retrieval
If the retrieval is successful, you can download the json output from the pre-signed URL. It will come in the following format:
Important Notes
Step 4. Push Back Treatment Documents
As part of using our patient search API, you are required to submit any new clinical treatment records within 7 days of your document retrieval. This requirement ensures compliance with the Carequality® framework and other national health information exchange (HIE) policies.
Our participation in these exchanges is governed by a principle of data reciprocity—meaning that in return for accessing clinical records, your organization must contribute new treatment documentation back into the network. This fosters a nationwide ecosystem of interoperability and care coordination.
The Abstractive Health team is here to support you. We’re happy to guide you through the process of formatting and submitting your documents back to the health information exchanges.
Push a document
Description
Send a new clinical treatment document to Abstractive Health
Method
POST
pid
A unique patient identifier, generated for your organization by Abstractive Health, during patient search and/or medical summarization. If pid is provided, other demographic fields are optional.
given_name
Patient's first name. Include the full first name and any middle names if available.
family_name
Patient's last name or surname.
birth_time
Patient’s date of birth in YYYYMMDD format.
administrative_gender_code
Patient’s sex or gender code. Expected values: M, F, U (unknown).
phone_number
Patient’s phone number in standard U.S. format: XXX-XXX-XXXX.
Patient’s email address. Used for improved record linkage and communication.
street_address_line
Patient’s primary street address (e.g., 123 Main St Apt 4B).
city
Patient’s city of residence.
state
Two-letter U.S. state abbreviation (e.g., NY).
postal_code
ZIP code or postal code.
country
Two-letter country code (e.g., US).
given_name
First name of the authoring clinician.
family_name
Last name of the provider or authoring clinician.
authored_on
Date the treatment summary was authored. Must be in YYYYMMDD format.
npi
National Provider Identifier (NPI) of the authoring clinician. Do not pass an organization NPI.
specialty
Medical specialty of the author (e.g., Family Medicine, Internal Medicine).
summary_assessment
A plain text narrative describing the clinical context or assessment that the summary reflects. This could include details such as diagnoses, treatment rationale, visit purpose, or findings relevant to the encounter. Use this to give background on how the summary was used with the patient during clinical treatment.
summary_edited
The final version of the medical summary after any manual edits. This will be treated as the official treatment note being pushed into the health information exchange.
summary_format
Specifies the format of the summary_edited field. Default is text (plain text). If you are submitting back to us the JSON format of our structured summary with edits that we provided you, set this to json.
user_api_email
Your API username (provided by Abstractive Health)
token
Active token retrieved from the Get Token API
Responses
200
Success
400
File format failure
401
Unauthorized
500
Failure
Important Notes
Last updated