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

General Information

Environments

API Base URL

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

Token URL

Environment	Base URL	Description
Production	`https://auth.docpier.com/realms/idp/protocol/openid-connect/token`	Live environment for production use.
Stage	`https://auth-stage.docpier.com/realms/idp/protocol/openid-connect/token`	Integration environment.

Contact support@docpier.com to obtain stage 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/realms/idp/protocol/openid-connect/token
Scopes:
- idp.capture — Read and write workspace data.

Retrieve an Access Token

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:

curl -X POST https://auth.docpier.com/realms/idp/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<<your_client_id>>" \
  -d "client_secret=<<your_client_secret>>" \
  -d "scope=idp.capture"

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

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "idp.capture"
}

Authorization: Bearer <<access_token>>

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

Start an extraction

Upload the PDF as multipart/form-data using the file form field.

curl -X POST 'https://idp.docpier.com/api/v1/workspaces/<<WORKSPACE_ID>>/documents' \
-H 'Authorization: Bearer <<access_token>>' \
-F 'file=@/.../invoice_123.pdf;type=application/pdf'

Notes:

Replace <WORKSPACE_ID> with your workspace id.
Replace <access_token> with the token from the previous step.

Content Types & Encoding

Encoding: UTF-8
Default response: application/json
Uploads supported:
- application/pdf
- image/jpeg, image/jpg
- image/png
- image/tiff

Content Negotiation (JSON or XML)

Docpier API responses can be returned as JSON (default) or XML, using standard HTTP content negotiation via the Accept header.

How it works

Default: application/json
Request XML by sending:
- Accept: application/xml
Docpier responds with the matching Content-Type:
- JSON → Content-Type: application/json
- XML → Content-Type: application/xml

Example: Requesting JSON

GET /workspaces/{workspaceId}/documents/{documentId}
Authorization: Bearer <token>
Accept: application/json

Example: Requesting XML

GET /workspaces/{workspaceId}/documents/{documentId}
Authorization: Bearer <token>
Accept: application/xml

XML response example (shape equivalent to JSON)

<documentResponse>
  <documentId>01HXYZ987654321FEDCBA</documentId>
  <workspaceId>04HXYZ123456789ABCDEF</workspaceId>
  <status>COMPLETED</status>
  <documentType>INVOICE</documentType>
  <!-- ...other fields depending on the document schema... -->
</documentResponse>

Notes

XML is an alternative representation only; the semantic meaning and fields match the JSON schema.
If Accept is omitted, Docpier returns JSON.

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
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.
Uploads: Validate files client-side before upload.
Feedback: Provide detailed field corrections to improve model accuracy.

Sequence Diagram (Agent Workflow)

sequenceDiagram
    participant Client as Agent Client
    participant API as Docpier IDP API Server
    participant Auth as OAuth Provider
    participant WebhookReceiver as Client's Webhook Endpoint

    Client->>Auth: Request Access Token (Client Credentials)
    Auth-->>Client: Return access_token

    Client->>API: POST /documents (file upload with Authorization: Bearer <token>)
    API-->>Client: 202 Accepted {documentId, processingInfo}

    Note over API: Document Processing in Progress...

    API->>WebhookReceiver: POST /your-webhook-url (DocumentReadyNotification, {documentId, status: "COMPLETED"})
    WebhookReceiver-->>API: 200 OK (Webhook Acknowledged)

    Client->>API: GET /documents/{documentId} (Authorization: Bearer <token>)
    API-->>Client: 200 OK {items: [...], status: "COMPLETED"}

    Client->>API: PATCH /documents/{documentId}/feedback (JSON body with feedback, Authorization: Bearer <token>)
    API-->>Client: 200 OK (Feedback successfully received)

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.

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