# API Reference Docs {% hint style="info" %} All requests need to route to `https://api.abstractive.ai` base URL {% endhint %} ## 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.
DescriptionRetrieves an authentication token
MethodPOST
Routehttps://api.abstractive.ai/get-token
Success Status Code200
LimitationsAccess token valid for 60 minutes
Avg. Response Time (Success)~1 second
## POST /get-token > Authenticates user credentials and returns an access token ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/get-token":{"post":{"tags":["get-token"],"description":"Authenticates user credentials and returns an access token","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}}}}},"components":{"schemas":{"TokenResponse":{"description":"Success token response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"access_token":{"type":"string","description":"OAuth token for user"}}},"TokenFailure":{"description":"Failed token response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"Type of error"},"missing_fields":{"type":"array","description":"Missing required fields (if validation error)","items":{"type":"string"}}}},"TokenRequest":{"description":"Input object to obtain token","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"username_api":{"type":"string","description":"User's API username. Optional, defaults to user_api_email"},"user_api_password":{"type":"string","description":"User's API password"}},"required":["user_api_email","user_api_password"]}}}} ``` #### Important Notes {% hint style="info" %} * Only get a token when necessary * Make sure you have an active token before requesting a summary {% endhint %} ## 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
DescriptionProvide a set of patient metadata to kick off an asynchronous Health Information Exchange (HIE) search.
MethodPOST
Routehttps://api.abstractive.ai/search-patient
Success Status Code202
LimitationsWe will take up to 5 patients per request.
Avg. Response Time (Success)3 - 5 seconds (time to 202 response)
## POST /search-patient > Searches for patients across multiple EHR systems based on provided metadata ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/search-patient":{"post":{"tags":["search-patient"],"description":"Searches for patients across multiple EHR systems based on provided metadata","responses":{"202":{"description":"At least one patient was successfully queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchAccepted"}}}},"400":{"description":"Request validation failed or all patient searches failed with client-side errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchAuthenticationFailure"}}}},"500":{"description":"Internal server error or all patient searches failed with server-side errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientSearchRequest"}}}}}}},"components":{"schemas":{"PatientSearchAccepted":{"description":"Request accepted. At least one patient search was queued. Top-level status is success if all items queued successfully and partial_success if some items failed immediately.","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success","partial_success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request. Use this to chain subsequent retrieval and summarization API calls."},"processing":{"type":"boolean","description":"Whether any patient search is still processing","enum":[true]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"results":{"type":"array","description":"Array of per-patient search results. Each item reports its own status, processing state, patient identifiers, and any immediate failure detail.","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchResult":{"description":"Result for a single patient search. Successful items include processing=true and patient identifiers. Failed items include error and a 4xx/5xx status_code.","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's search","enum":["success","failure"]},"status_code":{"type":"integer","description":"HTTP status code for this patient result"},"patient_id":{"type":"string","description":"Unique patient identifier assigned or matched by Abstractive Health for this organization"},"pid":{"type":"string","description":"Internal patient identifier. Matches patient_id when available."},"given_name":{"type":"string","description":"Patient given name echoed from the request"},"family_name":{"type":"string","description":"Patient family name echoed from the request"},"birth_time":{"type":"string","description":"Patient birth date echoed from the request in YYYYMMDD format"},"administrative_gender_code":{"type":"string","description":"Patient gender code echoed from the request","enum":["M","F"]},"processing":{"type":"boolean","description":"Whether this patient is currently being processed"},"error":{"type":"string","description":"Error message for failed patient searches"}}},"PatientSearchValidationFailure":{"description":"Patient search validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}},"invalid_fields":{"type":"object","description":"Invalid fields keyed by field name with validation messages","additionalProperties":{"type":"string"}},"results":{"type":"array","description":"Array of search results for each patient","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchAuthenticationFailure":{"description":"Patient search authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"}}},"PatientSearchInternalServerError":{"description":"Patient search internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"failure_reason":{"type":"string","description":"reason for failure"},"error_details":{"type":"string","description":"Additional internal error details when available"},"results":{"type":"array","description":"Array of search results for each patient","items":{"$ref":"#/components/schemas/PatientSearchResult"}}}},"PatientSearchRequest":{"description":"Patient Search Input","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"api_code":{"type":"string","description":"Optional team API code resolved for the authenticated organization. Used to associate the patient search with a team."},"patient_metadata":{"type":"array","description":"List of patients and their metadata. The API also accepts a single patient metadata object in this same shape. The public documentation recommends sending at most 5 patients per request.","items":{"$ref":"#/components/schemas/PatientSearchMetadata"}},"robustness":{"description":"Overall search robustness level. Accepts Optimized, Thorough, Robust, or an integer from 1 to 100.","type":"string"},"summarize":{"type":"boolean","description":"When true, the downstream patient search pipeline also requests summarization work after the patient search is kicked off.","default":false},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","patient_metadata"]},"PatientSearchMetadata":{"description":"Patient metadata used for patient search. Demographics are required. Addresses are optional but materially improve matching quality.","type":"object","properties":{"addresses":{"type":"array","description":"List of patient addresses. If provided, each item must include all address fields below.","items":{"$ref":"#/components/schemas/PatientSearchAddress"}},"demographics":{"$ref":"#/components/schemas/PatientSearchDemographics"}},"required":["demographics"]},"PatientSearchAddress":{"description":"Patient address used for patient matching. Include places where the patient has lived throughout their life when available.","type":"object","properties":{"street_address_line":{"type":"string","description":"Street address where the patient lived or currently lives"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State or province code, typically a two-letter U.S. abbreviation such as NY"},"postal_code":{"type":"string","description":"Postal or ZIP code"},"country":{"type":"string","description":"Country code for the address. Current records are limited to the United States."}},"required":["street_address_line","city","state","postal_code","country"]},"PatientSearchDemographics":{"description":"Patient demographic details","type":"object","properties":{"given_name":{"type":"string","description":"Patient's given name. Include middle names here when available."},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient gender code","enum":["M","F"]},"birth_time":{"type":"string","description":"Patient birth date in YYYYMMDD format","pattern":"^\\d{8}$"},"email":{"type":"string","description":"Patient's email address"},"phone_number":{"type":"string","description":"Patient phone number, typically in XXX-XXX-XXXX format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}}} ``` #### 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: ```json // Patient search with test patient example { "user_api_email": "user@example.com", "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 {% hint style="info" %} * 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 {% endhint %} ### Retrieve Patient Documents
DescriptionAfter a few minutes, attempt retrieval of the patient documents in the requested format.
MethodPOST
Routehttps://api.abstractive.ai/retrieve-patient-docs
Success Status Code200
Avg. Response Time (Success)Varies based on robustness score from /search-patient:
• 20 → 180 seconds
• 70 → 240 seconds
• 100 → 480 seconds
## POST /retrieve-patient-docs > Retrieves uploaded and processed patient documents as a presigned S3 URL ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/retrieve-patient-docs":{"post":{"tags":["retrieve-patient-docs"],"description":"Retrieves uploaded and processed patient documents as a presigned S3 URL","responses":{"200":{"description":"All documents successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalSuccess"}}}},"202":{"description":"Documents still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalProcessing"}}}},"207":{"description":"Some documents retrieved, others failed or processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalPartialSuccess"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalAuthenticationFailure"}}}},"404":{"description":"Conversation_id not recognized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalNotFoundFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRetrievalRequest"}}}}}}},"components":{"schemas":{"SearchRetrievalSuccess":{"description":"Successful document retrieval response","type":"object","properties":{"status":{"type":"string","description":"Overall status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResultSuccess"}}}},"PatientDocumentResultSuccess":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"}}},"SearchRetrievalProcessing":{"description":"Processing status for document retrieval","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["processing"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[true]},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResultProcessing"}}}},"PatientDocumentResultProcessing":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"}}},"SearchRetrievalPartialSuccess":{"description":"Partial success - some patients succeeded, others failed or processing","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["partial_success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[207]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"processing":{"type":"boolean","description":"whether processing is occurring"},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"oneOf":[{"$ref":"#/components/schemas/PatientDocumentResultPartialSuccess"},{"$ref":"#/components/schemas/PatientDocumentResultProcessing"},{"$ref":"#/components/schemas/PatientDocumentResultFailure"}]}}}},"PatientDocumentResultPartialSuccess":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"PatientDocumentResultFailure":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"SearchRetrievalValidationFailure":{"description":"Search retrieval validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["ValidationError"]},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}},"results":{"type":"array","description":"Array of retrieval results for each patient","items":{"$ref":"#/components/schemas/PatientDocumentResult"}}}},"PatientDocumentResult":{"description":"Document retrieval result for a single patient","type":"object","properties":{"status":{"type":"string","description":"Status of this patient's document retrieval","enum":["success","failure","processing"]},"status_code":{"type":"integer","description":"HTTP status code for this patient"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL of processed results (only present on success)"},"expires_in":{"type":"integer","description":"URL expiration time in seconds (only present on success)","enum":[3600]},"processing":{"type":"boolean","description":"Whether this patient's documents are still processing"},"message":{"type":"string","description":"Processing status message (only present when processing)"},"failure_reason":{"type":"string","description":"Reason for failure (only present on failure)"},"error":{"type":"string","description":"Error message if status is failure"}}},"SearchRetrievalAuthenticationFailure":{"description":"Search retrieval authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["AuthenticationError"]}}},"SearchRetrievalNotFoundFailure":{"description":"Search retrieval not found failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[404]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["NotFoundError"]}}},"SearchRetrievalInternalServerError":{"description":"Search retrieval internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"patient ID if available"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["InternalServerError"]}}},"SearchRetrievalRequest":{"description":"Input object to retrieve patient documents","type":"object","properties":{"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"patient_id":{"description":"Unique patient identifier (single ID or array of IDs)","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["conversation_id","user_api_email","token","patient_id"]}}}} ``` #### 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](https://build.fhir.org/) 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. ```json # 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 {% hint style="info" %} Mimetype of the response will always be JSON even if CDA is requested. {% endhint %} ## 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.
DescriptionUpload the documents you want to use to generate a medical summary or include with the documents you retrieved from \search-patient in Step 2
MethodPOST
Routehttps://api.abstractive.ai/upload-patient-docs
Success Status Code200 or 202
Avg. Response Time (Success)180 - 300 seconds
#### Input Parameters ## POST /upload-patient-docs > 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 ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/upload-patient-docs":{"post":{"tags":["upload-patient-docs"],"description":"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","responses":{"200":{"description":"Documents successfully uploaded and processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsSuccess"}}}},"202":{"description":"Documents uploaded and processing started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsSuccess"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsAuthenticationFailure"}}}},"404":{"description":"Patient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsNotFoundFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPatientDocsRequest"}}}}}}},"components":{"schemas":{"UploadPatientDocsSuccess":{"description":"Successful document upload","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200,202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID"},"document_count":{"type":"integer","description":"Number of files successfully processed"},"processing":{"type":"boolean","description":"Whether processing is occurring"}}},"UploadPatientDocsValidationFailure":{"description":"Upload patient docs validation failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[400]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["ValidationError"]},"missing_fields":{"type":"array","description":"missing required fields","items":{"type":"string"}}}},"UploadPatientDocsAuthenticationFailure":{"description":"Upload patient docs authentication failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[401]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["AuthenticationError"]}}},"UploadPatientDocsNotFoundFailure":{"description":"Upload patient docs not found failure","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[404]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["NotFoundError"]}}},"UploadPatientDocsInternalServerError":{"description":"Upload patient docs internal server error","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[500]},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Patient ID if available"},"failure_reason":{"type":"string","description":"Reason for failure"},"error_type":{"type":"string","description":"type of error","enum":["InternalServerError"]}}},"UploadPatientDocsRequest":{"description":"Upload Patient Documents Input - supports two modes (existing patient or new patient with metadata)","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"conversation_id":{"type":"string","description":"Optional conversation ID. If not provided, one will be generated"},"patient_id":{"type":"string","description":"Existing patient ID (for Option 1)"},"patient_metadata":{"type":"object","description":"Patient metadata (for Option 2 - new patients)","properties":{"addresses":{"type":"array","description":"List of patient addresses","items":{"type":"object","properties":{"street_address_line":{"type":"string","description":"Street address"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"2-letter capitalized state code"},"postal_code":{"type":"string","description":"5-digit postal code"},"country":{"type":"string","description":"3-letter capitalized country code"}}}},"demographics":{"type":"object","description":"Patient demographic details","properties":{"given_name":{"type":"string","description":"Patient's given name"},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient's gender code (M or F)"},"birth_time":{"type":"string","description":"Patient's birth date in YYYYMMDD format"},"phone_number":{"type":"string","description":"Patient's phone number in nnn-nnn-nnnn format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}},"files":{"type":"object","description":"Base64 encoded files organized by type","properties":{"non_text":{"type":"array","items":{"type":"string","description":"Base64 encoded PDF files"}},"cda":{"type":"array","items":{"type":"string","description":"Base64 encoded CDA files"}},"fhir":{"type":"array","items":{"type":"string","description":"Base64 encoded FHIR files"}}}}},"required":["user_api_email","token","files"]}}}} ``` {% hint style="info" %} 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. {% endhint %} ## 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.
DescriptionGenerate 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.
MethodPOST
Routehttps://api.abstractive.ai/request-summary
Success Status Code202
Avg. Response Time (Success)3 - 5 seconds
#### Input Parameters ## POST /request-summary > Requests a summary of an entire conversation containing patient documents ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/request-summary":{"post":{"tags":["request-summary"],"description":"Requests a summary of an entire conversation containing patient documents","responses":{"202":{"description":"Processing started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryProcessing"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestSummaryRequest"}}}}}}},"components":{"schemas":{"RequestSummaryProcessing":{"description":"Processing status for summary request","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[true]}}},"RequestSummaryFailure":{"description":"Failed summary request","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error"},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"missing_fields":{"type":"array","description":"missing required fields (if validation error)","items":{"type":"string"}}}},"RequestSummaryRequest":{"description":"Input object to request a conversation summary","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"patient_id":{"type":"string","description":"Unique patient identifier"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","patient_id","conversation_id"]}}}} ``` #### Important Notes {% hint style="info" %} Limit summary requests to 1 every 30 seconds. {% endhint %} ## Step 5. Retrieve a Summary
DescriptionRetrieve the summary after requesting to create one through /request-summary API endpoint
MethodPOST
Routehttps://api.abstractive.ai/retrieve-summary
Success Status Code200
Avg. Response Time (Success)60 - 180 seconds
#### Input Parameters ## POST /retrieve-summary > Retrieves a completed conversation summary ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/retrieve-summary":{"post":{"tags":["retrieve-summary"],"description":"Retrieves a completed conversation summary","responses":{"200":{"description":"Summary ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummarySuccess"}}}},"202":{"description":"Summary still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryProcessing"}}}},"400":{"description":"Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"404":{"description":"Conversation_id not recognized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryFailure"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveSummaryRequest"}}}}}}},"components":{"schemas":{"RetrieveSummarySuccess":{"description":"Successful summary retrieval response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["success"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[200]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"url":{"type":"string","description":"Presigned URL to download summary"},"expires_in":{"type":"integer","description":"URL expiration time in seconds","enum":[3600]},"posted":{"type":"boolean","description":"Whether URL is posted","enum":[true]},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[false]}}},"RetrieveSummaryProcessing":{"description":"Processing status for summary retrieval","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["processing"]},"status_code":{"type":"integer","description":"HTTP status code","enum":[202]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"message":{"type":"string","description":"Description of processing status"},"posted":{"type":"boolean","description":"Whether URL is posted","enum":[false]},"processing":{"type":"boolean","description":"Whether processing is occurring","enum":[true]}}},"RetrieveSummaryFailure":{"description":"Failed summary retrieval response","type":"object","properties":{"status":{"type":"string","description":"Status of the request","enum":["failure"]},"status_code":{"type":"integer","description":"HTTP status code"},"failure_reason":{"type":"string","description":"reason for failure"},"error_type":{"type":"string","description":"type of error"},"conversation_id":{"type":"string","description":"unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier if applicable"},"processing":{"type":"boolean","description":"whether processing is occurring","enum":[false]},"missing_fields":{"type":"array","description":"missing required fields (if validation error)","items":{"type":"string"}},"posted":{"type":"boolean","description":"whether url is posted","enum":[false]}}},"RetrieveSummaryRequest":{"description":"Input object to retrieve a generated conversation summary","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"patient_id":{"type":"string","description":"Unique patient identifier"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false}},"required":["user_api_email","token","conversation_id","patient_id"]}}}} ``` #### **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: ```json { "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 {% hint style="info" %} * You can retrieve a summary every 15 seconds. * We recommend not to retrieve the same summary more than 30 times {% endhint %} ## 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 NameDescription
DescriptionSend a new clinical treatment document to Abstractive Health
MethodPOST
Routehttps://api.abstractive.ai/push-document
Avg. Response Time (Success)10 - 15 seconds
## POST /push-document > Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata ```json {"openapi":"3.1.1","info":{"title":"Abstractive Health API","version":"2.0"},"servers":[{"url":"https://api.abstractive.ai"}],"paths":{"/push-document":{"post":{"tags":["push-document"],"description":"Converts structured clinical note payloads into CDA documents and stores them for the specified patient or patient metadata","responses":{"200":{"description":"All pushed documents completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentSuccess"}}}},"207":{"description":"Some pushed documents completed successfully while others failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentPartialSuccess"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentValidationFailure"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentAuthenticationFailure"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentInternalServerError"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDocumentRequest"}}}}}}},"components":{"schemas":{"PushDocumentSuccess":{"description":"All pushed documents completed successfully","type":"object","properties":{"status":{"type":"string","enum":["success"]},"status_code":{"type":"integer","enum":[200]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"message":{"type":"string","description":"Combined message across pushed note results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PushDocumentResult"}}}},"PushDocumentResult":{"description":"Result for a single pushed note","type":"object","properties":{"status":{"type":"string","enum":["success","failure"]},"status_code":{"type":"integer","description":"HTTP-style status code for this item"},"processing":{"type":"boolean","description":"Whether this pushed note is still processing"},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the result was generated"},"patient_id":{"type":"string","description":"Patient identifier associated with the pushed note"},"document_count":{"type":"integer","description":"Number of documents created for this item"},"note_id":{"type":"string","description":"Unique identifier for the pushed note"},"summary_id":{"type":"string","description":"Summary identifier associated with the pushed note"},"message":{"type":"string","description":"Result message"},"failure_reason":{"type":"string","description":"Failure reason for failed items when available"},"error":{"type":"string","description":"Failure detail for failed items when available"}}},"PushDocumentPartialSuccess":{"description":"Some pushed documents completed successfully while others failed","type":"object","properties":{"status":{"type":"string","enum":["partial_success"]},"status_code":{"type":"integer","enum":[207]},"conversation_id":{"type":"string","description":"Unique identifier associated with the request"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp for when the response was generated"},"message":{"type":"string","description":"Combined message across pushed note results"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PushDocumentResult"}}}},"PushDocumentValidationFailure":{"description":"Push document validation failure","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[400]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"invalid_fields":{"type":"object","additionalProperties":{"type":"string"}}}},"PushDocumentAuthenticationFailure":{"description":"Push document authentication failure","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[401]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"}}},"PushDocumentInternalServerError":{"description":"Push document internal server error","type":"object","properties":{"status":{"type":"string","enum":["failure"]},"status_code":{"type":"integer","enum":[500]},"conversation_id":{"type":"string"},"processing":{"type":"boolean","enum":[false]},"timestamp":{"type":"string","format":"date-time"},"failure_reason":{"type":"string"},"error_details":{"type":"string"}}},"PushDocumentRequest":{"description":"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.","type":"object","properties":{"user_api_email":{"type":"string","description":"User's API email"},"token":{"type":"string","description":"OAuth token obtained from get-token route"},"test":{"type":"boolean","description":"Flag to indicate if this is a test request","default":false},"author":{"$ref":"#/components/schemas/PushDocumentAuthor"},"summaries":{"type":"array","description":"One or more summaries to push as structured notes","items":{"$ref":"#/components/schemas/PushDocumentSummary"},"minItems":1}},"required":["user_api_email","token","author","summaries"]},"PushDocumentAuthor":{"description":"Provider metadata attached to the pushed note","type":"object","properties":{"given_name":{"type":"string","description":"First name of the authoring clinician"},"family_name":{"type":"string","description":"Last name of the authoring clinician"},"authored_on":{"type":"string","description":"Date the treatment summary was authored. The public documentation expects YYYYMMDD format."},"npi":{"type":"string","description":"10-digit National Provider Identifier of the authoring clinician. Do not pass an organization NPI.","pattern":"^\\d{10}$"},"specialty":{"type":"string","description":"Medical specialty of the authoring clinician"}},"required":["given_name","family_name","authored_on","npi","specialty"]},"PushDocumentSummary":{"description":"Summary payload for a single pushed note","type":"object","properties":{"summary_id":{"type":"string","description":"Existing summary identifier to associate with the pushed note"},"patient_id":{"type":"string","description":"Existing patient identifier generated by Abstractive Health during patient search or summarization. If provided, other patient demographic fields are optional."},"patient_metadata":{"allOf":[{"$ref":"#/components/schemas/PatientSearchMetadata"}],"description":"Patient demographics and optional addresses used to resolve or create a patient when patient_id is not supplied."},"summary_assessment":{"type":"string","description":"Plain-text narrative describing the clinical context or assessment reflected by the summary, such as diagnoses, treatment rationale, visit purpose, or key findings."},"summary_edited":{"type":"string","description":"Final version of the medical summary after any manual edits. This becomes the official treatment note pushed into the exchange. Required when summary_id is not supplied."},"summary_format":{"type":"string","description":"Format of summary_edited. Use json when submitting an edited structured summary payload previously returned by Abstractive Health.","enum":["text","json"],"default":"text"}},"required":["summary_assessment"]},"PatientSearchMetadata":{"description":"Patient metadata used for patient search. Demographics are required. Addresses are optional but materially improve matching quality.","type":"object","properties":{"addresses":{"type":"array","description":"List of patient addresses. If provided, each item must include all address fields below.","items":{"$ref":"#/components/schemas/PatientSearchAddress"}},"demographics":{"$ref":"#/components/schemas/PatientSearchDemographics"}},"required":["demographics"]},"PatientSearchAddress":{"description":"Patient address used for patient matching. Include places where the patient has lived throughout their life when available.","type":"object","properties":{"street_address_line":{"type":"string","description":"Street address where the patient lived or currently lives"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State or province code, typically a two-letter U.S. abbreviation such as NY"},"postal_code":{"type":"string","description":"Postal or ZIP code"},"country":{"type":"string","description":"Country code for the address. Current records are limited to the United States."}},"required":["street_address_line","city","state","postal_code","country"]},"PatientSearchDemographics":{"description":"Patient demographic details","type":"object","properties":{"given_name":{"type":"string","description":"Patient's given name. Include middle names here when available."},"family_name":{"type":"string","description":"Patient's family name"},"administrative_gender_code":{"type":"string","description":"Patient gender code","enum":["M","F"]},"birth_time":{"type":"string","description":"Patient birth date in YYYYMMDD format","pattern":"^\\d{8}$"},"email":{"type":"string","description":"Patient's email address"},"phone_number":{"type":"string","description":"Patient phone number, typically in XXX-XXX-XXXX format"}},"required":["given_name","family_name","administrative_gender_code","birth_time"]}}}} ``` #### Important Notes {% hint style="info" %} * You are required to return a clinical treatment document for every patient retrieved from Carequality® within 7 days. {% endhint %}