Skip to navigation
NLP API ReferenceTasks

Submit files containing documents for processing

Submit files containing documents, starting a task that will process them.

Authentication

Authorizationstring

This API uses our API key HMAC authentication, with empty credential scope.

Access keys and secret access keys will be provided by Emtelligent; contact us for key management. Keys will consist of only printable ASCII characters, and leading and trailing whitespace is insignificant.

OR
x-api-keystring

API keys will be provided by Emtelligent; contact us for key management. Keys will consist of only printable ASCII characters, and leading and trailing whitespace is insignificant.

Headers

AuthorizationstringRequired
Authentication information.
HoststringRequired
Host of server.
X-Auth-DatestringRequired
Date and time of request.

Query parameters

callbackstringOptional

URL to call on task completion (either success or failure). Will be given the task ID as a query parameter ‘id’. Any other information or results must be fetched through other API calls.

featureslist of enumsOptional
List of features to enable, comma separated. If not given, a default set of features will be enabled that depends on the NLP API deployment configuration. This set of features is chosen during NLP API deployment. For the list of default features for your API server please contact Emtelligent.

Request

Input files as a mime multipart HTTP body.

Each input file within the multipart body must have part name ‘file’ (name="file" in Content-Disposition). Filenames (filename= in Content-Disposition) are not required but can be sent if convenient. Each input file contains either one document for processing, or JSON giving a list of documents.

Document metadata is given through mime multipart headers (multipart allows attaching headers to each part), and in the case of a JSON file also fields within the file. ID must be given for each document. Category and subcategory may optionally be given for each document; if not given, then they will be inferred and the inferred category and subcategory will be provided in results. See below for details.

All text must be encoded in UTF-8. Each file (multipart part) can be one of the following:

  • text/plain: Plain report text for a single document. The document ID, type, category, and subcategory are read from the part headers for the file.
  • application/json: Structured JSON with a list of documents, in the JSON input format. Document ID is read from the field on each JSON document object. Type, category, and subcategory may be given in part headers and/or the fields on the JSON document objects. If a value is given as both a part header and a JSON field, the latter overrides the former.
  • application/pdf: Report text for a single document as a PDF (text or image). The document ID, type, category, and subcategory are read from the part headers for the file.

Part headers

All multipart parts carry one of these content types: text/plain; charset=utf-8, application/json; charset=utf-8, application/pdf.

id part header. Identifier for a document. Must be unique within each submission, and will indicate which result document corresponds to which input document. This is a required argument.

type part header. Type of document. Case insensitive. Use ‘plain’ if unsure. This is optional and is considered deprecated: it will be removed in a future version.

Allowed values: default, plain.

category part header. The Emtelligent top level document category. Optional. Case insensitive. If given must be one of the values listed.

Allowed values: Radiology, Clinical, Surgical, Pathology, Gastroenterology, Orthopedic, Cardiology, Molecular.

subcategory part header. The Emtelligent lower level document subcategory. Optional. Case insensitive. If given must be one of the values listed. The allowed subcategories by top level category:

  • Radiology
    • generic
    • CR
    • CT
    • MG
    • MR
    • NM
    • PT
    • RF
    • US
    • XA
  • Clinical
    • generic
    • Admission Note
    • Discharge Summary
    • ER Visit
    • History & Physical
    • Office Visit
    • Pre-op
    • Consult request
    • SOAP Note
    • Nutrition Assessment
    • CCD
    • Lab results
  • Surgical
    • generic
    • Operative Note
    • Clinic Note
  • Pathology
    • generic
    • Surgical Pathology
    • Molecular Pathology
    • Hematopathology
    • Cytopathology
    • Dermatopathology
  • Gastroenterology
    • generic
    • Endoscopy
    • Endoscopic Ultrasound
    • ERCP
    • VCE
    • Ostomy Exam
    • Pouch Exam
  • Orthopedic
    • generic
    • Consult note
  • Cardiology
    • generic
    • ECG
    • ETT
    • Echocardiogram
    • Holter
    • EP Study
    • Angiogram
  • Molecular
    • generic

process_with_section_labels part header. If this field is given for a document, the report will be processed as a single report section, without any attempt to parse sections from the text. This is an optional argument and if omitted then the document will be processed as a full report.

The value of the field should be one or more section labels, separated by double colon (::). If one section label is given, it is the label of the section. If more than one is given, they specify nested sections containing the single section to be processed, from outermost to innermost with the innermost being the label of the section to be processed.

Each section label will be handled the same way it would had it been identified as a section header in normal report parsing.

filelist of stringsRequired

Response

Accepted, returning task information.
idstring
Unique ID for a task. Use it to check task status or retrieve results.

Errors

400
Bad Request Error
401
Unauthorized Error
500
Internal Server Error
503
Service Unavailable Error