Skip to main content
POST
/
document_intelligence
Create Document Intelligence
curl --request POST \
  --url https://connect.penbox.io/v1/document_intelligence \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [
    {
      "name": "<string>",
      "key": "<string>",
      "hint": "<string>",
      "type": "text",
      "fields": [
        {
          "name": "<string>",
          "key": "<string>",
          "hint": "<string>",
          "type": "text"
        }
      ]
    }
  ],
  "attachments": [
    {
      "data": "aSDinaTvuI8gbWludGxpZnk=",
      "name": "<string>",
      "type": "<string>"
    }
  ],
  "workspace": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "language": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "attachments": [
    {
      "name": "<string>",
      "type": "<string>",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "results": {
    "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"
  },
  "updated_at": "2023-11-07T05:31:56Z",
  "language": "<string>",
  "creator": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com"
  },
  "usage": {
    "input": 123,
    "output": 123,
    "total": 123,
    "pages": 123
  }
}
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
object
Company reference (will use first workspace from token if ommited)
​
attachments
array
required
Array of attachments to process (minimum 1 attachment). Each attachment must use either the id field (reference existing) OR the data field (upload new).
Exactly one of fields or template must be provided — not both.
​
fields
array
Array of fields to extract from the documents. Mutually exclusive with template.
​
template
object
Reference to a document intelligence template. Mutually exclusive with fields.
​
language
string
Optional language hint for document processing
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.

Authorizations

​
Authorization
string
header
required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Body

application/json

Exactly one of 'fields' or 'template' must be provided.

​
fields
object[]
required

Fields to extract. Mutually exclusive with 'template'.

​
attachments
object[]
required

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.

Minimum array length: 1

New file upload with base64-encoded data

​
template
object

Reference to a document intelligence template. Mutually exclusive with 'fields'.

​
workspace
object
​
language
string

Optional language hint for document processing

Response

201 - application/json

Document intelligence job created

​
id
string<uuid>
required

Document intelligence job UUID

​
created_at
string<date-time>
required

Job creation timestamp

​
attachments
object[]
required

Array of processed documents

​
results
object
required

Extraction results: the extracted fields, a validation assessment, and the 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"
}
​
updated_at
string<date-time>

Last update timestamp

​
language
string

Document language detected or specified

​
creator
object

User who created the job

​
usage
object

Token usage statistics for the AI processing