> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Document Intelligence
> Extract structured data from documents using AI-powered document intelligence.
Extract structured data from documents using AI-powered document intelligence.
To use this feature, activation is required on your workspace. Please contact us for more
information.
## Request Body
Company reference (will use first workspace from token if ommited)
Company UUID
Array of attachments to process (minimum 1 attachment). Each attachment must use **either** the `id` field (reference existing) **OR** the `data` field (upload new).
Base64-encoded file content
File name (required when using `data`)
MIME type (required when using `data`, e.g., "application/pdf", "image/jpeg")
Existing attachment UUID
File name (optional when using `id`)
MIME type (optional when using `id`)
Exactly one of `fields` or `template` must be provided — not both.
Array of fields to extract from the documents. Mutually exclusive with `template`.
Field name to extract
Optional key for the field
Hint to help the AI extract the field (optional).
Can be used to specify the format of the field, for example: "DD/MM/YYYY" for a date field.
Field type: `text`, `number`, `date`, or `list`. Use `list` for repeating items; when `list`, provide a nested `fields` array defining the structure of each item.
Sub-field name to extract
Key for the sub-field (required for list items)
Hint to help the AI extract the sub-field
Sub-field type: `text`, `number`, or `date`
Reference to a document intelligence template. Mutually exclusive with `fields`.
Document intelligence template UUID
Optional language hint for document processing
Extraction quality level: `fast` or `advanced`. It sets both the model used and the credit cost per
page — `fast` costs 3 credits per page, `advanced` costs 6. Defaults to `advanced`.
Only valid together with `fields`. When you use a `template`, the level configured on that template
applies instead, and sending `level` alongside `template` is rejected.
The document intelligence processing may take a few seconds. The response includes the extracted
results in the `results` field once processing is complete.
Use the `hint` field to help the AI extract the field. For example, if the field is a date, you
can use the `hint` field to specify the format of the date. For example: "DD/MM/YYYY".
You can reference existing attachments by their UUID instead of uploading new ones, which is more
efficient if the documents are already in the system.
## OpenAPI
````yaml POST /document_intelligence
openapi: 3.0.0
info:
title: Penbox API
version: '1.0'
description: >-
The Penbox API provides programmatic access to Penbox's form management,
case management, and document processing capabilities. Authenticate using
Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
- url: https://connect.penbox.io/v1
description: Production
- url: https://connect.aiboov.com/v1
description: Staging
security:
- BearerAuth: []
paths:
/document_intelligence:
post:
summary: Create Document Intelligence
description: >-
Extract structured data from documents using AI-powered document
intelligence.
operationId: create-document-intelligence
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- attachments
description: Exactly one of 'fields' or 'template' must be provided.
oneOf:
- required:
- fields
properties:
fields:
type: array
template:
not: {}
- required:
- template
properties:
template:
type: object
fields:
not: {}
properties:
workspace:
type: object
properties:
id:
type: string
format: uuid
description: >-
Workspace UUID. Leave it empty to use the first
workspace from the token.
attachments:
type: array
minItems: 1
description: >-
Array of attachments to process (minimum 1). Each attachment
must have either 'id' (reference to existing attachment) OR
'data' (new file upload with base64). When using 'data',
'name' and 'type' are required.
items:
oneOf:
- type: object
description: New file upload with base64-encoded data
required:
- data
- name
- type
properties:
data:
type: string
format: byte
description: Base64-encoded file content
name:
type: string
description: File name (required when using 'data')
type:
type: string
description: MIME type (required when using 'data')
- type: object
description: Reference to existing attachment
required:
- id
properties:
id:
type: string
format: uuid
description: Existing attachment UUID
name:
type: string
description: File name (optional when using 'id')
type:
type: string
description: MIME type (optional when using 'id')
fields:
type: array
description: Fields to extract. Mutually exclusive with 'template'.
items:
type: object
required:
- name
properties:
name:
type: string
description: Field name to extract
key:
type: string
description: Optional key for the field
hint:
type: string
description: >-
Hint to help the AI extract the field (optional). Can
be used to specify the format of the field, for
example: 'DD/MM/YYYY' for a date field.
type:
type: string
enum:
- text
- number
- date
- list
default: text
description: >-
Field type. Use 'list' for repeating items; when
'list', provide a 'fields' array defining the
structure of each item.
fields:
type: array
description: >-
Required when type is 'list'. Defines the structure of
each item in the list. Sub-fields require a 'key'.
minItems: 1
items:
type: object
required:
- name
- key
properties:
name:
type: string
description: Sub-field name to extract
key:
type: string
description: Key for the sub-field (required for list items)
hint:
type: string
description: Hint to help the AI extract the sub-field
type:
type: string
enum:
- text
- number
- date
default: text
description: Sub-field type
template:
type: object
description: >-
Reference to a document intelligence template. Mutually
exclusive with 'fields'.
required:
- id
properties:
id:
type: string
format: uuid
description: Document intelligence template UUID
language:
type: string
description: Optional language hint for document processing
level:
type: string
enum:
- fast
- advanced
default: advanced
description: >-
Extraction quality level, which sets both the model used and
the credit cost per page: 'fast' costs 3 credits per page,
'advanced' costs 6. Defaults to 'advanced'. Only valid
together with 'fields' — when 'template' is used the level
configured on that template applies, and sending this field
alongside 'template' is rejected.
responses:
'201':
description: Document intelligence job created
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentIntelligence'
components:
schemas:
DocumentIntelligence:
type: object
properties:
id:
type: string
format: uuid
description: Document intelligence job UUID
created_at:
type: string
format: date-time
description: Job creation timestamp
updated_at:
type: string
format: date-time
description: Last update timestamp
attachments:
type: array
description: Array of processed documents
items:
type: object
properties:
name:
type: string
description: File name
type:
type: string
description: MIME type
id:
type: string
format: uuid
description: Attachment UUID
results:
type: object
description: >-
Extraction results: the extracted fields, a validation assessment,
and the detected document type.
properties:
fields:
type: array
description: Extracted fields. Each entry corresponds to a requested field.
items:
type: object
properties:
key:
type: string
description: >-
Field key (as requested in the input, or derived from the
name)
name:
type: string
description: Field name
hint:
type: string
description: Extraction hint provided in the request, if any
type:
type: string
enum:
- text
- number
- date
- list
description: Field type
value:
description: >-
Extracted value. A string, number or date for scalar
fields, or an array of sub-fields when `type` is `list`.
confidence:
type: string
enum:
- high
- medium
- low
description: Model confidence in the extracted value
validation:
type: object
description: Document-level validation assessment.
properties:
is_valid:
type: boolean
description: Whether the document is considered valid and exploitable
is_blurry:
type: boolean
description: Whether the document image is too blurry to read reliably
user_explanation:
type: string
description: Human-readable justification for the validation result
document_type:
type: string
description: Detected document type
example:
fields:
- key: firstname
name: firstname
type: text
value: Jane
confidence: high
- key: lastname
name: lastname
type: text
value: Doe
confidence: high
- key: number
name: id card number
type: text
value: 000-0000000-00
confidence: high
- key: birthday
name: date de naissance
hint: DD MMM YYYY
type: text
value: 01 JAN 1990
confidence: high
validation:
is_valid: true
is_blurry: false
user_explanation: >-
All required fields were successfully extracted from the
document.
document_type: ID Card
language:
type: string
description: Document language detected or specified
level:
type: string
enum:
- fast
- advanced
nullable: true
description: >-
The quality level this extraction ran at, and therefore the rate it
was billed at per page ('fast' 3 credits per page, 'advanced' 6).
Null for extractions created before levels existed.
creator:
type: object
description: User who created the job
properties:
id:
type: string
format: uuid
email:
type: string
format: email
usage:
type: object
description: Token usage statistics for the AI processing
properties:
input:
type: integer
description: Number of input tokens (prompt tokens)
output:
type: integer
description: Number of output tokens (candidate tokens)
total:
type: integer
description: Total number of tokens used
pages:
type: integer
description: Number of document pages processed
required:
- id
- created_at
- attachments
- results
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: token
description: >-
API token (starts with pnbx_). Create at
https://app.penbox.io/workspace/settings/api. Include as: Authorization:
Bearer {token}
````