List documents

curl --request GET \
  --url https://api.beltic.com/v1/documents \
  --header 'X-Api-Key: <api-key>'

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "document",
      "attributes": {
        "file": {
          "id": "<string>",
          "filename": "<string>",
          "content_type": "image/jpeg",
          "byte_size": 3340938,
          "checksum": "cdff95d353d86a9fa1f06532a8ca212430d5b512efa669250c0777c9525d55fb",
          "url": "https://files.beltic.com/9941d601-0dd4-4a33-8043-4f158b480f0e/file?X-Amz-Signature=..."
        },
        "processing_errors": [
          {
            "status": "<string>",
            "code": "<string>",
            "title": "<string>",
            "detail": "<string>",
            "meta": {
              "occurred_at": "<string>"
            }
          }
        ],
        "created_at": "<string>",
        "submitted_at": "<string>",
        "processed_at": "<string>",
        "redacted_at": "<string>",
        "extracted_data": {},
        "fraud_result": {
          "score": "NORMAL",
          "file_metadata": {
            "producer": null,
            "creator": null,
            "creation_date": null,
            "mod_date": null,
            "author": null,
            "title": null,
            "keywords": null,
            "subject": null
          },
          "indicators": [
            {
              "id": "<string>",
              "category": "<string>",
              "title": "<string>",
              "description": "<string>"
            }
          ],
          "document_classification": {
            "id": "<string>",
            "type": "<string>",
            "document_class_type": "<string>",
            "detailed_type": "<string>"
          }
        },
        "extracted_data_coordinates": {
          "version": 1,
          "fields": {
            "partners[0]": [
              {
                "surface": {
                  "type": "page",
                  "number": 2
                },
                "coordinate_space": "normalized_page",
                "bbox": {
                  "left": 0.177,
                  "top": 0.783,
                  "width": 0.672,
                  "height": 0.016
                },
                "polygon": [
                  {
                    "x": 0.177,
                    "y": 0.783
                  },
                  {
                    "x": 0.848,
                    "y": 0.783
                  },
                  {
                    "x": 0.848,
                    "y": 0.799
                  },
                  {
                    "x": 0.177,
                    "y": 0.799
                  }
                ]
              }
            ]
          }
        },
        "fraud_result_coordinates": {
          "version": 1,
          "indicators": {
            "grp_overlaps": [
              {
                "surface": {
                  "type": "page",
                  "number": 1
                },
                "coordinate_space": "normalized_page",
                "bbox": {
                  "left": 0.471,
                  "top": 0.601,
                  "width": 0.397,
                  "height": 0.27
                },
                "polygon": null,
                "detail": {
                  "original_text": "ParsedImage",
                  "new_text": ""
                }
              }
            ]
          }
        }
      },
      "relationships": {
        "document_template": {
          "data": {
            "type": "document-template",
            "id": "123e4567-e89b-12d3-a456-426614174000"
          }
        },
        "session": {
          "data": {
            "type": "session",
            "id": "123e4567-e89b-12d3-a456-426614174000"
          }
        }
      },
      "meta": {
        "extraction_config": {
          "enabled": true,
          "schema": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ],
            "additionalProperties": true
          },
          "extraction_rules": ""
        },
        "fraud_config": {
          "enabled": true,
          "requires_digital_signature": true
        },
        "file_url": "<string>",
        "ocr_external_id": "<string>",
        "fraud_check_external_id": "<string>"
      }
    }
  ],
  "meta": {
    "page": {
      "cursors": {
        "start": "<string>",
        "end": "<string>"
      },
      "hasNextPage": true,
      "hasPreviousPage": true,
      "total": 123
    }
  },
  "links": {
    "self": "<string>",
    "first": "<string>",
    "next": "<string>",
    "prev": "<string>",
    "last": "<string>"
  }
}

Document API

List Documents

Retrieve a paginated list of documents with optional filtering. Uses cursor-based pagination for efficient data retrieval.

Pagination:

Use page[size] to control results per page (default: 15, max: 100)
Navigate using page[after] or page[before] cursors from the response
Set page[total]=true to include total count (may impact performance on large datasets)
Response includes links for easy navigation (first, prev, next, last)

Filtering:

Filter by status to get documents in a specific processing state or multiple states (comma-separated)
Filter by template_id to get documents using a specific template

Sparse Fieldsets (JSON:API):

Use fields[document] with a comma-separated list to return only specific fields (attributes and relationships)
id and type are always returned; an empty value returns only id/type
Omit the parameter to return all fields
Unknown field names return 400 Bad Request

Example Queries:

Single status: GET /v1/documents?page[size]=20&filter[status]=processed&page[after]=eyJ2YWx1ZXM...
Multiple statuses: GET /v1/documents?page[size]=20&filter[status]=pending,submitted,processing,processed,failed,redacted
Sparse fields: GET /v1/documents?fields[document]=status,file

GET

documents

List documents

curl --request GET \
  --url https://api.beltic.com/v1/documents \
  --header 'X-Api-Key: <api-key>'

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "document",
      "attributes": {
        "file": {
          "id": "<string>",
          "filename": "<string>",
          "content_type": "image/jpeg",
          "byte_size": 3340938,
          "checksum": "cdff95d353d86a9fa1f06532a8ca212430d5b512efa669250c0777c9525d55fb",
          "url": "https://files.beltic.com/9941d601-0dd4-4a33-8043-4f158b480f0e/file?X-Amz-Signature=..."
        },
        "processing_errors": [
          {
            "status": "<string>",
            "code": "<string>",
            "title": "<string>",
            "detail": "<string>",
            "meta": {
              "occurred_at": "<string>"
            }
          }
        ],
        "created_at": "<string>",
        "submitted_at": "<string>",
        "processed_at": "<string>",
        "redacted_at": "<string>",
        "extracted_data": {},
        "fraud_result": {
          "score": "NORMAL",
          "file_metadata": {
            "producer": null,
            "creator": null,
            "creation_date": null,
            "mod_date": null,
            "author": null,
            "title": null,
            "keywords": null,
            "subject": null
          },
          "indicators": [
            {
              "id": "<string>",
              "category": "<string>",
              "title": "<string>",
              "description": "<string>"
            }
          ],
          "document_classification": {
            "id": "<string>",
            "type": "<string>",
            "document_class_type": "<string>",
            "detailed_type": "<string>"
          }
        },
        "extracted_data_coordinates": {
          "version": 1,
          "fields": {
            "partners[0]": [
              {
                "surface": {
                  "type": "page",
                  "number": 2
                },
                "coordinate_space": "normalized_page",
                "bbox": {
                  "left": 0.177,
                  "top": 0.783,
                  "width": 0.672,
                  "height": 0.016
                },
                "polygon": [
                  {
                    "x": 0.177,
                    "y": 0.783
                  },
                  {
                    "x": 0.848,
                    "y": 0.783
                  },
                  {
                    "x": 0.848,
                    "y": 0.799
                  },
                  {
                    "x": 0.177,
                    "y": 0.799
                  }
                ]
              }
            ]
          }
        },
        "fraud_result_coordinates": {
          "version": 1,
          "indicators": {
            "grp_overlaps": [
              {
                "surface": {
                  "type": "page",
                  "number": 1
                },
                "coordinate_space": "normalized_page",
                "bbox": {
                  "left": 0.471,
                  "top": 0.601,
                  "width": 0.397,
                  "height": 0.27
                },
                "polygon": null,
                "detail": {
                  "original_text": "ParsedImage",
                  "new_text": ""
                }
              }
            ]
          }
        }
      },
      "relationships": {
        "document_template": {
          "data": {
            "type": "document-template",
            "id": "123e4567-e89b-12d3-a456-426614174000"
          }
        },
        "session": {
          "data": {
            "type": "session",
            "id": "123e4567-e89b-12d3-a456-426614174000"
          }
        }
      },
      "meta": {
        "extraction_config": {
          "enabled": true,
          "schema": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ],
            "additionalProperties": true
          },
          "extraction_rules": ""
        },
        "fraud_config": {
          "enabled": true,
          "requires_digital_signature": true
        },
        "file_url": "<string>",
        "ocr_external_id": "<string>",
        "fraud_check_external_id": "<string>"
      }
    }
  ],
  "meta": {
    "page": {
      "cursors": {
        "start": "<string>",
        "end": "<string>"
      },
      "hasNextPage": true,
      "hasPreviousPage": true,
      "total": 123
    }
  },
  "links": {
    "self": "<string>",
    "first": "<string>",
    "next": "<string>",
    "prev": "<string>",
    "last": "<string>"
  }
}

Authorizations

X-Api-Key

string

header

required

API key for authentication. Access https://console.beltic.com/ to obtain your API key.

Query Parameters

page[size]

string

Number of items per page (default: 15)

Pattern: ^\d+$

Example:

"15"

page[after]

string

Cursor for fetching items after this point

Example:

"eyJ2YWx1ZXMiOnsiY3JlYXRlZF9hdCI6IjIwMjUtMTAtMjJUMjI6MTM6NDguMTQ5WiJ9LCJpZCI6IjNkZjk3MWQwLWNkNTYtNDAwNi05YmM0LTFjYmMzMjc1OWI2ZiJ9"

page[before]

string

Cursor for fetching items before this point

Example:

"eyJ2YWx1ZXMiOnsiY3JlYXRlZF9hdCI6IjIwMjUtMTAtMjJUMjI6MTM6NDguMTQ5WiJ9LCJpZCI6IjNkZjk3MWQwLWNkNTYtNDAwNi05YmM0LTFjYmMzMjc1OWI2ZiJ9"

page[total]

enum<string>

Include total count in response (may impact performance)

Available options:

true,

false

Example:

"true"

filter[status]

string

Filter documents by status. Supports single value or comma-separated values (e.g., "pending,submitted,processing,processed,failed,redacted")

Example:

"pending,submitted,processing,processed,failed,redacted"

filter[template_id]

string<uuid>

Filter documents by template ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

fields[document]

string

Sparse fieldset: comma-separated list of document fields (attributes and relationships) to return. An empty value returns only id/type. Omit the parameter to return all fields.

Example:

"status,file"

Response

Documents retrieved successfully

data

object[]

required

Show child attributes