--- updatedAt: 2026-07-31T18:03:06.000Z agentTools: projectIndex: https://docs.sensible.so/llms.txt --- # Extract doc at a Sensible URL using specified config This endpoint's behavior is identical to the [Extract doc at a Sensible URL](ref:generate-an-upload-url) endpoint's behavior, except that Sensible uses the specified config to extract data from the document instead of automatically choosing the best-scoring extraction in the document type. # 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": "Document", "description": "Extract data from documents" } ], "paths": { "/generate_upload_url/{document_type}/{config_name}": { "post": { "operationId": "generate-an-upload-url-with-config", "summary": "Extract doc at a Sensible URL using specified config", "description": "This endpoint's behavior is identical to the [Extract doc at a Sensible URL](https://docs.sensible.so/reference/generate-an-upload-url) endpoint's behavior, except that Sensible uses the specified config to extract data from the document instead of automatically choosing the best-scoring extraction in the document type.\n", "parameters": [ { "$ref": "#/components/parameters/document_type" }, { "$ref": "#/components/parameters/environment" }, { "$ref": "#/components/parameters/document_name" }, { "$ref": "#/components/parameters/config_name" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateUrlRequest" } } } }, "tags": [ "Document" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } }, "description": "Returns the upload_url at which to PUT the document for extraction" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "415": { "$ref": "#/components/responses/415" }, "429": { "$ref": "#/components/responses/429" }, "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." } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "title": "Too Many Requests", "type": "string", "example": "One of the following error messages - Attempt limit exceeded, please retry after some time. Free accounts are limited to 150 API calls per month. Please upgrade your account to make additional calls. Pro accounts are limited to 5,000 API calls per month. Please upgrade your account to make additional calls." } } } }, "500": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "title": "Sensible encountered an unknown error", "type": "string", "example": "Sensible encountered an unknown error" } } } } }, "parameters": { "document_type": { "name": "document_type", "required": true, "in": "path", "description": "Type of document to extract from. Create your custom type in the Sensible app (for example, `rate_confirmation`, `certificate_of_insurance`, or `home_inspection_report`). To quickly test this endpoint using the `Try It` button in this interactive explorer, use the `senseml_basics` tutorial document type with this [example document](https://raw.githubusercontent.com/sensible-hq/sensible-docs/v0/assets/pdfs/1_extract_your_first_data.pdf). As a convenience, Sensible automatically detects the best-fit extraction from among the extraction queries (\"configs\") in the document type. For example, if you create an `auto_insurance_quotes` document type, you can add `carrier 1`, `carrier 2`, and `carrier 3` configs to the document type in the Sensible app. Sensible then automatically classifies each document you upload by its carrier, so you can use the same document type for each carrier without specifying the carrier in the extraction request.", "schema": { "type": "string" }, "example": "senseml_basics" }, "config_name": { "name": "config_name", "required": true, "in": "path", "description": "User-friendly name of the config to use to extract data from the document.", "schema": { "type": "string" }, "example": "anyco_insurance_auto_declarations" }, "document_name": { "name": "document_name", "in": "query", "description": "If you specify the filename of the document using this parameter, then Sensible returns the filename in the extraction response.", "schema": { "type": "string" }, "example": "test.pdf" }, "environment": { "name": "environment", "in": "query", "description": "If you specify `development`, extracts preferentially using config versions published to the development environment in the Sensible app. The extraction runs all configs in the doc type before picking the best fit. For each config, falls back to production version if no development version of the config exists.", "schema": { "type": "string", "enum": [ "production", "development" ], "default": "production" } } }, "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 } }, "UploadUrl": { "type": "string", "format": "url", "description": "URL at which to PUT the document bytes for extraction. for example, curl -T ./sample.pdf \"YOUR_UPLOAD_URL\"", "example": "https://sensible-so-utility-bucket-prod-us-west-2.s3.us-west-2.amazonaws.com/EXTRACTION_UPLOAD/sensible/fc3484c5-3f35-4129-bb29-0ad1291ee9f8/EXTRACTION/14d82783-c12b-4e70-b0ae-ca1ce35a9836.pdf?AWSAccessKeyId=REDACTED&Expires=1623861476&Signature=REDACTED&x-amz-security-token=REDACTED" }, "UploadResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ExtractionId" }, "created": { "$ref": "#/components/schemas/ExtractionCreated" }, "type": { "$ref": "#/components/schemas/DocumentTypeName" }, "status": { "$ref": "#/components/schemas/ExtractionStatus" }, "upload_url": { "$ref": "#/components/schemas/UploadUrl" } } }, "GenerateUrlRequest": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" }, "content_type": { "$ref": "#/components/schemas/ContentTypeParameter" }, "extra_data": { "$ref": "#/components/schemas/ExtraDataRecord" } } }, "DocumentTypeName": { "description": "Unique user-friendly name for a document type", "example": "auto_insurance_quotes_all_carriers", "type": "string" }, "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." }, "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" }, "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" } } }, "ContentTypeParameter": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/tiff", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "application/vnd.ms-excel.sheet.macroenabled.12", "text/csv", "application/json" ], "description": "Content type of the document being presented for extraction. Required for the CSV file type." } } } } ```