openapi: 3.0.3
info:
title: Sensible Document Types and Configurations API
version: v0
description: Manage document types and SenseML configurations. Create, list, update, and delete document types; create,
list, fetch, update, publish, and delete SenseML configuration versions; list versions for a configuration.
contact:
name: Sensible
url: https://www.sensible.so
email: [email protected]
license:
name: Proprietary
url: https://www.sensible.so/terms
servers:
- url: https://api.sensible.so/v0
description: Production server
security:
- bearerAuth: []
tags: []
paths:
/document_types/{type-id}/configurations:
parameters:
- $ref: '#/components/parameters/documentTypeId'
post:
operationId: create-configuration
summary: Create configuration in a document type
description: Pass the configuration as stringified JSON.
tags:
- Configuration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostConfiguration'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationResponse'
description: The created configuration
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
get:
operationId: list-configurations
summary: List configurations in a document type
description: List configurations in a document type.
tags:
- Configuration
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllConfigurations'
description: List of document types for the current account
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/document_types/{type-id}/configurations/{config-name}:
parameters:
- $ref: '#/components/parameters/documentTypeId'
- $ref: '#/components/parameters/configurationName'
get:
operationId: get-configuration
summary: Get configuration
description: Get a configuration as stringified JSON.
tags:
- Configuration
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationResponse'
description: The identified configuration
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
put:
operationId: update-configuration
summary: Update configuration
description: Replace a published or draft version of the configuration.
tags:
- Configuration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PutConfiguration'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationResponse'
description: The created configuration
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
delete:
operationId: delete-configuration
summary: Delete configuration
description: Delete a configuration and its versions.
tags:
- Configuration
responses:
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/document_types/{type-id}/configurations/{config-name}/{version}:
parameters:
- $ref: '#/components/parameters/documentTypeId'
- $ref: '#/components/parameters/configurationName'
- $ref: '#/components/parameters/versionIdentifier'
delete:
operationId: delete-configuration-by-version
summary: Delete draft or unpublish configuration
description: To delete a draft, specify a version name in the `version` parameter. To unpublish a configuration, enter
the publication environment name in the `version` parameter, for example, `development`.
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/documentTypeId'
- $ref: '#/components/parameters/configurationName'
- in: path
name: version
required: true
description: if unpublishing a configuration from an environment, the name of the environment (`development`, `production`.)
If deleting the current draft, the version number of the current draft.
schema:
type: string
responses:
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
get:
operationId: get-configuration-by-version
summary: Get configuration by version
description: Get a configuration as stringified JSON by version id.
tags:
- Configuration
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationResponse'
description: The identified configuration
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/document_types:
post:
operationId: create-document-type
summary: Create document type
description: Create a document type.
tags:
- Document type
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostDocumentType'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentType'
description: List of document types for the current account
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
get:
operationId: list-document-types
summary: List document types
description: Lists all document types in your Sensible account.
tags:
- Document type
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetAllDocumentTypes'
description: List of document types for the current account
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/document_types/{type-id}:
parameters:
- $ref: '#/components/parameters/documentTypeId'
get:
operationId: get-document-type
summary: Get document type
description: Find the document type id using the `/document_types` endpoint.
tags:
- Document type
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentType'
description: Identified document type
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
delete:
operationId: delete-document-type
summary: Delete document type
description: 'Delete a document type and everything it contains, for example configurations and reference PDfs,
but not its extraction history displayed in the Sensible app.
'
tags:
- Document type
responses:
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
/document_types/{type-id}/configurations/{config-name}/versions:
parameters:
- $ref: '#/components/parameters/documentTypeId'
- $ref: '#/components/parameters/configurationName'
get:
operationId: get-configuration-versions
summary: List versions for a configuration
description: Get the version ids for a configuration.
tags:
- Configuration
responses:
'200':
description: Version information for the identified configuration
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationVersionsResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'415':
$ref: '#/components/responses/415'
'500':
$ref: '#/components/responses/500'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token using a Sensible API key. Create keys at https://app.sensible.so/account/.
schemas:
UniqueId:
type: string
format: uuid
description: Unique identifier
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
ConfigurationName:
description: Unique user-friendly name for a configuration
example: anyco_auto_insurance_quote
type: string
Date:
type: string
format: date-time
description: ISO 8601 date-time.
ConfigurationVersion:
type: object
properties:
version_id:
type: string
example: fdE0LO4d2GftiGvPyeYbgpstRWyLrEdm
datetime:
$ref: '#/components/schemas/Date'
description: "The date and time Sensible created this version ID for the config. Sensible creates a new version\
\ ID for a config when you: 1. publish a config to an environment in the Sensible app 2. create or edit the configuration\
\ through the Sensible API. Publishing or unpublishing an\n existing configuration version using the Sensible\
\ API doesn't trigger the creation of a new version ID."
environments:
type: array
items:
type: string
example:
- production
- development
draft:
type: boolean
example: false
description: The version list returned by this endpoint contains a single draft version ID that's used to manage
the editor state in the Sensible app. This draft version ID is never published to the development or production
environments.
required:
- version_id
- datetime
- draft
additionalProperties: false
PostConfiguration:
type: object
properties:
name:
$ref: '#/components/schemas/ConfigurationName'
configuration:
$ref: '#/components/schemas/StringifiedConfigurationRequest'
example: "{ \t\"fingerprint\": { \t\t\"tests\": [ \t\t\t\"anyco\", \t\t\t\"quoted coverage changes\" \t\t] \t},\
\ \t\"preprocessors\": [{ \t\t\"type\": \"pageRange\", \t\t\"startPage\": 0, \t\t\"endPage\": 2 \t}], \t\"fields\"\
: [{ \t\t\"id\": \"_driver_name_raw\", \t\t\"anchor\": \"name of driver\", \t\t\"method\": { \t\t\t\"id\": \"\
label\", \t\t\t\"position\": \"below\" \t\t} \t}], \t\"computed_fields\": [{ \t\t\t\"id\": \"driver_name_last\"\
, \t\t\t\"method\": { \t\t\t\t\"id\": \"split\", \t\t\t\t\"source_id\": \"_driver_name_raw\", \t\t\t\t\"separator\"\
: \", \", \t\t\t\t\"index\": 1 \t\t\t} \t\t} \t] }\n"
publish_as:
$ref: '#/components/schemas/Environment'
required:
- name
- configuration
additionalProperties: false
StringifiedConfigurationRequest:
type: string
description: 'JSON-stringified configuration.
If you test this endpoint using the **Try It** button in this interactive API explorer,
the explorer stringifies the JSON for you when you paste the configuration into this parameter.
To support publishing drafts, this API doesn’t reject requests with configuration errors.
To validate, compare your configuration to the latest version of the configuration schema, published at https://schema.sensible.so/configuration.schema.json.
'
Environment:
type: string
enum:
- production
- development
minLength: 3
maxLength: 128
example: development
description: Destination environment for publication, as a target for later extraction. If you specify an environment,
the configuration must be valid. If you don't specify an environment, Sensible saves this version of the configuration
as the current draft.
ConfigurationResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ConfigurationName'
created:
$ref: '#/components/schemas/Date'
configuration:
type: string
description: Configuration returned as stringified JSON.
example: '"{\r\n\t\"fingerprint\": {\r\n\t\t\"tests\": [\r\n\t\t\t\"anyco\",\r\n\t\t\t\"quoted coverage changes\"\r\n\t\t]\r\n\t},\r\n\t\"preprocessors\":
[{\r\n\t\t\"type\": \"pageRange\",\r\n\t\t\"startPage\": 0,\r\n\t\t\"endPage\": 2\r\n\t}],\r\n\t\"fields\": [{\r\n\t\t\"id\":
\"_driver_name_raw\",\r\n\t\t\"anchor\": \"name of driver\",\r\n\t\t\"method\": {\r\n\t\t\t\"id\": \"label\",\r\n\t\t\t\"position\":
\"below\"\r\n\t\t}\r\n\t}],\r\n\t\"computed_fields\": [{\r\n\t\t\t\"id\": \"driver_name_last\",\r\n\t\t\t\"method\":
{\r\n\t\t\t\t\"id\": \"split\",\r\n\t\t\t\t\"source_id\": \"_driver_name_raw\",\r\n\t\t\t\t\"separator\": \",
\",\r\n\t\t\t\t\"index\": 1\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t]\r\n}"
'
version_id:
type: string
versions:
type: array
items:
$ref: '#/components/schemas/ConfigurationVersion'
required:
- name
- created
- configuration
- version_id
- versions
additionalProperties: false
Name:
type: string
pattern: ^[a-z0-9_]*$
minLength: 3
maxLength: 128
description: User-friendly name
GetAllConfigurations:
type: array
items:
type: object
properties:
name:
$ref: '#/components/schemas/ConfigurationName'
created:
$ref: '#/components/schemas/Date'
versions:
type: array
items:
$ref: '#/components/schemas/ConfigurationVersion'
required:
- name
- created
- versions
additionalProperties: false
PutConfiguration:
type: object
properties:
name:
$ref: '#/components/schemas/Name'
configuration:
$ref: '#/components/schemas/StringifiedConfigurationRequest'
example: "{ \"fields\": [{ \t\t\"id\": \"updated_name_field\", \t\t\"anchor\": \"name of driver\", \t\t\"method\"\
: { \t\t\t\"id\": \"label\", \t\t\t\"position\": \"below\" \t\t} \t}], \t\"computed_fields\": [{ \t\t\t\"id\"\
: \"driver_name_last\", \t\t\t\"method\": { \t\t\t\t\"id\": \"split\", \t\t\t\t\"source_id\": \"_driver_name_raw\"\
, \t\t\t\t\"separator\": \", \", \t\t\t\t\"index\": 1 \t\t\t} \t\t} \t] }\n"
publish_as:
$ref: '#/components/schemas/Environment'
current_draft:
type: string
description: Version ID of the current draft of the configuration, if the current draft exists and is being replaced.
if the configuration is currently in draft and this parameter is not supplied or does not match, the operation
fails
additionalProperties: false
DocumentTypeName:
description: Unique user-friendly name for a document type
example: auto_insurance_quotes_all_carriers
type: string
DocumentType:
type: object
properties:
name:
$ref: '#/components/schemas/DocumentTypeName'
id:
$ref: '#/components/schemas/UniqueId'
created:
$ref: '#/components/schemas/Date'
schema:
$ref: '#/components/schemas/DocumentTypeOutput'
required:
- name
- id
- created
- schema
additionalProperties: false
PostDocumentType:
type: object
properties:
name:
$ref: '#/components/schemas/DocumentTypeName'
schema:
$ref: '#/components/schemas/DocumentTypeOutput'
required:
- name
- schema
additionalProperties: false
DocumentTypeOutput:
type: object
additionalProperties: false
properties:
fingerprint_mode:
enum:
- fallback_to_all
- strict
type: string
description: The Sensible app defaults to `fallback_to_all`.
ocr_engine:
enum:
- microsoft
- amazon
- google
- lazarus
type: string
description: 'For information about each OCR engine, see [OCR engine](https://docs.sensible.so/docs/ocr-engine).
'
prevent_default_merge_lines:
type: boolean
description: 'Prevents the built-in line merging that occurs before the
[Merge Lines](https://docs.sensible.so/docs/merge-lines) preprocessor.
'
ocr_level:
enum:
- 0
- 2
- 4
- 5
type: number
description: 'See [OCR level](https://docs.sensible.so/docs/ocr-level).
'
validations:
description: Array of validations. See [Validating extractions](https://docs.sensible.so/docs/validate-extractions).
items:
$ref: '#/components/schemas/Validation'
type: array
review_triggers:
description: 'Array of criteria for flagging an extraction for [human review](https://docs.sensible.so/docs/human-review).
Criteria include `coverage_threshold`, `validation_warnings_threshold`, and `validation_errors_threshold`. If
the review criteria includes specific validations, this parameter contains `"selected_validations": true` and
each selected validation includes a `"review_trigger":true` parameter.'
type: array
items:
type: string
Validation:
type: object
additionalProperties: false
description: See https://docs.sensible.so/docs/validate-extractions.
properties:
description:
type: string
description: User-friendly description for the test
example: Broker's email is in string@string format
condition:
description: The test for validating the field, written in JsonLogic.
example:
match:
- var: broker\.email.value
- ^\S+\@\S+$
type: object
additionalProperties: true
fields:
type: array
description: Skip this test unless prerequisite fields are non-null.
example:
- broker\.email
items:
type: string
severity:
type: string
description: Severity of the failing test
enum:
- warning
- error
scope:
type: array
description: If the field to validate is in sections, the list of parent sections.
example:
- parent_section
- child_section
required:
- description
- condition
GetAllDocumentTypes:
type: array
items:
type: object
properties:
name:
$ref: '#/components/schemas/DocumentTypeName'
id:
$ref: '#/components/schemas/UniqueId'
created:
$ref: '#/components/schemas/Date'
schema:
$ref: '#/components/schemas/DocumentTypeOutput'
required:
- name
- id
additionalProperties: false
ConfigurationVersionsResponse:
type: object
properties:
versions:
type: array
items:
$ref: '#/components/schemas/ConfigurationVersion'
required:
- versions
additionalProperties: false
parameters:
documentTypeId:
name: type-id
required: true
in: path
description: The unique document type identifier in v4 UUID format. Find IDs using the `/document_types` endpoint.
schema:
$ref: '#/components/schemas/UniqueId'
configurationName:
name: config-name
required: true
in: path
description: Unique name for a configuration. Find it in the Sensible app or from the `/document_types/{type-id}/configurations`
endpoint.
example: anyco_auto_insurance_quote
schema:
$ref: '#/components/schemas/Name'
versionIdentifier:
name: version
required: true
in: path
description: Unique identifier for a configuration version.
schema:
type: string
responses:
'400':
description: Bad Request
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
- Not available to logged in users 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 Specified configuration/version does not
exist Specified configuration/version is not valid Must provide the Content-Type header when request body is
present Content-Type must be application/json 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} Document is not present
'401':
description: Not authorized
content:
text/plain:
schema:
title: Unauthorized
type: string
example: Unauthorized
'404':
description: Not Found
content:
text/plain:
schema:
title: Not Found
type: string
'415':
description: Unsupported Media Type
content:
text/plain:
schema:
title: Unsupported Media Type
type: string
example: Messages related to the file format of the document to extract data from.
'500':
description: Internal Server Error
content:
text/plain:
schema:
title: Sensible encountered an unknown error
type: string
example: Sensible encountered an unknown error
'204':
description: No content
content:
text/plain:
schema:
title: No Content
type: string
example: No Content