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>",
  "level": "advanced"
}
'

import requests

url = "https://connect.penbox.io/v1/document_intelligence"

payload = {
    "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>",
    "level": "advanced"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>',
    level: 'advanced'
  })
};

fetch('https://connect.penbox.io/v1/document_intelligence', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/document_intelligence",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
    'level' => 'advanced'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/document_intelligence"

	payload := strings.NewReader("{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://connect.penbox.io/v1/document_intelligence")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/document_intelligence")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}"

response = http.request(request)
puts response.read_body

{
  "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
  }
}

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>",
  "level": "advanced"
}
'

import requests

url = "https://connect.penbox.io/v1/document_intelligence"

payload = {
    "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>",
    "level": "advanced"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>',
    level: 'advanced'
  })
};

fetch('https://connect.penbox.io/v1/document_intelligence', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://connect.penbox.io/v1/document_intelligence",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>',
    'level' => 'advanced'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.penbox.io/v1/document_intelligence"

	payload := strings.NewReader("{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://connect.penbox.io/v1/document_intelligence")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://connect.penbox.io/v1/document_intelligence")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [\n    {\n      \"name\": \"<string>\",\n      \"key\": \"<string>\",\n      \"hint\": \"<string>\",\n      \"type\": \"text\",\n      \"fields\": [\n        {\n          \"name\": \"<string>\",\n          \"key\": \"<string>\",\n          \"hint\": \"<string>\",\n          \"type\": \"text\"\n        }\n      ]\n    }\n  ],\n  \"attachments\": [\n    {\n      \"data\": \"aSDinaTvuI8gbWludGxpZnk=\",\n      \"name\": \"<string>\",\n      \"type\": \"<string>\"\n    }\n  ],\n  \"workspace\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  },\n  \"language\": \"<string>\",\n  \"level\": \"advanced\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

object

Company reference (will use first workspace from token if ommited)

Show Company Object

string

required

Company UUID

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).

Show Option 1: New File Upload

string

required

Base64-encoded file content

string

required

File name (required when using data)

string

required

MIME type (required when using data, e.g., “application/pdf”, “image/jpeg”)

Show Option 2: Reference Existing Attachment

string

required

Existing attachment UUID

string

File name (optional when using id)

string

MIME type (optional when using id)

Exactly one of fields or template must be provided — not both.

array

Array of fields to extract from the documents. Mutually exclusive with template.

Show Field Object

string

required

Field name to extract

string

Optional key for the field

string

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.

string

default:"text"

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.

Show Sub-fields (when type is 'list')

string

required

Sub-field name to extract

string

required

Key for the sub-field (required for list items)

string

Hint to help the AI extract the sub-field

string

default:"text"

Sub-field type: text, number, or date

object

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

Show Template Object

string

required

Document intelligence template UUID

string

Optional language hint for document processing

string

default:"advanced"

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.

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

Option 1
Option 2

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

fields

object[]

required

Fields to extract. Mutually exclusive with 'template'.

Show child attributes

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

Option 1
Option 2

Show child attributes

template

object

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

Show child attributes

workspace

object

Show child attributes

language

string

Optional language hint for document processing

level

enum<string>

default:advanced

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.

Available options:

fast,

advanced

Response

201 - application/json

Document intelligence job created

string<uuid>

required

Document intelligence job UUID

created_at

string<date-time>

required

Job creation timestamp

attachments

object[]

required

Array of processed documents

Show child attributes

results

object

required

Extraction results: the extracted fields, a validation assessment, and the detected document type.

Show child attributes

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

level

enum<string> | null

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.

Available options:

fast,

advanced

creator

object

User who created the job

Show child attributes

usage

object

Token usage statistics for the AI processing

Show child attributes

API Reference

Workspaces

Cases

Case Templates

Forms

Form Templates

Attachments

Document Intelligence

Signatures

Previous API version

Create Document Intelligence

Request Body

Authorizations

Body

Response

​Request Body

Authorizations

Body

Response

Request Body