Docpier Intelligent Document Processing API Documentation

Overview

The Docpier Intelligent Document Processing (IDP) API enables automated document processing, workspace management, and feedback submission for agents and users. It supports various document types (invoices, credit notes, contracts, etc.) with a normalized JSON structure, ensuring compliance with the Swiss Federal Act on Data Protection (nFADP).

API Base URL (Production): https://idp.docpier.com/api/v1

Current API Version: 1.0.0

Last Updated: July 07, 2025

General Information

Environments

Environment	Base URL	Description
Production	`https://idp.docpier.com/api/v1`	Live environment for production use.
Sandbox	`https://idp-int.docpier.com/api/v1`	Integration/testing with mock data and relaxed rate limits.

Contact support@docpier.com to obtain sandbox credentials.

Version Management

The API uses Semantic Versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking changes; requires client updates.

MINOR: Backward-compatible changes.

PATCH: Bug fixes, minor improvements.

Changelog: https://docpier.com/changelog

Authentication

The API uses OAuth 2.0 managed by Docpier’s identity provider.

Client Credentials Flow (for Agents / Server-to-Server)

Token URL: https://auth.docpier.com/oauth/token

Scopes:

idp.capture — Read and write worspace data.

Example (Client Credentials Flow)

Request an access token using HTTP POST with:

grant_type=client_credentials

client_id=your_client_id

client_secret=your_client_secret

scope=idp.capture

Here’s a full example how to request a client credentials token for Docpier using curl:

The response will include an access_token that can be used in the Authorization header for subsequent API requests.

Example usage after token retrieval:

Authorization: Bearer <access_token>

Best Practice: Cache tokens, refresh before expiry, store credentials securely.

Pagination

The API provides pagination mechanism for clients to query of large amount of data efficiently.

Parameters:

page — The page number (zero-based). Default: 0.

size — The number of items per page. Default: 20, Maximum: 100.

sort — Optional. Sorting criteria in the format: property,(asc|desc).

Example Request:

GET /user/workspaces/ws_abcdef123/documents?page=0&size=10&sort=uploadTime,desc
Authorization: Bearer <token>

Example Response:

{
  "content": [ ... ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 123,
  "totalPages": 13,
  "last": false,
  "first": true,
  "numberOfElements": 10
}

Error Handling

All errors return standard HTTP status codes with consistent JSON error format.

Example Error:

{
  "code": "INVALID_FILE",
  "message": "The uploaded file is not a valid PDF."
}

HTTP Status Codes

Code	Meaning
200	OK
201	Created
202	Accepted
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
413	Payload Too Large
415	Unsupported Media Type
429	Too Many Requests
500	Internal Server Error

Common Error Codes

Code	Description
INVALID_FILE	Invalid file format or corrupted
INVALID_TOKEN	Invalid or expired token
FORBIDDEN_ACCESS	Insufficient permissions
NOT_FOUND	Resource not found
RATE_LIMIT_EXCEEDED	Too many requests
INVALID_SCHEMA	Invalid JSON schema
PROCESSING_FAILED	Processing error

Best Practice: Implement retry logic with exponential backoff for 429 and 500 errors.

Character Sets

Encoding: UTF-8

Content-Type: application/json (default)

Uploads: application/pdf, image/jpeg, image/png, image/tiff

Integration Guidelines

Obtain Credentials

Contact support@docpier.com to receive:

client_id

client_secret

workspace_id

Test in Sandbox

Use https://idp-int.docpier.com/api/v1 to integrate your flow.

Implement Workflows

Agent Workflow (Server-to-Server)

POST /worspaces/{workspace_id}/documents — Upload document

GET /worspaces/{workspace_id}/documents/{documentId} — Poll processing status

PATCH /worspaces/{workspace_id}/documents/{documentId}/feedback — Submit feedback

Rate Limits

Environment	Limit
Production	100 requests/minute
Integration	20 requests/minute

Response Header: X-Rate-Limit-Remaining

nFADP Compliance

Each response containing personal data includes an nFADP object.

Partners are responsible for full compliance with Swiss Federal Act on Data Protection (nFADP) and GDPR.

Best Practices

Authentication: Cache tokens, store credentials securely.

Error Handling: Log errors with codes/messages.

Pagination: Handle next_cursor properly.

Uploads: Validate files client-side before upload.

Feedback: Provide detailed field corrections to improve model accuracy.

Monitoring: Actively monitor usage, response times, and error rates.

Sequence Diagram (Agent Workflow)

Domain/Class Diagram: API Data Model

This diagram illustrates the core entities and their relationships within the Docpier API data model. Note that the ProcessingResult in the diagram broadly represents the structured JSON output (items in the GET /documents/{documentId} response), which will conform to one of the specific document schemas (Invoice, CreditNote, etc.).

Key Field Definitions

This section explains the possible values for all enum fields across the API data models, providing clarity on the expected and accepted values.

`documentType`

Used in: CoreDocument

Value	Description
`INVOICE`	The document is identified as a commercial invoice (Rechnung).
`REMINDER`	The document is identified as a payment reminder (Mahnung).
`RECEIPT`	The document is identified as a payment receipt (Beeleg).
`ACCOUNT_STATEMENT`	The document is identified as a bank account statement (Kontoauszug).
`CREDIT_NOTE`	The document is identified as a credit note (Gutschrift).
`SALARY_STATEMENT`	The document is identified as a salary statement (Lohnausweis).
`PAY_SLIP`	The document is identified as a pay slip (Lohnabrechnung).
`TAX_CERTIFICATE`	The document is identified as a tax certificate (Steuerbescheinigung).
`INSURANCE_POLICY`	The document is identified as an insurance policy (Versicherungspolice).
`WARRANTY_POLICY`	The document is identified as a warranty policy (Garantieschein).
`CONTRACT`	The document is identified as a contract (Vertrag).
`CREDITCARD_STATEMENT`	The document is identified as a credit card statement (Kreditkartenauszug).
`UNKNOWN`	The document type could not be identified or fully structured by Docpier.

`language`

Used in: CoreDocument

Value	Description
`DE`	German (Deutsch)
`FR`	French (Français)
`IT`	Italian (Italiano)
`EN`	English

`type`

For Tax Identifiers (sender.taxIds[].type, recipient.taxIds[].type)

Used in: sender.taxIds.items, recipient.taxIds.items

Value	Description
`UID`	Swiss Company Identification Number (UID/EHRA).
`VAT`	Value Added Tax (VAT) Identification Number (e.g., Swiss MWST).
`VAT_EU`	Value Added Tax (VAT) Identification Number (e.g., EU VAT ID).
`OTHER`	Other type of tax identification not explicitly listed.

`paymentType`

Used in: Invoice, Receipt, Reminder

Value	Description
`QR`	Payment expected/made via Swiss QR-Bill.
`DOMESTIC_IBAN`	Payment expected/made via a domestic IBAN bank transfer.
`INTERNATIONAL_IBAN`	Payment expected/made via an international IBAN bank transfer.
`LSV`	Payment expected/made via Lastschriftverfahren (Direct Debit - Switzerland).
`BDD`	Payment expected/made via Business Debit Direct (Switzerland).
`CREDIT_CARD`	Payment expected/made via a credit card.
`DEBIT_CARD`	Payment expected/made via a debit card.
`CARD`	Payment expected/made via a generic card (type not specified/detected).
`TWINT`	Payment expected/made via Twint mobile payment.
`BANK_TRANSFER`	General bank transfer (when more specific IBAN/LSV/BDD not detected).
`CASH`	Payment expected/made via cash.

`stateOfInvoice`

Used in: Receipt, Invoice, Reminder

Value	Description
`PAID`	The associated invoice (if any) is fully paid.
`OUTSTANDING`	The associated invoice (if any) still has an outstanding balance.

Normalized JSON Structure

The GET /documents/{documentId} endpoint returns processed documents in a normalized JSON structure. Each extracted field corresponds to a defined schema property and includes a confidence score (a float between 0.0 and 1.0) indicating the accuracy of the extraction for that specific field.

The top-level response is an array of detected documents, where each document conforms to one of the specific schemas (e.g., Invoice, Credit Note, Account Statement, or UnknownDocument).

Support

📧 Email: support@docpier.com

📄 Documentation: https://docpier.com/docs

🔔 Changelog: https://docpier.com/changelog

🛠 Issue Reporting: Use partner portal or email (include documentId and error codes for faster resolution).

General

Docpier Intelligent Document Processing API Documentation#

Overview#

General Information#

Environments#

Version Management#

Authentication#

Client Credentials Flow (for Agents / Server-to-Server)#

Example (Client Credentials Flow)#

Pagination#

Parameters:#

Example Request:#

Example Response:#

Error Handling#

Example Error:#

HTTP Status Codes#

Common Error Codes#

Character Sets#

Integration Guidelines#

Obtain Credentials#

Test in Sandbox#

Implement Workflows#

Agent Workflow (Server-to-Server)#

Rate Limits#

nFADP Compliance#

Best Practices#

Sequence Diagram (Agent Workflow)#

Domain/Class Diagram: API Data Model#

Key Field Definitions#

documentType#

language#

type#

paymentType#

stateOfInvoice#

Normalized JSON Structure#

Support#