👾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

post

Authenticates user credentials and returns an access token

Body

Input object to obtain token

user_api_emailstringRequired

User's API email

Example: [email protected]

username_apistringOptional

User's API username. Optional, defaults to user_api_email

Example: [email protected]

user_api_passwordstringRequired

User's API password

Example: password123

Responses

200

Success

application/json

Success token response

statusstring · enumOptional

Status of the request

Example: successPossible values:

status_codeinteger · enumOptional

HTTP status code

Example: 200Possible values:

access_tokenstringOptional

OAuth token for user

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

400

Missing required fields

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/get-token

POST /get-token HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 105

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

{
  "status": "success",
  "status_code": 200,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

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)

post

Searches for patients across multiple EHR systems based on provided metadata

Body

Patient Search Input

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

api_codestringOptional

Optional team API code resolved for the authenticated organization. Used to associate the patient search with a team.

Example: default

robustnessstringOptional

Overall search robustness level. Accepts Optimized, Thorough, Robust, or an integer from 1 to 100.

Example: Optimized

summarizebooleanOptional

When true, the downstream patient search pipeline also requests summarization work after the patient search is kicked off.

Default: falseExample: true

testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true

Responses

202

At least one patient was successfully queued for processing

application/json

400

Request validation failed or all patient searches failed with client-side errors

application/json

401

Unauthorized

application/json

500

Internal server error or all patient searches failed with server-side errors

application/json

post

/search-patient

POST /search-patient HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 502

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

{
  "status": "success",
  "status_code": 202,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "processing": true,
  "timestamp": "2026-03-17T13:45:21.123456",
  "results": [
    {
      "status": "success",
      "status_code": 202,
      "patient_id": "patient123",
      "pid": "patient123",
      "given_name": "Nwhinone",
      "family_name": "Nwhinzzztestpatient",
      "birth_time": "19810101",
      "administrative_gender_code": "M",
      "processing": true,
      "error": "No patient addresses found. Please retry with patient addresses."
    }
  ]
}

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

post

Retrieves uploaded and processed patient documents as a presigned S3 URL

Body

Input object to retrieve patient documents

conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

patient_idone ofRequired

Unique patient identifier (single ID or array of IDs)

stringOptionalExample: 9de61c87-b0ce-4d34-8785-dacb55408eea

string[]OptionalExample: ["patient123","patient456"]

testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true

Responses

200

All documents successfully retrieved

application/json

Successful document retrieval response

statusstring · enumOptional

Overall status of the request

Possible values:

status_codeinteger · enumOptional

HTTP status code

Possible values:

conversation_idstringOptional

unique identifier associated with the request

processingboolean · enumOptional

whether processing is occurring

Possible values:

202

Documents still processing

application/json

207

Some documents retrieved, others failed or processing

application/json

400

Invalid request parameters

application/json

401

Unauthorized

application/json

404

Conversation_id not recognized

application/json

500

Internal server error

application/json

post

/retrieve-patient-docs

POST /retrieve-patient-docs HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_api_email": "[email protected]",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
  "test": true
}

{
  "status": "success",
  "status_code": 200,
  "conversation_id": "text",
  "processing": false,
  "results": [
    {
      "status": "success",
      "status_code": 200,
      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
      "patient_id": "patient123",
      "url": "https://s3.amazonaws.com/bucket/results.json?AWSAccessKeyId=...",
      "expires_in": 3600,
      "processing": false
    }
  ]
}

URL Retrieval and Directory Structure

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

Structure of the zipped folder

{conversation_id}.zip
   ├── cda
   │   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.xml
   │   └── ...more cda documents...
   ├── fhir
   │   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.json
   │   └── ...more FHIR json documents...
   ├── non_text
   |   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.pdf
   |   └── ...more non-text documents (jpeg/TIFF/png/pdf)...
   ├── converted_text_notes
   |   ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.pdf
   |   └── ...more text notes converted to PDF format for easy viewing...
   └──  cleaned_text_notes
       ├── {DocumentTitle}_{SourcePipeline}_{AuthoredDate}_{id}.json
       └── ...more parsed and cleaned medical documents...

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.

# Format of the cleaned_text_notes JSON
{
  "section_content": {
    "Document Title": "",
    "Document Date": "",
    "Encounter Type": "",
    "Reason for Visit": "",
    "Allergies": [],
    "Immunizations": [],
    "Medications": [],
    "Vitals": [],
    "Labs": [],
    "Images": [],
    "Procedures": [],
    "Location": "",
    "Location Type": "",
    "Medical History": [],
    "Social History": "",
    "Family History": [],
    "Document Text": [],
    "Providers": [""],
    "Organization": "",
    "Orders": [],
    "Patient": {
      "First Name": "",
      "Last Name": "",
      "Birth Date": "",
      "Gender": "",
      "Phone": "",
      "Email": "",
      "Address": ""
    }
  },
  "section_header": "",
  "section_date": "",
  "section_note_id": 0,
  "section_note_type": ""
}

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

post

Uploads patient documents (PDFs, CDA, FHIR) for processing and analysis. Supports two input modes - with existing patient_id or with patient_metadata for new patients

Body

Upload Patient Documents Input - supports two modes (existing patient or new patient with metadata)

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

conversation_idstringOptional

Optional conversation ID. If not provided, one will be generated

Example: 550e8400-e29b-41d4-a716-446655440000

patient_idstringOptional

Existing patient ID (for Option 1)

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea

Responses

200

Documents successfully uploaded and processed

application/json

Successful document upload

statusstring · enumOptional

Status of the request

Example: successPossible values:

status_codeinteger · enumOptional

HTTP status code

Example: 202Possible values:

conversation_idstringOptional

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000

patient_idstringOptional

Patient ID

Example: patient123

document_countintegerOptional

Number of files successfully processed

Example: 3

processingbooleanOptional

Whether processing is occurring

Example: true

202

Documents uploaded and processing started

application/json

400

Invalid request

application/json

401

Unauthorized

application/json

404

Patient not found

application/json

500

Internal server error

application/json

post

/upload-patient-docs

POST /upload-patient-docs HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 669

{
  "user_api_email": "[email protected]",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
  "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"
    }
  },
  "files": {
    "non_text": [
      "JVBERi0xLjQKJdPr6eEKMSAwIG9iago..."
    ],
    "cda": [
      "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0..."
    ],
    "fhir": [
      "eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50Iiwi..."
    ]
  }
}

{
  "status": "success",
  "status_code": 202,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "patient_id": "patient123",
  "document_count": 3,
  "processing": true
}

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.

Step 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

post

Requests a summary of an entire conversation containing patient documents

Body

Input object to request a conversation summary

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

patient_idstringRequired

Unique patient identifier

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea

conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000

testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true

Responses

202

Processing started

application/json

400

Missing required fields

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/request-summary

POST /request-summary HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "user_api_email": "[email protected]",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "test": true
}

{
  "status": "success",
  "status_code": 202,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "patient_id": "patient123",
  "processing": true
}

Important Notes

Limit summary requests to 1 every 30 seconds.

Step 5. 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

post

Retrieves a completed conversation summary

Body

Input object to retrieve a generated conversation summary

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

conversation_idstringRequired

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000

patient_idstringRequired

Unique patient identifier

Example: 9de61c87-b0ce-4d34-8785-dacb55408eea

testbooleanOptional

Flag to indicate if this is a test request

Default: falseExample: true

Responses

200

Summary ready

application/json

Successful summary retrieval response

statusstring · enumOptional

Status of the request

Example: successPossible values:

status_codeinteger · enumOptional

HTTP status code

Example: 200Possible values:

conversation_idstringOptional

Unique identifier associated with the request

Example: 550e8400-e29b-41d4-a716-446655440000

patient_idstringOptional

Unique patient identifier

Example: patient123

urlstringOptional

Presigned URL to download summary

Example: https://s3.amazonaws.com/bucket/summary.json?AWSAccessKeyId=...

expires_ininteger · enumOptional

URL expiration time in seconds

Example: 3600Possible values:

postedboolean · enumOptional

Whether URL is posted

Example: truePossible values:

processingboolean · enumOptional

Whether processing is occurring

Possible values:

202

Summary still processing

application/json

400

Missing required fields

application/json

401

Unauthorized

application/json

404

Conversation_id not recognized

application/json

500

Internal server error

application/json

post

/retrieve-summary

POST /retrieve-summary HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 208

{
  "user_api_email": "[email protected]",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "patient_id": "9de61c87-b0ce-4d34-8785-dacb55408eea",
  "test": true
}

{
  "status": "success",
  "status_code": 200,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "patient_id": "patient123",
  "url": "https://s3.amazonaws.com/bucket/summary.json?AWSAccessKeyId=...",
  "expires_in": 3600,
  "posted": true,
  "processing": false
}

Format of cleaned_text_notes/

{
  "section_content": {
    "Document Title": "",
    "Document Date": "",
    "Encounter Type": "",
    "Reason for Visit": "",
    "Allergies": [],
    "Immunizations": [],
    "Medications": [],
    "Vitals": [],
    "Labs": [],
    "Images": [],
    "Procedures": [],
    "Location": "",
    "Location Type": "",
    "Medical History": [],
    "Social History": "",
    "Family History": [],
    "Document Text": [],
    "Providers": [""],
    "Organization": "",
    "Orders": [],
    "Patient": {
      "First Name": "",
      "Last Name": "",
      "Birth Date": "",
      "Gender": "",
      "Phone": "",
      "Email": "",
      "Address": ""
    }
  },
  "section_header": "",
  "section_date": "",
  "section_note_id": 0,
  "section_note_type": ""
}

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 to retrieve the same summary more than 30 times

Step 6. 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

post

Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata

Body

Push structured note data for CDA conversion and storage. Each summary item must include either patient_id or patient_metadata, and either summary_id or summary_edited.

user_api_emailstringRequired

User's API email

Example: [email protected]

tokenstringRequired

OAuth token obtained from get-token route

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

testbooleanOptional

Flag to indicate if this is a test request

Default: false

Responses

200

All pushed documents completed successfully

application/json

All pushed documents completed successfully

statusstring · enumOptionalPossible values:

status_codeinteger · enumOptionalPossible values:

conversation_idstringOptional

Unique identifier associated with the request

processingboolean · enumOptionalPossible values:

timestampstring · date-timeOptional

UTC timestamp for when the response was generated

messagestringOptional

Combined message across pushed note results

207

Some pushed documents completed successfully while others failed

application/json

400

Validation failure

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

post

/push-document

POST /push-document HTTP/1.1
Host: api.abstractive.ai
Content-Type: application/json
Accept: */*
Content-Length: 800

{
  "user_api_email": "[email protected]",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "test": false,
  "author": {
    "given_name": "Alex",
    "family_name": "Smith",
    "authored_on": "20260317",
    "npi": "1234567890",
    "specialty": "Internal Medicine"
  },
  "summaries": [
    {
      "summary_id": "summary-123",
      "patient_id": "patient123",
      "patient_metadata": {
        "addresses": [
          {
            "street_address_line": "1100 Test Street",
            "city": "Helena",
            "state": "AL",
            "postal_code": "35080",
            "country": "US"
          }
        ],
        "demographics": {
          "given_name": "Nwhinone",
          "family_name": "Nwhinzzztestpatient",
          "administrative_gender_code": "M",
          "birth_time": "19810101",
          "email": "[email protected]",
          "phone_number": "205-111-1111"
        }
      },
      "summary_assessment": "Follow-up note for chronic condition management.",
      "summary_edited": "Patient is stable on current medication regimen.",
      "summary_format": "text"
    }
  ]
}

{
  "status": "success",
  "status_code": 200,
  "conversation_id": "text",
  "processing": false,
  "timestamp": "2026-03-18T18:13:51.445Z",
  "message": "text",
  "results": [
    {
      "status": "success",
      "status_code": 200,
      "processing": false,
      "timestamp": "2026-03-18T18:13:51.445Z",
      "patient_id": "patient123",
      "document_count": 1,
      "note_id": "note-123",
      "summary_id": "summary-123",
      "message": "Pushed document successfully",
      "failure_reason": "text",
      "error": "text"
    }
  ]
}

Important Notes

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

Last updated 1 day ago

hashtagStep 1: Get Token

hashtagImportant Notes

hashtagStep 2. Search for a Patient (Optional)

hashtagSearch Patient

hashtagTest Patient Example

hashtagImportant Notes

hashtagRetrieve Patient Documents

hashtagURL Retrieval and Directory Structure

hashtagStructure of the zipped folder

hashtagOutput Document Information

hashtagImportant Notes

hashtagStep 3. Bulk Document Upload (Optional)

hashtagInput Parameters

hashtagStep 4. Request a Summary (From Patient Search and/or From Bulk Upload Documents)

hashtagInput Parameters

hashtagImportant Notes

hashtagStep 5. Retrieve a Summary

hashtagInput Parameters

hashtagFormat of cleaned_text_notes/

hashtagAI Summary Format

hashtagImportant Notes

hashtagStep 6. Push Back Treatment Documents

hashtagPush a document

hashtagImportant Notes

Step 1: Get Token

Important Notes

Step 2. Search for a Patient (Optional)

Search Patient

Test Patient Example

Important Notes

Retrieve Patient Documents

URL Retrieval and Directory Structure

Structure of the zipped folder

Output Document Information

Important Notes

Step 3. Bulk Document Upload (Optional)

Input Parameters

Step 4. Request a Summary (From Patient Search and/or From Bulk Upload Documents)

Input Parameters

Important Notes

Step 5. Retrieve a Summary

Input Parameters

Format of cleaned_text_notes/

AI Summary Format

Important Notes

Step 6. Push Back Treatment Documents

Push a document

Important Notes