--- updatedAt: 2026-07-31T18:03:06.000Z agentTools: projectIndex: https://docs.sensible.so/llms.txt --- # Retrieve extraction by ID Use this endpoint in conjunction with asynchronous extraction requests to retrieve your results. You can also use this endpoint to retrieve the results for documents extractions from the synchronous /extract endpoint. To poll extraction status, check the `status` field in this endpoint's response. When the extraction completes, the returned status is `COMPLETE` and the response includes results in the `parsed_document` field. For fields in the extraction for which Sensible couldn't find a value, Sensible returns null. # OpenAPI definition ```json { "openapi": "3.0.3", "servers": [ { "url": "https://api.sensible.so/v0", "description": "Production server (uses live data)" } ], "info": { "title": "Extraction", "version": "0.0.0", "license": { "name": "Sensible API", "url": "https://www.TBD.org/licenses/LICENSE-2.0.html" }, "description": "Extract structured data from documents with the Sensible API." }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Retrieve extractions", "description": "Retrieve data extracted asynchronously from documents" } ], "paths": { "/documents/{id}": { "get": { "operationId": "retrieving-results", "summary": "Retrieve extraction by ID", "description": "Use this endpoint in conjunction with asynchronous extraction requests to retrieve your results.\nYou can also use this endpoint to retrieve the results for documents extractions from the synchronous /extract endpoint.\nTo poll extraction status, check the `status` field in this endpoint's response.\nWhen the extraction completes, the returned status is `COMPLETE` and the response includes results in the\n`parsed_document` field. For fields in the extraction for which Sensible couldn't find a value, Sensible returns null.\n", "parameters": [ { "$ref": "#/components/parameters/id" } ], "tags": [ "Retrieve extractions" ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ExtractionSingleRetrievalResponse" }, { "$ref": "#/components/schemas/ExtractionPortfolioRetrievalResponse" } ] } } }, "description": "Returns the extraction." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "415": { "$ref": "#/components/responses/415" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "responses": { "400": { "description": "Bad Request. Sensible returns either a plain-text error message or a structured JSON error, depending on what caused the failure. For more information, see the two content types below.", "content": { "text/plain": { "schema": { "title": "Bad Request", "type": "string", "example": "Either a specific set of messages about fields in the request, or error messages like the following examples - To use the asynchronous flow you must have persistence enabled Specified document type does not exist Specified document type ${named type} does not exist No published configurations found for environment ${environment} Specified golden does not exist Must provide the Content-Type header Missing request body or body.document Could not determine the content type of the document Could not determine the content type of the document. Please check that the document was correctly encoded as Base64 This PDF is invalid. If you submitted this PDF using Base64 encoding, please check that the encoding is correct This PDF is password protected. Please resubmit with password protection disabled This PDF is empty This PDF exceeds the maximum dimensions for OCR of 17 x 17 inches This PDF exceeds the maximum size for OCR of 50MB No fingerprints match for this PDF and fingerprint_mode is set to strict Content type of ${found} does not match declared type of ${expected} The start date must be before the end date" } }, "application/json": { "schema": { "title": "Bad Request (structured)", "type": "object", "description": "Returned instead of plain text when the request fails path, query, or body validation (for example, a malformed id, an out-of-range limit, or an invalid field in a JSON body), and for the extract_from_url document-fetch failure. The shape of `context` varies by cause: for validation failures, it echoes the offending path and/or query values; for the extract_from_url failure, it's the extraction's current state.", "properties": { "message": { "type": "string", "description": "Human-readable summary of the error." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Present when the request failed path, query, or body validation -- one message per failing field, in the form '/ '." }, "context": { "type": "object", "additionalProperties": true, "description": "Additional context about the failure. See the parent description for how this varies by cause." } }, "required": [ "message" ] }, "examples": { "validationFailure": { "summary": "A path parameter failed validation", "value": { "message": "This request contains errors", "context": { "path": "/documents/{id}" }, "errors": [ "path/id should be valid version 4 UUID" ] } }, "documentFetchFailure": { "summary": "extract_from_url could not download the document", "value": { "message": "Transferring the file failed with 'Response code 404 (Not Found)'", "context": { "id": "e75dd6ee-ef8f-4960-8be2-ba22f8c398e3", "created": "2026-07-17T14:39:49.084Z", "completed": "2026-07-17T14:39:49.330Z", "status": "FAILED", "type": "1040s", "environment": "production", "errors": [], "error": "Response code 404:\n404: Not Found", "actor": "legacy: Sensible" } } } } } } }, "401": { "description": "Not authorized", "content": { "text/plain": { "schema": { "title": "Unauthorized", "type": "string", "example": "Unauthorized" } } } }, "415": { "description": "Unsupported Media Type", "content": { "text/plain": { "schema": { "title": "Unsupported Media Type", "type": "string", "description": "Unsupported file type. See https://docs.sensible.so/docs/file-types." } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "title": "Sensible encountered an unknown error", "type": "string", "example": "Sensible encountered an unknown error" } } } } }, "parameters": { "id": { "name": "id", "required": true, "in": "path", "description": "Unique ID for the extraction, used to retrieve the extraction.", "schema": { "$ref": "#/components/schemas/ExtractionId" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Sensible uses API keys to authenticate requests. Keep your API keys secure and do not share them publicly accessible areas such as GitHub, client-side code, etc. Authentication to the API is performed via Bearer Authentication. Provide your API key as the bearer auth value." } }, "schemas": { "ExtraDataRecord": { "type": "object", "description": "Extra data in the form of flat key/value pairs you attach to an asynchronous extraction endpoint request, for example, `{\"applicant_id\": \"A-123\", \"expected_premium\": 1250.00}`. Use this parameter to bring request-time context into a config's output so validations, postprocessors, and computed field methods can read it. For example, use it to validate extraction data against a dynamic external record. Has the following constraints: \n- Doesn't support synchronous extractions \n- Doesn't support nested objects and arrays \n- Values must be strings, numbers, booleans, or null \n- Extra data has a maximum size of 16 kB \n- Extra data isn't subject to custom data retention policies. Don't include sensitive information in it. \n\n Sensible persists the extra data and echoes it in responses and webhook deliveries. When you submit a [portfolio](https://docs.sensible.so/docs/portfolio) extraction with extra data, Sensible passes the same object to every document extracted from the portfolio. For more information, see the [Extra Data](https://docs.sensible.so/docs/extra-data) method.", "additionalProperties": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "number" }, { "type": "boolean" } ] }, "example": { "applicant_id": "A-123", "tenant": "acme", "premium_member": true, "year": 2025, "prior_decision": null } }, "Charged": { "type": "integer", "example": 1, "description": "The number of extractions charged to your account for this extraction ID." }, "Actor": { "type": "string", "description": "Best-effort label identifying the user or credential that initiated the extraction. For extractions you initiate in the Sensible app, the value is your account's email address. For extractions you initiate by using your API key, the value is `'api_key: '` if the key has a name, or `'api_key'` if unnamed. For extractions you initiate in the Sensible app while logged in with legacy credentials, the value is `'legacy: '`. Sensible omits this field for extractions you initiate with email processors.", "example": "api_key: my production key", "x-internal-note": "auth_token-initiated extractions are not a real code path; omitting the 'auth_token: ' case from the public description deliberately." }, "PostprocessorOutput": { "type": "object", "additionalProperties": true, "description": "A custom schema that you define using a [postprocessor](https://docs.sensible.so/docs/postprocessors). For example, define this output when your app consumes a pre-existing schema and you don't want to use Sensible's `parsed_document` schema." }, "ReviewStatuses": { "type": "string", "nullable": true, "enum": [ "NEEDS_REVIEW", "APPROVED", null, "REJECTED" ], "example": "NEEDS_REVIEW", "description": "The review status for each document in the portfolio, in order of their page ranges in the portfolio. For more information, see [Human review](https://docs.sensible.so/docs/human-review). Specify a webhook in the extraction request so that you can get a push notification when a review status in the reviewStatuses array changes to `APPROVED` or `REJECTED` for extractions that returned `NEEDS_REVIEW`." }, "ReviewStatus": { "type": "string", "enum": [ "NEEDS_REVIEW", "APPROVED", "REJECTED" ], "example": "NEEDS_REVIEW", "description": "The extraction's review status. For more information, see [Human review](https://docs.sensible.so/docs/human-review). Specify a webhook in the extraction request so that you can get a push notification when review status changes to `APPROVED` or `REJECTED` for extractions that returned `NEEDS_REVIEW`. Sensible omits this property from the extraction response if the extraction doesn't need review." }, "ContentTypeResponse": { "type": "string", "description": "The content type of the document.\n", "example": "image/png" }, "Coverage": { "type": "number", "description": "The coverage score measures how fully an extraction captured all your target data in the document. It's a percentage comparing non-null, [validated](https://docs.sensible.so/docs/validate-extractions) fields to total fields returned by a config for a document. For example, a coverage score of 70% for an extraction with no validation errors means that 30% of fields were null. For more information about scoring, see [Monitoring extraction metrics](https://docs.sensible.so/docs/metrics).", "example": 0.75 }, "EnvironmentResponse": { "description": "Name of the environment to which the configuration used by this extraction was published.", "example": "production", "type": "string", "enum": [ "production", "development" ] }, "ExtractionSyncResponse": { "type": "object", "x-internal-note": "version_id is returned by the backend but deliberately not documented publicly. batchId may also be returned, but is not a standard field on every extraction -- the backend only sets it for extractions created through the separate, undocumented /extract/batch/* API (src/api/extract/batch.ts), so it's absent for anything created through the endpoints in this spec.", "properties": { "id": { "$ref": "#/components/schemas/ExtractionId" }, "created": { "$ref": "#/components/schemas/ExtractionCreated" }, "type": { "$ref": "#/components/schemas/DocumentTypeName" }, "status": { "$ref": "#/components/schemas/ExtractionStatus" }, "completed": { "$ref": "#/components/schemas/ExtractionCompleted" }, "configuration": { "$ref": "#/components/schemas/ConfigurationName" }, "configuration_version": { "$ref": "#/components/schemas/ConfigurationVersion" }, "parsed_document": { "$ref": "#/components/schemas/ParsedDocument" }, "validations": { "$ref": "#/components/schemas/Validations" }, "file_metadata": { "$ref": "#/components/schemas/FileMetadata" }, "validation_summary": { "$ref": "#/components/schemas/ValidationsSummary" }, "errors": { "$ref": "#/components/schemas/Errors" }, "classification_summary": { "$ref": "#/components/schemas/ClassificationSummary" }, "page_count": { "type": "integer", "example": 100, "description": "Total number of pages in the document." }, "environment": { "$ref": "#/components/schemas/EnvironmentResponse" }, "document_name": { "$ref": "#/components/schemas/DocName" }, "content_type": { "$ref": "#/components/schemas/ContentTypeResponse" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "reviewStatus": { "$ref": "#/components/schemas/ReviewStatus" }, "charged": { "$ref": "#/components/schemas/Charged" }, "actor": { "$ref": "#/components/schemas/Actor" }, "postprocessorOutput": { "$ref": "#/components/schemas/PostprocessorOutput" } } }, "DocName": { "type": "string", "description": "If you specify the filename of the document using the `document_name` parameter, then Sensible displays the name in extraction history in the Sensible app and returns the name in the extraction response.", "example": "example.pdf" }, "ExtractionSingleRetrievalResponse": { "description": "Extracted document data from a single-document extraction.", "x-internal-note": "Extends ExtractionSyncResponse with fields populated during async processing: lifecycle timestamps (for example, uploaded, processing_started), signed download URLs (download_url, converted_url), and the top-level error message for failed extractions (error).", "allOf": [ { "$ref": "#/components/schemas/ExtractionSyncResponse" }, { "type": "object", "properties": { "uploaded": { "$ref": "#/components/schemas/ExtractionUploaded" }, "processing_started": { "$ref": "#/components/schemas/ExtractionProcessingStarted" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "error": { "$ref": "#/components/schemas/ExtractionErrorMessage" }, "download_url": { "$ref": "#/components/schemas/DownloadUrlDocument" }, "converted_url": { "$ref": "#/components/schemas/ConvertedUrlDocument" }, "extra_data": { "$ref": "#/components/schemas/ExtraDataRecord" } } } ] }, "ExtractionPortfolioRetrievalResponse": { "type": "object", "description": "Extracted data from a multiple-document extraction.", "x-internal-note": "batchId may be returned by the backend but is not a standard field on every extraction -- it's deliberately not documented publicly. The backend only sets it for extractions created through the separate, undocumented /extract/batch/* API (src/api/extract/batch.ts), so it's absent for anything created through the endpoints in this spec.", "properties": { "id": { "$ref": "#/components/schemas/ExtractionId" }, "created": { "$ref": "#/components/schemas/ExtractionCreated" }, "uploaded": { "$ref": "#/components/schemas/ExtractionUploaded" }, "processing_started": { "$ref": "#/components/schemas/ExtractionProcessingStarted" }, "completed": { "$ref": "#/components/schemas/ExtractionCompleted" }, "status": { "$ref": "#/components/schemas/ExtractionStatus" }, "error": { "$ref": "#/components/schemas/ExtractionErrorMessage" }, "types": { "$ref": "#/components/schemas/DocumentTypeNames" }, "segment_documents_with": { "$ref": "#/components/schemas/SegmentDocumentsWith" }, "webhook": { "$ref": "#/components/schemas/Webhook" }, "environment": { "$ref": "#/components/schemas/EnvironmentResponse" }, "document_name": { "$ref": "#/components/schemas/DocName" }, "page_count": { "$ref": "#/components/schemas/PageCountPortfolio" }, "validation_summary": { "$ref": "#/components/schemas/ValidationSummaryPortfolio" }, "download_url": { "$ref": "#/components/schemas/DownloadUrlDocument" }, "converted_url": { "$ref": "#/components/schemas/ConvertedUrlDocument" }, "content_type": { "$ref": "#/components/schemas/ContentTypeResponse" }, "coverage": { "$ref": "#/components/schemas/CoveragePortfolio" }, "charged": { "$ref": "#/components/schemas/Charged" }, "actor": { "$ref": "#/components/schemas/Actor" }, "reviewStatuses": { "$ref": "#/components/schemas/ReviewStatuses" }, "extra_data": { "$ref": "#/components/schemas/ExtraDataRecord" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInPortfolio" } } } }, "DocumentInPortfolio": { "type": "object", "properties": { "documentType": { "$ref": "#/components/schemas/DocumentTypeName" }, "configuration": { "$ref": "#/components/schemas/ConfigurationName" }, "startPage": { "type": "integer", "description": "Page in the portfolio on which the document for this extraction starts.", "example": 2 }, "endPage": { "type": "integer", "description": "Page in the portfolio on which this document for this extraction ends.", "example": 6 }, "configuration_version": { "$ref": "#/components/schemas/ConfigurationVersion" }, "output": { "type": "object", "description": "Extraction result for this document within the portfolio, containing the parsed data, validation results, errors, and metadata.", "x-internal-note": "Fields in this object use camelCase (parsedDocument, fileMetadata) rather than the snake_case convention used elsewhere in the public API -- this reflects the engine's internal naming.", "properties": { "parsedDocument": { "$ref": "#/components/schemas/ParsedDocument" }, "configuration": { "$ref": "#/components/schemas/ConfigurationName" }, "validations": { "$ref": "#/components/schemas/Validations" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "fileMetadata": { "$ref": "#/components/schemas/FileMetadata" }, "errors": { "$ref": "#/components/schemas/Errors" }, "needsReview": { "type": "boolean", "description": "Whether this specific document in the portfolio needs human review. Redundant with this document's entry in the top-level reviewStatuses array (true here corresponds to NEEDS_REVIEW there)." }, "classificationSummary": { "$ref": "#/components/schemas/ClassificationSummaryPortfolio" }, "postprocessorOutput": { "$ref": "#/components/schemas/PostprocessorOutput" }, "validation_summary": { "$ref": "#/components/schemas/ValidationsSummary" } } } } }, "PageCountPortfolio": { "type": "integer", "example": 100, "description": "Total number of pages in the portfolio." }, "ValidationSummaryPortfolio": { "type": "object", "description": "Summary for the whole portfolio file of the extracted fields that fail validation rules you write in the Sensible app.", "properties": { "fields": { "type": "integer", "description": "Number of fields specified to extract from all documents in the portfolio", "example": 6 }, "fields_present": { "type": "integer", "description": "Actual number of non-null fields extracted from the portfolio file", "example": 4 }, "errors": { "type": "number", "description": "Number of validation errors for all extractions in the portfolio", "example": 0 }, "warnings": { "type": "number", "description": "Number of validation warnings for all extractions in the portfolio", "example": 1 }, "skipped": { "type": "integer", "description": "Number of fields skipped for all extractions in the portfolio because a prerequisite field was null", "example": 1 } } }, "CoveragePortfolio": { "type": "number", "description": "The overall coverage score for the portfolio is the weighted average of the coverage scores of its subdocuments. For example, if subdocA has 1 non-null field out of 2 specified, and subdocB has 0 non-null fields out of 4 specified, the average is (1/2 + 0/4)/2 = 0.25 For more information about scoring, see [Monitoring extraction metrics](https://docs.sensible.so/docs/metrics).", "example": 0.6 }, "Classification": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/ConfigurationName" }, "fingerprints_present": { "type": "integer", "example": 1, "description": "The number of this config's fingerprints that Sensible found in the document." }, "fingerprints": { "type": "integer", "example": 1, "description": "The number of fingerprints defined in this config." }, "score": { "$ref": "#/components/schemas/Score" } } }, "ConfigurationName": { "type": "string", "description": "Name of the \"configuration\", a collection of SenseML queries for extracting document data.", "example": "config_for_x_company" }, "ConfigurationVersion": { "type": "string", "description": "Version number for the configuration.", "example": "N39i3ZvEbPCkcjOtYIAU1_ADSovnUC5I" }, "DocumentTypeName": { "description": "Unique user-friendly name for a document type", "example": "auto_insurance_quotes_all_carriers", "type": "string" }, "ClassificationSummary": { "type": "array", "description": "Metadata about how Sensible scores configs against the document to extract from. By default, Sensible compares all configs in the document type, then chooses the best extraction using fingerprints, scores, or a combination of the two. When two extractions tie by score and fingerprints, Sensible chooses the first configuration in alphabetic order. For more information, see [fingerprints](https://docs.sensible.so/docs/fingerprint#notes).", "items": { "$ref": "#/components/schemas/Classification" }, "example": [ { "configuration": "config_for_x_company", "fingerprints": 2, "fingerprints_present": 2, "score": { "value": 3, "fields_present": 4, "penalties": 0.5 } }, { "configuration": "acme_co", "fingerprints": 2, "fingerprints_present": 2, "score": { "value": 0, "fields_present": 2, "penalties": 1.5 } } ] }, "ClassificationSummaryPortfolio": { "type": "array", "description": "Metadata about how Sensible chose the config to use for this extraction. The summary doesn't return fingerprints information for portfolio extractions.", "items": { "$ref": "#/components/schemas/ClassificationPortfolio" }, "example": [ { "configuration": "config_for_x_company", "score": { "score": 3, "coverage": 0.75, "fieldsPresent": 4, "penalties": 0.5 } }, { "configuration": "acme_co", "score": { "score": 0, "coverage": 0.5, "fieldsPresent": 2, "penalties": 1.5 } } ] }, "ClassificationPortfolio": { "type": "object", "properties": { "configuration": { "$ref": "#/components/schemas/ConfigurationName" }, "score": { "$ref": "#/components/schemas/ScorePortfolio" } } }, "ScorePortfolio": { "type": "object", "description": "The score for the extraction, used to help choose the best extraction. Unlike the single-document extraction Score, includes a coverage field.", "x-internal-note": "Field names use camelCase (score, fieldsPresent) rather than the snake_case of the single-document Score schema (value, fields_present) — this reflects the engine's internal naming.", "properties": { "score": { "type": "number", "example": 31, "description": "The score total is fieldsPresent minus penalty points. In the absence of fingerprints, Sensible returns the extraction in the document type with the highest score. Equivalent to Score.value for single-document extractions." }, "coverage": { "type": "number", "example": 0.5740740740740741, "description": "The coverage score for this document, calculated the same way as the top-level Coverage schema." }, "fieldsPresent": { "type": "integer", "example": 31, "description": "Number of non-null fields Sensible extracted from this document using this config. Equivalent to Score.fields_present for single-document extractions." }, "penalties": { "type": "number", "example": 0, "description": "Errors are 1 penalty point and warnings are 0.5 points. See the validation_summary for a breakdown." } } }, "FileMetadata": { "type": "object", "description": "Metadata about the PDF file, for example author, authoring tool, and modified date.", "properties": { "metadata": { "type": "object", "description": "Raw metadata embedded in the PDF. Returned if available, without data normalization." }, "error": { "type": "string", "description": "Errors Sensible encountered when attempting to retrieve metadata", "example": "Error retrieving PDF metadata: Invalid PDF structure" }, "info": { "type": "object", "description": "Normalized metadata about the PDF, returned if available.", "properties": { "author": { "type": "string", "description": "The name of the person who created the document.", "example": "Jay S. Schiller" }, "title": { "type": "string", "description": "Title assigned to the PDF by the PDF producer.", "example": "file123" }, "creator": { "type": "string", "description": "If the document was converted to PDF from another format, the name of the application that created the original document from which it was converted.", "example": "macOS Version 11.2 (Build 20D64) Quartz PDFContext" }, "producer": { "type": "string", "description": "If the document was converted to PDF from another format, the name of the application that converted it to PDF", "example": "Preview" }, "creation_date": { "type": "string", "description": "File creation date", "example": "2022-08-02T18:09:31.000+00:00" }, "modification_date": { "type": "string", "description": "File modification date", "example": "2022-08-03T15:09:23.000+00:00" }, "error": { "type": "string", "description": "Errors Sensible encountered when attempting to retrieve metadata." } } } } }, "Score": { "type": "object", "description": "The score for the extraction, used to help choose the best extraction.", "properties": { "value": { "type": "number", "example": 17, "description": "The score total is fields_present minus penalty points. In the absence of fingerprints, Sensible returns the extraction in the document type with the highest score." }, "fields_present": { "type": "integer", "example": 17, "description": "Number of non-null fields Sensible extracted from the document using this config" }, "penalties": { "type": "number", "example": 1.5, "description": "Errors are 1 penalty point and warnings are 0.5 points. See the validation_summary for a breakdown." } } }, "ParsedDocument": { "description": "Data extracted from the document, structured as an array of fields.\nConfigure the verbosity parameter in the SenseML configuration to return\nextraction metadata, such as:\n- page numbers\n- the bounding polygons that\ndefine line coordinates\n- for text that Sensible OCR'd, confidence scores.\nFor more information, see [Verbosity](https://docs.sensible.so/docs/verbosity).\n", "type": "object", "example": { "policy_number": { "type": "number", "value": 123456789, "lines": [ { "text": "123456789", "page": 0, "boundingPolygon": [ { "x": 6.458, "y": 2.601 }, { "x": 7.354, "y": 2.601 }, { "x": 7.354, "y": 2.767 }, { "x": 6.458, "y": 2.767 } ] } ] }, "name_insured": { "type": "string", "value": "Petar Petrov", "lines": [ { "text": "Petar Petrov", "page": 0, "boundingPolygon": [ { "x": 1, "y": 5.515 }, { "x": 1.935, "y": 5.515 }, { "x": 1.935, "y": 5.674 }, { "x": 1, "y": 5.674 } ] } ] } } }, "Validation": { "type": "object", "properties": { "description": { "type": "string", "description": "Description of the validation", "example": "Dollar amount should be more than $100" }, "severity": { "type": "string", "enum": [ "error", "warning", "skipped" ], "example": "warning", "description": "Severity of the failing validation (error, warning, skipped)" }, "message": { "type": "string", "description": "Messages about why the validation failed", "example": "Missing prerequisites: broker.email" } } }, "Validations": { "description": "Which extracted fields failed validation rules you write in the Sensible app", "type": "array", "items": { "$ref": "#/components/schemas/Validation" }, "example": [ { "description": "Policy number must be 11 digits", "severity": "error" }, { "description": "Company email must be in format string@string", "severity": "skipped", "message": "Missing prerequisites - company_email" } ] }, "ValidationsSummary": { "type": "object", "description": "Summary of the extracted fields that fail validation rules you write in the Sensible app.", "properties": { "fields": { "type": "integer", "description": "Number of fields specified in the SenseML config to extract from the document", "example": 6 }, "fields_present": { "type": "integer", "description": "Actual number of non-null fields extracted from the document", "example": 4 }, "errors": { "type": "number", "description": "Number of validation errors in the extraction", "example": 0 }, "warnings": { "type": "number", "description": "Number of validation warnings in the extraction", "example": 1 }, "skipped": { "type": "integer", "description": "Number of fields skipped in the extraction because a prerequisite field was null", "example": 1 } } }, "Errors": { "type": "array", "description": "Extraction error messages.", "items": { "$ref": "#/components/schemas/ExtractionError" } }, "ExtractionError": { "type": "object", "description": "Extraction error message", "properties": { "field_id": { "type": "string", "description": "ID of the extracted field.", "example": "phone_number" }, "message": { "type": "string", "description": "Description of the error", "example": "ConfigurationError: width <=0" }, "type": { "type": "string", "description": "Error type", "example": "configuration" } } }, "DownloadUrlDocument": { "type": "string", "description": "URL of the document extraction", "example": "https://sensible-so-document-type-bucket-dev-us-west-2.s3.us-west-2.amazonaws.com/sensible/fc3484c5-3f35-4129-bb29-0ad1291ee9f8/EXTRACTION/246a6f60-0e5b-11eb-b720-295a6fba723e.pdf?AWSAccessKeyId=REDACTED" }, "ExtractionId": { "type": "string", "format": "uuid", "description": "Unique ID for the extraction, used to retrieve the extraction", "example": "246a6f60-0e5b-11eb-b720-295a6fba723e" }, "ExtractionCreated": { "type": "string", "format": "date-time", "example": "2022-10-31T16:27:53.433", "description": "Date and time Sensible created the initial empty extraction and set its status to WAITING." }, "ExtractionCompleted": { "type": "string", "format": "date-time", "example": "2022-10-31T16:27:53.741Z", "description": "Date and time Sensible set the extraction's status to COMPLETED" }, "ExtractionUploaded": { "type": "string", "format": "date-time", "example": "2022-10-31T16:27:53.601Z", "description": "Date and time Sensible received and stored the document, prior to setting the extraction's status to PROCESSING." }, "ExtractionProcessingStarted": { "type": "string", "format": "date-time", "example": "2022-10-31T16:27:53.615Z", "description": "Date and time Sensible set the extraction's status to PROCESSING and began extracting data from the document." }, "ExtractionErrorMessage": { "type": "string", "example": "Transferring the file failed with 'Response code 404:\\nNot Found'", "description": "If `status` is `FAILED`, the message describing why the extraction failed. Absent otherwise. This describes a failure of the extraction as a whole; for errors about individual extracted fields, see `errors`." }, "ConvertedUrlDocument": { "type": "string", "format": "url", "description": "Signed URL to download a PDF rendering of this document, for previewing documents whose original file isn't a PDF. Present for every document content type except application/pdf and image/tiff.", "example": "https://sensible-so-document-type-bucket-dev-us-west-2.s3.us-west-2.amazonaws.com/sensible/fc3484c5-3f35-4129-bb29-0ad1291ee9f8/EXTRACTION/246a6f60-0e5b-11eb-b720-295a6fba723e-converted.pdf?AWSAccessKeyId=REDACTED" }, "ExtractionStatus": { "type": "string", "description": "Status of the extraction:\n- WAITING: Sensible created an initial empty extraction and is waiting for the document.\n- PROCESSING: Sensible received the document and is extracting data.\n- FAILED: The extraction failed.\n- COMPLETE: The extraction is complete.\n", "enum": [ "WAITING", "PROCESSING", "COMPLETE", "FAILED" ], "example": "COMPLETE" }, "DocumentTypeNames": { "type": "array", "description": "Specifies the document types contained in the PDF portfolio.", "example": [ "tax_returns", "bank_statements", "credit_reports" ], "items": { "type": "string" } }, "SegmentDocumentsWith": { "type": "string", "enum": [ "llm", "fingerprints" ], "default": "fingerprints", "example": "llm", "description": "Specifies how to segment the page ranges of the documents in the portfolio. For more information, see [Multi-document extraction](https://docs.sensible.so/docs/portfolio)." }, "Webhook": { "type": "object", "description": "Pushes extraction results to the specified webhook under the following circumstances, so you don't have to poll for results status:\n - When Sensible sets `\"status\": \"COMPLETE\"` or `\"status\": \"FAILED\"` \n - When the value for `reviewStatus` (for portfolio extractions) or `reviewStatus` (for single-document extractions) changes.", "properties": { "url": { "type": "string", "format": "url", "description": "Webhook destination. Sensible will POST to this URL when the extraction is complete.", "example": "https://example.com/example_webhook_url" }, "payload": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ], "description": "Information additional to the API response, for example a UUID for verification. Can be any of the following types - [string, number, boolean, array, object].", "example": "info extra to the default extraction payload" } } } } } } ```