General - Docpier Intelligent Document Processing API

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

Last Updated: 29. August, 2025

General Information

Environments

Environment	Base URL	Description
Production	`https://idp.docpier.com/api/v1`	Live environment for production use.
Sandbox	`https://idp-stage.docpier.com/api/v1`	Integration environment.

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.

There is only major version visible (/v1) on the URL path https://.../api/v1

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 workspace 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/jp[e]g, image/png, image/tiff

Integration Guidelines

Obtain Credentials

Contact support@docpier.com to receive:

client_id

client_secret

workspace_id

Test in Stage environemnt

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

Implement Workflows

Agent Workflow (Server-to-Server)

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

GET /v1/worspaces/{workspace_id}/documents/{documentId} — Get processed data (poll the result)

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

Rate Limits

Environment	Limit
Production	100 requests/minute
Stage	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)

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).
`POLICY_ADJUSTMENT`	The document is identified as a policy adjustment. The document records a modification, correction, or endorsement to an existing insurance policy
`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.

Domain Models (schemas)

In this section you find the schemas to core document and invoice. Check the endpoint definitions for other document types and more details.

Core Document

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

IDP API

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 Stage environemnt#

Implement Workflows#

Agent Workflow (Server-to-Server)#

Rate Limits#

nFADP Compliance#

Best Practices#

Sequence Diagram (Agent Workflow)#

Key Field Definitions#

documentType#

Domain Models (schemas)#

Normalized JSON Structure#

Support#