👾API Reference Docs

All requests need to route to https://api.abstractive.ai base URL

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
Method	POST
Route	https://api.abstractive.ai/get-token
Success Status Code	200
Limitations	Access token valid for 60 minutes
Avg. Response Time (Success)	~1 second

Input Parameters

{
  "user_api_email": "[email protected]", *
  "username_api": "[email protected]", *
  "user_api_password": "password123" *
}

* = required

Field	Type	Description
user_api_email	string	The email address you registered with Abstractive Health
username_api	string	Your API username (provided by Abstractive Health)
user_api_password	string	Your authentication password provided to you by the Abstractive Health team.

Output Parameters

{
  "status": "success",
  "status_code": 200,
  "processing": false,
  "timestamp": "2025-07-22T09:07:54.714738",
  "access_token": "xxxxxxxxxxx",
  "token_type": "Bearer"
}

Field	Type	Description
status	string	Result of the API call: "success" or "failure".
status_code	integer	Numeric code of the API result. 200 is success.
processing	boolean	Indicates whether the request is still processing: "true" or "false".
timestamp	string	Server time the response was generated in ISO-8601 format.
access_token	string	Token for subsequent API requests (lasts for 60 minutes).
token_type	string	Authentication scheme to use with the token (e.g. "Bearer").
failure_reason	string	Reason the API call failed (e.g. "Invalid Credentials").

Example Responses

Status Code	Description
200	Success { "status": "success", "status_code": 200, "processing": false, "timestamp": "2025-07-23T09:21:11.868981", "access_token": "xxxxxxxxxxx", "token_type": "Bearer" }
400	Missing required fields { "status": "failure", "status_code": 400, "processing": false, "timestamp": "2025-07-23T09:22:35.739023", "missing_fields": [ "username_api" ], "failure_reason": "Missing required fields: username_api" }
401	Unauthorized { "status": "failure", "status_code": 401, "processing": false, "timestamp": "2025-07-23T09:23:45.558430", "failure_reason": "Invalid credentials" }
500	Internal server error { "status": "failure", "status_code": 500, "processing": false, "timestamp": "2025-07-23T09:23:45.558430", "failure_reason": "The user authentication failed" }

Important Notes

• Only get a token when necessary

• Make sure you have an active token before requesting a summary

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, JPEG, and JSON formats. These retrieved documents form the foundation for generating a complete and clinically accurate medical record summary and delivered directly to you through our API.

Search Patient

Description	Provide a set of patient metadata to kick off an asynchronous Health Information Exchange (HIE) search.
Method	POST
Route	https://api.abstractive.ai/search-patient
Success Status Code	202
Limitations	We will take up to 5 patients per request.
Avg. Response Time (Success)	3 - 5 seconds (time to 202 response)

Input Parameters

{
  "user_api_email": "[email protected]", *
  "token": "string", *
  "patient_metadata": [
    {
      "addresses": [
        {
          "street_address_line": "123 Main Street",
          "city": "New York",
          "state": "NY", # two letter code
          "postal_code": "10022", # 5 digit code
          "country": "USA"
        }
      ],
      "demographics": {
        "given_name": "FName", *
        "family_name": "LName", *
        "administrative_gender_code": "F" | "M", *
        "birth_time": "YYYYMMDD", *
        "phone_number": "000-000-0000",
        "email": "[email protected]",
      }
    }
  ],
  "robustness": "20", # this defaults to "20".
  "test": true # this defaults to false.
}

* = required

Field	Type	Description
user_api_email*	string	Your email that was configured by the Abstractive Health team.
token*	string	The token retrieved from the /get-token API endpoint (Step 1).
patient_metadata*	array	Array of patients and their metadata (maximum of 5 patients)
demographics*	dict	Patient demographic details
given_name*	string	Patient first name (if they have a middle name it should still be included here)
family_name*	string	Patient last name
administrative_gender_code*	string	Patient gender (F or M)
birth_time*	string	Patient birth date (YYYYMMDD)
phone_number	string	Patient phone number (000-000-0000)
email	string	Patient email
addresses	array of dictionaries	An array 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	string	Street address of where the patient lives
city	string	City that the patient lives in
state	string	State that the patient lives in (e.g. NY)
postal_code	string	Postal/ZIP code where the patient lives (e.g. 10022)
country	string	Country where the patient lives (e.g. USA). Records are currently limited to only the USA.
robustness	string	A string integer between 1-100 where 20 represents an optimized search (roughly 3-4 minutes in duration), 70 represents a thorough search (5-7 minutes), and 100 represents a robust search (8-10 minutes).
test	boolean	A boolean that enables/disables demo mode with test patient data

Output Parameters

{
  "status": "success",
  "status_code": 202,
  "processing": true,
  "timestamp": "2025-07-23T09:38:31.232910",
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "results": [
    {
      "status": "success",
      "status_code": 202,
      "given_name": "Nwhinone",
      "family_name": "Nwhinzzztestpatient",
      "birth_time": "1981-01-01",
      "administrative_gender_code": "M",
      "pid": "patient123",
      "patient_id": "patient123",
      "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "processing": true,
      "message": "This search request is valid and is being processed. We recommend checking back every minute."
    }
  ]
}

Fields	Type	Description
status	string	Result of the API call: "success" or "failure".
status_code	integer	Numeric code of the API result. 200 is success.
conversation_id	string	A unique ID associated with the API request that is used to chain subsequent API calls.
processing	boolean	Indicates whether the request is still processing: "true" or "false".
results	array of dictionaries	Each individual patients status for patient search. Each result has its own status, processing, patient_id, and failure_reason.
patient_id	string	Unique patient identifier to identify the patient in Abstractive Health. Patient matching is performed on supplied metadata for linking the same patients.
failure_reason	string	Reason the API call failed (e.g. "Missing patient metadata").

Example Responses

Code	Description
202	All patients queued successfully { "status": "success", "status_code": 202, "processing": true, "timestamp": "2025-07-23T09:38:31.232910", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "results": [ { "status": "success", "status_code": 202, "given_name": "Nwhinone", "family_name": "Nwhinzzztestpatient", "birth_time": "1981-01-01", "administrative_gender_code": "M", "pid": "patient123", "patient_id": "patient123", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": true, "message": "This search request is valid and is being processed. We recommend checking back every minute." } ] }
207	Partial success, some queued, some failed { "status": "partial_success", "status_code": 207, "conversation_id": "string", "processing": true, "timestamp": "2025-07-23T09:38:31.232910", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "results": [ { "status": "success", "pid": "patient123", "patient_id": "patient123", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": true } ] }
400	Invalid { "status": "failure", "status_code": 400, "processing": false, "timestamp": "2025-07-23T09:42:31.039312", "invalid_fields": { "patient_metadata[0].demographics.administrative_gender_code": "Must be 'M' or 'F'" }, "failure_reason": "Invalid administrative_gender_code in patient metadata at index 0. Must be 'M' or 'F'." }
401	Unauthorized { "status": "failure", "status_code": 401, "processing": false, "timestamp": "2025-07-23T09:43:38.014655", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "failure_reason": "User authentication failed - invalid credentials" }
500	Submission Failure { "status": "failure", "status_code": 500, "processing": false, "timestamp": "2025-07-23T09:43:38.014655", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "failure_reason": "string", "error_type": "InternalServerError", "results": [ { "status": "failure", "patient_id": "patient123", "pid": "patient123", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": false, "failure_reason": "Missing patient metadata" } ] }

Test Patient Example

You can test patient search without querying the national health information exchanges by setting the field test:true. Below is the test patient demographics and address for simulating a search:

// Patient search with test patient example

{
  "user_api_email": "[email protected]",
  "token": "xxxxxxxxxx",
  "patient_metadata": [
    {
      "addresses": [
        {
          "street_address_line": "1100 Test Street",
          "city": "Helena",
          "state": "AL",
          "postal_code": "35080",
          "country": "USA"
        }
      ],
      "demographics": {
        "given_name": "Nwhinone",
        "family_name": "Nwhinzzztestpatient",
        "administrative_gender_code": "M",
        "birth_time": "19810101",
        "phone_number": "205-111-1111"
      }
    }
  ],
  "robustness": "20",
  "test": true
}

* = required (optional parameters can be excluded from request)

Important Notes

• Sending more than 5 sets of patient metadata will not result in error; sending 0 sets might result in error.

• Make sure all patient metadata belongs to the same individual

Retrieve Patient Documents

Description	After a few minutes, attempt retrieval of the patient documents in the requested format.
Method	POST
Route	https://api.abstractive.ai/retrieve-patient-docs
Success Status Code	200
Avg. Response Time (Success)	Varies based on robustness score from /search-patient: • 20 → 180 seconds • 70 → 240 seconds • 100 → 480 seconds

Input Parameters

{
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", *
  "user_api_email": "[email protected]", *
  "token": "xxxxxxxxxxx", *
  "patient_id": "patient123" | "[patient123, patient456,...,patient789]", *
  "test": false
}

* = required

Field	Type	Description
conversation_id	string	The ID returned from the /search-patient API endpoint.
user_api_email	string	Your email that was configured by the Abstractive Health team.
token	string	The token retrieved from the /get-token API endpoint.
patient_id	string or array of strings	Unique patient identifier that was provided in /search-patient API endpoint. Could also be an array of patient_id 's if all of them share the same conversation_id
test	boolean	Enables/disables demo mode with test patient data

Output Parameters

{
"status": "success",
"status_code": 200,
"conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"processing": false,
"results":
    [
        {
        "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "expires_in": 3600,
        "patient_id": "patient123",
        "status": "success",
        "status_code": 200,
        "url": "https://prod-ah-useast1-app.s3.amazonaws.com/result.zip?AWSAccessKeyId=xxxxxx&Expires=1753268355"
        }
    ]
}

Fields	Type	Description
status	string	Result of the API call: "success" or "failure".
status_code	integer	Numeric code of the API result. 200 is success.
conversation_id	string	The ID returned from the /search-patient API endpoint.
processing	boolean	Indicates whether the request is still processing: "true" or "false".
results	array of dictionaries	Each individual doc retrieval status for patient search. Each result has its own url, expires_in, status, processing, patient_id, and failure_reason.
patient_id	string	Unique patient identifier that was provided in /search-patient API endpoint.
url	string	Location to retrieve the patient documents once processing has finished.
expires_in	integer	Amount of time (in seconds) that the documents are available for you to retrieve.
failure_reason	string	Reason the API call failed (e.g. "NotFoundError").

Example Responses

Code	Description
200	Success { "status": "success", "status_code": 200, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": false, "results": [ { "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "expires_in": 3600, "patient_id": "patient123", "status": "success", "status_code": 200, "url": "https://prod-ah-useast1-app.s3.amazonaws.com/result.zip?AWSAccessKeyId=xxxxxx&Expires=1753268355" } ] }
202	Processing { "status": "processing", "status_code": 202, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": true, "results": [ { "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "message": "This retrieval request is valid but document search has not yet been completed. We recommend checking back every minute.", "patient_id": "patient123", "processing": true, "status": "success", "status_code": 202 } ] }
207	Some documents retrieved, others failed or processing { "status": "partial_success", "status_code": 207, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "processing": true, "results": [ { "status": "success", "status_code": 200, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "url": "https://s3.amazonaws.com/bucket/results.json?AWSAccessKeyId=...", "expires_in": 3600, "processing": false, }, { "status": "processing", "status_code": 202, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient456", "processing": true, "message": "This retrieval request is valid but document search has not yet been completed. Current stage: {search_status}. We recommend checking back every minute." }, { "status": "failure", "status_code": 400, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient789", "processing": false, "failure_reason": "Internal server error", "error": "Internal server error" } ] }
400	Invalid request parameters { "status": "failure", "status_code": 400, "processing": false, "timestamp": "2025-07-23T09:54:09.268172", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "missing_fields": [ "patient_id" ], "failure_reason": "Both conversation_id and patient_id are required." }
401	Unauthorized { "status": "failure", "status_code": 401, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "failure_reason": "User authentication failed - invalid credentials" }
404	Conversation_id not recognized { "status": "failure", "status_code": 404, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "results": [ { "status": "failure", "status_code": 404, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "failure_reason": "This patient id is not associated with this conversation id." } ], "processing": false }
422	External Data Failure { "status": "failure", "status_code": "422", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "results": [ { "status": "failure", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "error": "notes_parsing_error", "error_details": "We encountered an error while parsing the retrieved notes. This may be due to malformed content from the responder. Please contact support if the issue persists.", "status_code": "422", } ], "processing": false }
500	Failure { "status": "failure", "status_code": 500, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "failure_reason": "string", "error_type": "InternalServerError" }

URL Retrieval and Directory Structure

If the retrieval is successful, you can download the zipped folder from the pre-signed URL.

Output Document Information

Documents retrieved from the HIE (health information exchanges) are returned as CDAs, FHIR, PDFs, PNGs, TIFF, and JPEGs mime-type formats. For all CDA documents that Abstractive retrieves from the HIEs, we parse them through a CDA -> FHIR conversion engine. You can find documentation on FHIR here by HL7 foundation.

Subsequently, we parse all FHIR documents (which includes the CDAs converted to FHIR) into a proprietary JSON flat-file format for data standardization. Note that healthcare data is quite messy, so our format can sometimes reflect that messiness.

Any documents that not CDA or FHIR are not converted to a JSON format and left in raw format.

// Abstractive flat file format of retrieve patient documentation

Important Notes

Mimetype of the response will always be JSON even if CDA is requested.

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 the HIEs (health information exchanges) 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 \search-patient in Step 2
Method	POST
Route	https://api.abstractive.ai/upload-patient-docs
Success Status Code	200 or 202
Avg. Response Time (Success)	180 - 300 seconds

Input Parameters

{
  "user_api_email": "[email protected]", *
  "token": "xxxxxxxxxx", *
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "patient_metadata": {
      "addresses": [
        {
          "street_address_line": "123 Main Street",
          "city": "New York",
          "state": "NY", # two letter code
          "postal_code": "10022", # 5 digit code
          "country": "USA"
        }
      ],
      "demographics": {
        "given_name": "FName", *
        "family_name": "LName", *
        "administrative_gender_code": F | M, *
        "birth_time": "YYYYMMDD", *
        "phone_number": "000-000-0000"
      }
  },
  "files": { *
    "non_text": [
      "Base"
    ],
    "cda": [
      "string"
    ],
    "fhir": [
      "string"
    ]
  }
}

* = required

Field	Type	Description
user_api_email *	string	Your email that was configured by the Abstractive Health team.
conversation_id	string	Optional field. If included: A unique ID associated with your HIE \search-patient API request for capturing your results once processing has completed. If not included: The response will output a new conversation id that can be used for summarization of only the uploaded documents.
token *	string	The token retrieved from the get-token API endpoint.
patient_metadata *	array of dictionaries	Patient Metadata Dictionary
demographics *	dictionary	Patient demographic details
given_name *	string	Patient first name (if they have a middle name it should still be included here)
family_name *	string	Patient last name
administrative_gender_code *	string	Patient gender (F or M)
birth_time *	string	Patient birth date (YYYYMMDD)
phone_number	string	Patient phone number (000-000-0000)
email	string	Patient email
addresses	array of dictionaries	An array of addresses 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	string	Street address of where the patient lives
city	string	City that the patient lives in
state	string	State that the patient lives in (e.g. NY)
postal_code	string	Postal/ZIP code where the patient lives (e.g. 10022)
country	string	Country where the patient lives (e.g. USA)
files *	dictionary	Dictionary of different file types. At least one of the subtypes need to be present in the dictionary.
non_text	array of strings	An array of Base64 encoded PDF, JPEG/JPG, TIFF/tiff, PNG, files
cda	array of strings	An array of Base64 encoded CDA files
fhir	array of strings	An array of Base64 encoded FHIR files

Output Parameters

{
  "status": "success",
  "status_code": 202,
  "processing": true,
  "timestamp": "2025-07-22T11:05:17.392877",
  "conversation_id": "string",
  "files_failed": [],
  "patient_id": "string",
  "document_count": 1,
  "message": "Documents are being processed"
}

Fields	Type	Description
status	string	Result of the API call: "success" or "failure"
status_code	integer	Numeric code of the API result. 200 and 202 are success.
processing	boolean	Indicates whether the request is still processing: "true" or "false"
conversation_id	string	Either a unique ID associated with the API request that is used to chain subsequent API calls, or the ID used from the /search-patient API endpoint if one was supplied in the request.
files_failed	array	Files that failed processing. Each result has its own error, file_type, and file_index.
patient_id	string	Unique patient identifier to identify the patient in Abstractive Health. Patient matching is performed on supplied metadata for linking the same patients.
document_count	integer	Number of total files attempted processing for document upload.
message	string	Information about the API request (e.g. "Documents are being processed")
failure_reason	string	If a status of "failure" is returned, why the API request failed (e.g. "No files were successfully processed").

Example Responses

Code	Description
200	Success { "conversation_id": "string", "patient_id": "string", "status": "success", "message": "string", "files_processed": int }
202	Processing { "status": "success", "status_code": 202, "processing": true, "timestamp": "2025-07-23T11:53:29.493182", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "files_failed": [], "patient_id": "patient123", "document_count": 1, "message": "Documents are being processed" }
400	Invalid/Missing Fields { "status": "failure", "status_code": 400, "processing": false, "timestamp": "2025-07-23T11:51:17.422678", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "invalid_fields": { "patient_metadata": "Must be a dictionary" }, "failure_reason": "patient_metadata must be a dictionary" }
401	Unauthorized { "status": "failure", "status_code": 401, "processing": false, "timestamp": "2025-07-23T11:54:33.100457", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "failure_reason": "Authentication failed" }
500	Submission Failure { "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "status": "failure", "status_code": 500, "failure_reason": "string" }

Note: When uploading non-text documents (PDFs, jpegs, TIFFs, pngs), you will receive a 202 status code as these files will have to be parsed and processed first.

If you request a summary while the documents are still processing, you will receive a 409 status code error. Please allow 3-5 minutes of processing window before requesting a summary.

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 and ensure 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. You must either first call /search-patient or /upload-patient-docs API endpoints before accessing this endpoint.
Method	POST
Route	https://api.abstractive.ai/request-summary
Success Status Code	202
Avg. Response Time (Success)	3 - 5 seconds

Input Parameters

{
  "user_api_email": "[email protected]", *
  "token": "xxxxxxxxxxx", *
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", *
  "patient_id": "patient123", *
  "test": false
}

* = required

Fields	Type	Description
user_api_email	string	Your email that was configured by the Abstractive Health team.
token	string	The token retrieved from the /get-token API endpoint.
conversation_id	string	The ID returned from either the /search-patient or /upload-patient-docs API endpoints.
patient_id	string	Unique patient identifier that was provided in either the /search-patient or /upload-patient-docs API endpoints.
test	boolean	A boolean that enables/disables demo mode with test patient data

Output Parameters

{
  "status": "success",
  "status_code": 202,
  "processing": true,
  "timestamp": "2025-07-23T12:02:53.698061",
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "patient_id": "patient123",
  "message": "Summary request submitted successfully"
}

Fields	Type	Description
status	string	Result of the API call: "success" or "failure"
status_code	integer	Numeric code of the API result: 202 is success.
processing	string	Indicates whether the request is still processing: "true" or "false".
timestamp	string	Server time the response was generated in ISO-8601 format.
conversation_id	string	Unique ID associated with the API request either generated from /search-patient or /upload-patient-docs.
patient_id	string	Unique patient identifier linked to the patient in Abstractive Health.
message	string	Additional information about the API request
failure_reason	string	Reason the API call failed.

Example Responses

Code	Description
202	Processing { "status": "success", "status_code": 202, "processing": true, "timestamp": "2025-07-23T12:02:53.698061", "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "message": "Summary request submitted successfully" }
400	Invalid/Missing fields { "status": "failure", "status_code": 400, "processing": false, "timestamp": "", "conversation_id": "string", "missing_fields": [ "missing_payload_field" ], "failure_reason": "string" }
401	Unauthorized { "status": "failure", "status_code": 401, "processing": false, "timestamp": "", "failure_reason": "Invalid credentials" }
409	Search results and/or uploaded files are still being processed { "status": "failure", "status_code": 409, "processing": false, "timestamp": "TIMESTAMP", "conversation_id": "string", "patient_id": "string", "failure_reason": "The documents are still being parsed from search/upload. Please try again in a few minutes.", "user_id": "string" }
500	Submission Failure {   "processing": false, "conversation_id": "string", "failure_reason": "string", "patient_id": "string" }

Important Notes

Limit summary requests to 1 every 30 seconds.

Retrieve a Summary

Description	Retrieve the summary after requesting to create one through /request-summary API endpoint
Method	POST
Route	https://api.abstractive.ai/retrieve-summary
Success Status Code	200
Avg. Response Time (Success)	60 - 180 seconds

Input Parameters

{
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", *
  "user_api_email": "[email protected]", *
  "token": "xxxxxxxxxxx", *
  "patient_id": "patient123", *
  "test": false
}

* = required

Fields	Type	Description
conversation_id	string	The ID returned from either the /search-patient or /upload-patient-docs API endpoints.
user_api_email	string	Your email that was configured by the Abstractive Health team.
token	string	The token retrieved from the /get-token API endpoint.
patient_id	string	Unique patient identifier that was provided in either the /search-patient or /upload-patient-docs API endpoints.
test	boolean	A boolean that enables/disables demo mode with test patient data

Output Parameters

{
  "status": "success",
  "status_code": 200,
  "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "patient_id": "patient123",
  "url": "https://prod-ah-useast1-app.s3.amazonaws.com/conversation_output/pid.zip?AWSAccessKeyId=xxxx...",
  "expires_in": 3600,
  "posted": true,
  "processing": false
}

Fields	Type	Description
status	string	Result of the API call: "success" or "failure"
status_code	integer	Numeric code of the API result: 200 is success
processing	boolean	Indicates whether the result is still processing: "true" or "false"
posted	boolean	Confirmation that the summary is available to retrieve.
conversation_id	string	Unique ID associated with the API request either generated from /search-patient or /upload-patient-docs.
patient_id	string	Unique patient identifier linked to the patient in Abstractive Health.
url	string	Location to retrieve the patient documents once processing has finished.
expires_in	integer	Amount of time (in seconds) that the documents are available for you to retrieve.
message	string	Additional information about the API request
failure_reason	string	If a status of "failure" is returned, why the API request failed (e.g. "No conversation found with this ID").

Responses

Code	Description
200	Success { "status": "success", "status_code": 200, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "url": "https://prod-ah-useast1-app.s3.amazonaws.com/conversation_output/pid.zip?AWSAccessKeyId=xxxx...", "expires_in": 3600, "posted": true, "processing": false }
202	Processing { "status": "processing", "status_code": 202, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "message": "This retrieval request is valid but output has not been generated. We recommend checking back every minute.", "posted": false, "processing": true }
401	Unauthorized { "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "status": "failure", "status_code": 401, "failure_reason": "User authentication failed - invalid credentials", "processing": false }
404	Conversation_id not recognized { "status": "failure", "status_code": 404, "conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "patient_id": "patient123", "failure_reason": "No conversation found with this ID", "posted": false, "processing": false }
500	System failure { "processing": false, "conversation_id": "string", "patient_id": "string", "failure_reason": "string" }

AI Summary Format

If the retrieval is successful, you can download the json output from the pre-signed URL. It will come in the following format:

{
  "conversation_id": "",
  "section_summaries": [
    {
      "section_header": "",
      "section_summary": {
        "Events": "",
        "Followups": [],
        "Providers": [],
        "Medication": []
      }
    }
  ],
  "section_entities": [
    {
      "section_page":0, 
      "section_header": "",
      "section_entities":[{
        "Text": "",
        "Type": "",
        "Score": 0.0,
        "Traits":[],
        "Category": "",
        "Codemaps": {},
        "Endoffset": 0,
        "Beginoffset": 0, 
        "Attributes": []
      }]
    }
  ],
  "meta_summary":{
    "HPI": "",
    "Labs": [],
    "Images": [],
    "Vitals": [],
    "Allergies": [],
    "FamilyHistory": "",
    "SocialHistory": "",
    "PastClinicalEvents": [],
    "AllHistoricalFollowups": [],
    "AllHistoricalProviders": [],
    "AllHistoricalMedications": []
  },
  "meta_entities": {
    "HPI": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "Labs": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "Images": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "Vitals": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "Allergies": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "FamilyHistory": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "SocialHistory": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "PastClinicalEvents": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "AllHistoricalFollowups": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "AllHistoricalProviders": [{
    "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
    "AllHistoricalMedications": [{
      "Text": "",
      "Type": "",
      "Score": 0.0,
      "Traits": [],
      "Category": "",
      "Codemaps": {},
      "Endoffset": 0,
      "Beginoffset": 0,
      "Attributes": []
    }],
  },
  "patient_metadata": {
    "dob": "",
    "sex": "",
    "address": "",
    "last_name": "",
    "first_name": "",
    "phone_number": "",
    "provider_name": ""
  },
  "scoring": {
    "SimilarityScores":{
      "HPI": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "Labs": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "Images": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "Vitals": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "Allergies": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "FamilyHistory": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "SocialHistory": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "PastClinicalEvents": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "AllHistoricalFollowups": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "AllHistoricalProviders": {
        "OverallScore": 0.0,
        "Sentences": {}
      },
      "AllHistoricalMedications": {
        "OverallScore": 0.0,
        "Sentences": {}
      }
    }
  }
}

Important Notes

• You can retrieve a summary every 15 seconds.

• We recommend not retrieving the same summary no more than 30 times

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

Parameter Name	Description
Description	Send a new clinical treatment document to Abstractive Health
Method	POST
Route	https://api.abstractive.ai/push-document
Avg. Response Time (Success)	10 - 15 seconds

   {
        "patient": {
            "pid": "unique id of the patient",                  # required
            "given_name": "first name of the patient",          # required if no pid
            "family_name": "last name of the patient",          # required if no pid
            "birth_time": "date of birth of the patient",       # required if no pid
            "administrative_gender_code": "sex of the patient", # required if no pid
            "phone_number": "phone number of the patient",
            "email": "email of the patient",
            "street_address_line": "patient's address line",
            "city": "patient's city",
            "state": "patient's state",
            "postal_code": "patient's zipcode",
            "country": "patient's country"
        },
        "author": {
            "given_name": "first name of the author", # required
            "family_name": "last name of the author", # required
            "authored_on": "date of the document",    # required
            "npi": "national provider identifier",    # required
            "specialty": "provider's specialty"       # required
        },
        "summary_assessment": "clinical context of the summary in plain text",    # required
        "summary_edited": "summary with edits made",                              # required
        "summary_format": "text/json. Defaults to text.",
        "user_api_email": "string",                                               # required
        "token": "string"                                                         # required
    }

Parameter Name	Description
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.
email	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

Code	Description
200	Success { "pushed": true, "conversation_id": "string" }
400	File format failure { "status": "failure", "status_code": 400, "processing": false, "timestamp": "", "conversation_id": "string", "missing_fields": [ "missing_payload_field" ], "failure_reason": "string" }
401	Unauthorized { "conversation_id": "string", "failure_reason": "string" }
500	Failure { "conversation_id": "string", "failure_reason": "string" }

Important Notes

• You are required to return a clinical treatment document for every patient retrieved from Carequality® within 7 days.