# PaperOffice AI API

> AI-powered document automation: OCR, IDP, PDF, e-signatures, translation, voice, workflows. Comprehensive REST API with native MCP server support — organized by category below.

## Quick Start

<a id="quick-start"></a>

- **Base URL:** `https://api.paperoffice.ai/latest`
- **Auth:** `Authorization: Bearer po_sk_xxx` (System Key), `Bearer po_ut_xxx` (User Token), or `Bearer po_pk_xxx` (Publishable Key)
- **Landing page:** https://paperoffice.ai/l/developer-llms/ (language auto; EN: https://paperoffice.ai/en/developer/llms/)
- **Postman Collection:** [https://api.paperoffice.ai/latest/docs/postman](https://api.paperoffice.ai/latest/docs/postman) (for Postman / Insomnia / Bruno apps)
- **MCP (canonical DMS):** `https://mcp.paperoffice.ai/dms` · **Claude:** `https://mcp.paperoffice.ai/claude` · **Cursor:** `https://mcp.paperoffice.ai/cursor` · **ChatGPT / OpenAI:** `https://mcp.paperoffice.ai/openai` · **Document AI:** `https://mcp.paperoffice.ai/mcp-document-ai` · **Workflow AI:** `https://mcp.paperoffice.ai/mcp-workflow-ai` · **Full surface (300+):** `https://mcp.paperoffice.ai/mcp-full`. Same Bearer token as REST. Legacy aliases: `/mcp-headless` → `/mcp-document-ai`, `/mcp-headless-plus` → `/mcp-document-workflow-ai`.
- **Get a token:** https://paperoffice.ai

## MCP Server (Model Context Protocol)

PaperOffice exposes a **Streamable HTTP MCP server** at `https://mcp.paperoffice.ai` using the **same Bearer token** as the REST API (`po_sk_`, `po_ut_`, or scoped `po_pk_`). Public marketing claim: **300+ API/MCP-Tools** (do not cite 250/260/350/357/500 or drifting profile integers).

### Connect in 10 seconds (copy the URL into your MCP client)

| AI client | Paste this URL | Tools |
|-----------|----------------|-------|
| **Headless DMS** (canonical) | `https://mcp.paperoffice.ai/dms` | subset of 300+ |
| **Cursor** IDE | `https://mcp.paperoffice.ai/cursor` | subset of 300+ |
| **ChatGPT / OpenAI** MCP | `https://mcp.paperoffice.ai/openai` | subset of 300+ |
| **Full MCP** (300+) | `https://mcp.paperoffice.ai/mcp-full` | 300+ |

**Auth:** same Bearer token as REST (`po_sk_`, `po_ut_`) or OAuth 2.1 on first connect. Public tool-count claim is **300+ API/MCP-Tools** — do not cite drifting profile integers.

**Claude.ai network allowlist:** add `mcp.paperoffice.ai` and `api.paperoffice.ai` (two **f**s — never `paperofice`).

**Example (full DMS):**

```json
{
  "mcpServers": {
    "paperoffice": {
      "url": "https://mcp.paperoffice.ai/dms",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

### Profiles (choose endpoint URL — aligned with Postman / app modules)

| Endpoint | Surface | Purpose |
|----------|---------|--------|
| **`/dms`** | **subset of 300+** | **Canonical headless DMS** — CRUD + capture + workflow + signatures + schema + admin |
| `/claude` | subset of 300+ | *Alias of `/dms`* for Claude Desktop / Claude Code |
| `/mcp-dms-parity` | subset of 300+ | *Technical alias* of `/dms` (parity testing) |
| `/mcp` | subset of 300+ | **Default read-only** — search, get, upload, intelligence (Cursor-safe) |
| `/mcp-document-ai` | subset of 300+ | **Document AI (lighter)** — balanced + DMS CRUD + capture + comments/notes |
| `/mcp-workflow-ai` | subset of 300+ | **Workflow AI** — tasks, HITL, workflow templates, approvals |
| `/mcp-document-workflow-ai` | subset of 300+ | **Document AI + Workflow AI** combined |
| `/mcp-fast` | subset of 300+ | Minimal fast sessions |
| `/mcp-full` | **300+** | All MCP-enabled tools from SOT |
| `/mcp-headless` | subset of 300+ | *Legacy alias* of `/mcp-document-ai` (deprecated) |
| `/mcp-headless-plus` | subset of 300+ | *Legacy alias* of `/mcp-document-workflow-ai` (deprecated) |

**Claude / DocuWare replacement:** connect to `https://mcp.paperoffice.ai/dms` (or `/claude` alias).

### Session concurrency (`tools/call`)

Per MCP session the server allows **parallel read-only tools** (default: 4 idempotent reads, 2 limited reads) and **serial writes** (1, **fail-fast**). Total inflight per session: 8; per account (Bearer): 24. Parallel writes receive immediate `SESSION_BUSY` (`busy_reason: write_queue`, `retry_after_ms: 300`) — do **not** parallelize mutations on one session. On overload: `SESSION_BUSY` / `ACCOUNT_BUSY` with `retry_safe: true`. During deploy: `MCP_MAINTENANCE` with `retry_safe: true`. Discover limits via `GET https://mcp.paperoffice.ai/dms` → `session_concurrency_limits`.

### Custom toolsets (optional on `/mcp`)

Pass header `X-MCP-Toolsets: document-ai-mcp` or query `?toolsets=document-ai-mcp` (curated preset: `balanced` + `dms-core-write` + `dms-capture`). Full DMS preset: `dms` or `dms-parity` (all seven DMS toolsets). Workflow preset: `workflow-ai-mcp`. Combined: `document-workflow-ai`. SOT category toolsets (broader): `document-ai`, `workflow-ai`, `analytics-ai`, `relations-ai`, `data-ai`, `admin`. Legacy aliases `headless` / `headless-plus` remain supported.

### Wishlist aliases (stable tool names)

| Wishlist / DocuWare name | MCP tool_id | Backend |
|--------------------------|-------------|--------|
| `po_documents_update_index` | same | `POST /documents/document-edit/{pofid}` |
| `po_documents_bulk_update` | same | `POST /documents/document-batch-process` |
| `po_job_get` | same | `GET /job/get/{job_id}` |
| `po_ingest_email` | same | `POST /import/import-create` (channel=email) |
| `po_ingest_watchfolder` | same | `POST /import/import-scan` |

### Document AI write tools (dms-core-write)

`po_documents_edit`, `po_documents_rename`, `po_documents_move`, `po_documents_copy`, `po_documents_delete`, `po_documents_restore`, `po_documents_tags_create`, `po_documents_batch_process`, folder tools, `po_document_lists_documents_export`, workspace create/update, **workspace sharing** (create, list, update, revoke, accept/decline, resend/cancel invite, share_info), trash, revisions, legal hold, audit trail, `po_job_get`.

### Workspace external sharing (dms-core-write)

| MCP tool | REST endpoint | Purpose |
|----------|---------------|--------|
| `po_workspaces_share_create` | `POST /paperoffice_account/share_workspace` | Create email/telephony share |
| `po_workspaces_shares_list` | `GET /paperoffice_account/my_shares` | Owner: list shares |
| `po_workspaces_shares_shared_with_me` | `GET /paperoffice_account/shared_with_me` | Recipient inbox |
| `po_workspaces_share_update` | `POST /paperoffice_account/update_share` | Update permissions |
| `po_workspaces_share_revoke` | `POST /paperoffice_account/revoke_share` | Revoke or leave (confirm) |
| `po_workspaces_share_accept` | `POST /paperoffice_account/accept_share` | Accept via token |
| `po_workspaces_share_accept_by_id` | `POST /paperoffice_account/accept_share_by_id` | Accept from inbox |
| `po_workspaces_share_decline` | `POST /paperoffice_account/decline_share` | Decline invitation |
| `po_workspaces_share_resend_invite` | `POST /paperoffice_account/resend_invite` | Resend pending email |
| `po_workspaces_share_cancel_invite` | `POST /paperoffice_account/cancel_invite` | Cancel pending (confirm) |
| `po_workspaces_share_info` | `GET /paperoffice_account/share_info` | Public metadata by token |
| `po_workspaces_external_users_list` | `GET /paperoffice_account/external_users` | Admin: external users |
| `po_workspaces_telephony_agent_get` | `GET /paperoffice_account/workspace_telephony_agent` | Telephony agent read |
| `po_workspaces_telephony_agent_set` | `POST /paperoffice_account/workspace_set_telephony_agent` | Telephony agent set/clear |

Permissions follow the Bearer token (same as UI). Destructive share actions require `confirm=true` on MCP.

### Document AI collaboration (text, not visual stamps)

For agent review loops use **text comments and notes** — not SVG overlays or DocuWare-style stamps.

| Tool | Purpose |
|------|--------|
| `po_documents_comments_create` | Threaded comment on a document; optional `page_number`, `anchor_text` |
| `po_documents_comments_list` | List comments with resolution status |
| `po_documents_comments_resolve` | Mark a comment thread resolved after fix |
| `po_documents_notes_create` | Internal note (`title`, `category`, `is_pinned`) |
| `po_documents_notes_list` | List notes on a document |

Visual annotations in document-edit UI are human-only overlays; API agents should not write coordinate-based stamps.

### Async jobs (OCR, analysis, workflow)

1. `POST /job/add/{pipeline}` with slug form `handler___command` (e.g. `paperoffice_aiocr___generate`)
2. Poll with MCP `po_job_get` or REST `GET /job/get/{job_id}` until `job_status` is `completed`

### Document anonymization / redact (REST + MCP)

Canonical headless flows (same orchestrator policy engine as the app):

| Step | REST | MCP |
|------|------|-----|
| Preview PII | `POST /job/add/workflow` `template=document_anonymize_preview` | `po_anonymization_pii_detect` |
| Apply PDF | `POST /job/add/paperoffice_dataripper___redact_image` | `po_anonymization_redaction_apply` (`preview_job_id`) |
| One-shot PDF | `POST /job/add/workflow` `template=document_anonymize` | `po_anonymization_anonymize` |
| Redact Agent | `POST /documents/redact-agent-run` | `po_documents_redact_agent_run` |

**Key params:** `scenario` (default `gdpr_auskunft`; also `externe_weitergabe`, `finanzdaten`, …), `whitelist`, `custom_redact`, `custom_instructions`, `redact_categories`, `model` (`basic`\|`premium`\|`ultra`). Do **not** use obsolete template `anonymization___request`. Optional workflow finalize: `template=document_anonymize_finalize` — prefer `redact_image` / MCP apply.

### Media AI voice tools (`/mcp-full` utilities)

Available on the full MCP profile and aligned with Postman **Media AI → Voice**.

| MCP tool | REST pipeline | Key parameters |
|----------|---------------|----------------|
| `po_tts_voices_list` | `POST /voice/voices` | `language` (optional filter) |
| `po_tts_generate` | `POST /job/add/paperoffice_voice___tts` | `text`, `voice`, `language`, `quality`, `output` |
| `po_tts_voice_clone` | same URL, upload sample | `text`, `voice_sample_base64`, **`quality`** (`premium`\|`ultra`, default `premium`), **`reference_text`** (transcript — strongly recommended), `language`, `output` |
| `po_tts_multivoice_generate` | same URL, `voice=Multi` | `text` with speaker tags, `language` (required) |
| `po_stt_transcribe` | `POST /job/add/paperoffice_voice___stt` | `audio_base64`, optional `language` |

**Voice clone:** omitting `quality` defaults to `basic` on the API and returns **403** — the MCP tool always sends `quality=premium` unless you set `ultra`. Set `reference_text` to the spoken transcript of `voice_sample_base64` for best clone quality. Poll with `po_jobs_get_job_status_result` when the tool returns an async `job_id`.

### Example MCP client config

```json
{
  "mcpServers": {
    "paperoffice-dms": {
      "url": "https://mcp.paperoffice.ai/dms",
      "headers": { "Authorization": "Bearer po_ut_EXAMPLE_TOKEN_REPLACE_ME" }
    }
  }
}
```

## Authentication

<a id="authentication"></a>

All endpoints require a Bearer Token in the `Authorization` header, except **VISITOR** infra: `/docs/*`, `GET /health`, `GET /ping`, public compliance verify (0 credits on `/docs/*`). Product APIs including `/ip2location/*` and `/currency_exchange/*` always require `po_sk_`, `po_ut_`, or `po_pk_`.

```http
Authorization: Bearer po_sk_EXAMPLE_TOKEN_REPLACE_WITH_YOUR_KEY
```

| Prefix | Type | Usage | Browser-safe? |
|--------|------|-------|---------------|
| `po_sk_` | **Secret Key** | Server-to-server, full access | No — **never** expose in browser code |
| `po_ut_` | **User Token** | User-scoped, tier-limited | No — never expose in browser code |
| `po_pk_` | **Publishable Key** | Browser/AI-Artifact direct calls | **Yes** — scoped, budget-limited, origin-locked |

### HTTP methods (PaperOffice convention)

PaperOffice is **not** a strict REST CRUD API. Most mutations use **`POST`** with action-style paths (`template-delete`, `import-delete`, tag/note removal, …). The only standard **`DELETE`** in the public surface is `DELETE /documents/document-delete` — do not assume REST-style `DELETE` elsewhere.

## Request bodies (JSON and multipart)

Most `POST` endpoints accept **either** `application/json` **or** `multipart/form-data` with the same field names. JSON fields override duplicate form keys. Exceptions are noted per endpoint.

**Notable exception:** `POST /job/add/workflow` accepts **multipart `file` or `pofid` only** — JSON `files` URL arrays are **not** supported (unlike most `/job/add/{pipeline}` endpoints).

<a id="document-ids-pofid"></a>
<a id="pipeline-routing"></a>

## Response envelopes

Success payloads are **not** uniform across the API: some endpoints return top-level IDs (`note_id`), others nest under `workspace`, `results[]`, or async `job` objects. Use the per-endpoint response schema below — do not assume one global wrapper.

**`_billing` variants:** (1) **Standard** — `_billing.credits.total_monthly` / `remaining_monthly`; (2) **Free info** — `_billing.plan.tier` = `FREE_ENDPOINT`, `credits.used` = 0 (e.g. `workflow_tasks/list`, `voices_info`); (3) **Legacy flat** — `credits: null` with `remaining_credits` / `total_monthly` at `_billing` top level (some template list routes). See **Response Format** below for examples.

**MCP / `tools/call`:** Full `_billing` is replaced by **`_billing_summary`** (`credits_billed`, `remaining_credits`, `remaining_scope`=`prepaid_monthly_pool`, `total_monthly`, `plan_tier`, `job_name`; when present: `overage_can_continue`, `overage_funding_healthy`, `overage_alarm_kind`) — no tokens, IPs, or wallet amounts. Query balance before expensive work: `GET /billing/credits/balance` (`po_billing_credits_balance_get`), `GET /billing/status` (`po_billing_status_get`), usage audit: `GET /billing/usage-detail` (`po_billing_usage_detail_get`). Requires `po_sk_` or `po_ut_` (not `po_pk_`).

### Publishable Keys (po_pk_) — Browser-Direct Calls

<a id="publishable-keys"></a>

Publishable Keys let you **call the PaperOffice API directly from the browser** — from Claude Artifacts, ChatGPT Canvas, Gemini, Grok, or your own web app — without a server. They are Stripe-style: safe to embed in frontend code because they are scope-limited, budget-capped, rate-limited and origin-locked.

**Security model (hardcoded, not overridable):**

- `DELETE` is **never** allowed (only `GET`/`POST`/`PUT`/`PATCH`, default `GET`+`POST`)
- Admin/auth/billing/webhook/oauth endpoints are **always blocked** (regardless of scope)
- Every request must include an `Origin` header matching the token's allowlist (exact host or subdomain wildcard, e.g. `https://*.example.com` includes `example.com` and all subdomains)
- A lifetime **credit budget** caps total spend — exhausted = 402
- A per-minute **rate limit** protects against burst-abuse — exceeded = 429
- Max TTL: 365 days. Max budget: 100000 Credits. Max rate: 600 req/min.

**Create a Publishable Key:** In the PaperOffice app go to **Account → API**, choose **Publishable Key (po_pk_)**, set allowed origins and credit budget, then copy the token once.

**Use the Publishable Key from the browser:**

```javascript
const form = new FormData();
form.append('source_url', 'https://api.paperoffice.ai/latest/download/demo/demo_invoice.pdf');
form.append('processing_lane', 'instant');
form.append('client_wait', 'true');
const response = await fetch('https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer po_pk_EXAMPLE_REPLACE_ME' },
  body: form
});
const data = await response.json();
```

**Manage tokens:** Create, list, rotate, and revoke Publishable Keys in the PaperOffice app under **Account → API** (not listed in this public endpoint export).

**Error codes specific to Publishable Keys:**

| HTTP | Code | Meaning |
|------|------|---------|
| 402 | `BUDGET_EXHAUSTED` | Token credit budget reached — raise `credit_budget_ceiling` or create a new token |
| 403 | `METHOD_FORBIDDEN_FOR_BROWSER` | `DELETE` is hardcoded-blocked for all `po_pk_` |
| 403 | `METHOD_NOT_IN_ALLOWLIST` | HTTP method not in `allowed_http_methods` |
| 403 | `SCOPE_NOT_GRANTED` | Token lacks the scope required for this endpoint |
| 403 | `ORIGIN_HEADER_REQUIRED` | Missing `Origin` header (no server-to-server) |
| 403 | `DOMAIN_NOT_ALLOWED` | Origin not in token's allowlist |
| 400 | `ORIGINS_REQUIRED` | No origin allowlist provided when creating/updating a Publishable Key |
| 400 | `ORIGINS_INVALID` | Malformed origin pattern (use `https://host` or `https://*.example.com`) |
| 403 | `ENDPOINT_HARDCODED_FORBIDDEN` | Admin/auth/billing endpoint — always blocked |
| 404 | `ENDPOINT_NOT_FOUND_IN_REGISTRY` | Endpoint not in API registry (no `browser_scope`) |
| 404 | `ENDPOINT_NOT_BROWSER_ENABLED` | Endpoint exists but no `browser_scope` assigned (destructive/admin) |
| 429 | `RATE_LIMIT_EXCEEDED` | `rate_limit_per_minute` hit — wait until next minute |

## Job workflow (Hybrid Client-Wait)

<a id="job-workflow-hybrid-client-wait"></a>
<a id="priority-jobs"></a>

**Default:** `client_wait=true` — API holds the HTTP connection while the job runs (dynamic timeout per pipeline/lane/pages; typically 20s–several minutes, infrastructure cap about 295s). Returns the result inline or HTTP 202 with `poll_url` and `max_wait_seconds`.

**Force async:** `client_wait=false` or `async_only=true` — immediate `job_id`, then:
1. `POST /job/add/{pipeline}` → `{ "job_id": "abc123" }`
2. `GET /job/get/{job_id}` → poll until `job_status` is `completed` — **JSON result is here**
3. (Optional) `GET /job/download/{token}` — only when `job_result` contains a file URL (not part of Quickstart ①–④)

`processing_lane` is the Start-SLA (wait-to-start): `no_sla`|`sla_24h`|`sla_12h`|`sla_6h`|`sla_1h`|`instant`. Omit = workspace default / fair-use. Guarantee = start, not completion. Separate from inline wait. Legacy `priority` remains for compatibility; lane wins when both are sent.

**HTTP 202** is success-path continuation, not an error: the client-wait window ended while the job is still running. Follow `poll_url` or `GET /job/get/{job_id}` until `job_status` is `completed`. See `max_wait_seconds` in the 202 body.

### Job pipeline URL slugs

The path segment after `/job/add/` must be the **queue job name** in `handler___command` form (triple underscore `___`), e.g. `paperoffice_aiocr___generate`. Dot notation (`handler.command`) returns HTTP 400 (`JOB_CONFIG_INVALID`). Labels such as **API reference:** `po-*` in endpoint sections are documentation identifiers only — they are **not** valid pipeline slugs. Use `_billing.job.api_job_name` from a prior response when unsure.

Handwriting, government forms, and US tax forms use `POST /job/add/paperoffice_aiocr___generate` (vision / form OCR). Structured IDP (invoices, IDs, DATEV, contracts, and similar) uses `POST /job/add/workflow` with an IDP agent. These are two different pipelines — not aliases.

List prices start at **Basic** (about €0.01 OCR / ~€0.03 IDP). **Premium** and **Ultra** lanes are higher (indicatively 4 ct / 10 ct). Exact rates: https://paperoffice.ai/en/pricing/ and `GET /billing/plans`.

## Response Format

<a id="response-format"></a>

All responses are JSON. On success, `status` is `"success"`. Most REST endpoints return endpoint-specific fields at the **top level** (not wrapped in `data`). Exceptions:

| Pattern | Where | Key fields |
|---------|--------|------------|
| Standard REST | documents, analytics, utilities, … | top-level fields + `status` |
| Job submit (sync complete) | `POST /job/add/{pipeline}` | `status`, `job_id`, **`result`** |
| Job poll | `GET /job/get/{job_id}` | envelope `status`, **`job_status`**, **`job_result`** |
| Account / workspace resources | e.g. `workspace_telephony_agent` | **`data`** object + `status` |

Many billed calls also include `_billing` and `processing_time`.

**`_billing` shapes (three variants):**

| Variant | When | `credits` shape |
|---------|------|-----------------|
| **Standard** | Most billed REST/job endpoints | `{ "total_monthly", "remaining_monthly", "credit_source", … }` |
| **Free info** | e.g. `workflow_tasks/list`, `voices_info`, `model_info` | `{ "used": 0, "remaining": null, "monthly": null }` + `plan.tier: "FREE_ENDPOINT"` |
| **Legacy flat** | Some template/list handlers | top-level `credits: null` with `remaining_credits` / `total_monthly` siblings |

Do not assume one JSON Schema for `_billing` across all endpoints — inspect the live response per route.

```json
{
  "status": "success",
  "partners": [],
  "processing_time": "123.45ms",
  "_billing": { "credits": { "remaining_monthly": 1000 } }
}
```

Errors use HTTP 4xx/5xx. Most handlers return `status`, `code`, and `message`; some also include `error`, `error_code`, or `example_curl` — treat any of these as machine-readable failure signals.

**Localization:** The `message` field may reflect the account locale (for example German text while reading English docs). **Clients must branch on stable `code` values** (English, documented below) — never parse or assert exact `message` strings.

```json
{
  "status": "error",
  "code": "AUTH_REQUIRED",
  "message": "Authentication required. Please provide a valid Bearer token.",
  "processing_time": "12.34ms"
}
```

Job endpoints may return `job_id`, `poll_url`, or HTTP `202` when client-wait times out — see **Job workflow** above. Use the `job_id` from step ③ when polling in step ④.

## Standard Error Codes

<a id="standard-error-codes"></a>

Canonical codes below; some legacy aliases may still appear in older clients (`AUTH_REQUIRED` ≈ `NOT_AUTHENTICATED`, `INVALID_REQUEST` ≈ `BAD_REQUEST`, `NOT_FOUND` ≈ `UNKNOWN_API_ENDPOINT`).

| HTTP | Code | Meaning |
|------|------|---------|
| 400 | `BAD_REQUEST` / `INVALID_REQUEST` | Missing/invalid parameters |
| 400 | — | Wrong HTTP method on a POST-only endpoint (API returns 400, not HTTP 405) |
| 400 | `MISSING_PARAMETER` / `MISSING_QUERY` | Required query or body field missing |
| 400 | `INVALID_QUERY` | Search/query syntax not supported (e.g. wildcard-only) |
| 400 | `INPUT_TOO_LARGE` | Input exceeds endpoint limit (e.g. 15k chars for /translate/text) |
| 401 | `NOT_AUTHENTICATED` / `AUTH_REQUIRED` | Invalid or missing Bearer on endpoints that require a **known** token |
| 401 | `TOKEN_NOT_FOUND` | Unknown or revoked API token |
| 401 | `INVALID_TOKEN` | Malformed or expired token |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits |
| 403 | `TIER_RESTRICTED` | **No Bearer at all** on a product API — VISITOR tier (not the same as 401) |
| 403 | `UI_ONLY_ENDPOINT` | Allowed only via PaperOffice web UI (browser session) |
| 404 | `NOT_FOUND` / `UNKNOWN_API_ENDPOINT` | Endpoint or resource not found |
| 404 | `DOCUMENT_NOT_FOUND` | Document ID/POFID not found |
| 429 | `RATE_LIMIT_EXCEEDED` | Retry after `Retry-After` header |
| 500 | `INTERNAL_ERROR` / `GENERAL_ERROR` | Retry with exponential backoff |
| 500 | `TRANSLATION_FAILED` | LLM pipeline failure (endpoint-specific, e.g. /translate/text) |

## UI-only operations (security policy)

These destructive/compliance actions are **not** available via REST, MCP, or Postman — only through the PaperOffice web app with a browser session: **workspace delete**, **empty trash**, **legal hold release**. API calls return HTTP `403` with code `UI_ONLY_ENDPOINT`. Legal holds can be **placed** via `POST /documents/document-legal-hold`; release requires the UI.

## Trash and restore (tier-dependent)

Move-to-trash, restore, and trash listing require `trash_enabled: true` on the account/workspace tier. On tiers without trash, `DELETE /documents/document-delete` performs permanent deletion (POST alias accepted for legacy clients). Before `POST /documents/document-restore`, check `GET /documents/trash-settings` and `GET /documents/workspaces-list` (field `_capabilities.trash_enabled`) — restore on tiers without trash returns HTTP `404`.

## Rate Limits

Per-token (authenticated) or per-IP (visitor). Minimum limits (all tiers): 5/sec, 30/min, 100/hr, 500/day. Paid tiers get higher limits. Check `RateLimit-*` and `X-RateLimit-*` response headers.

## Billing semantics

- **`_billing.credits`:** `total_monthly` is the plan baseline; `remaining_monthly` may exceed it when carryover, promotional grants, or unlimited-tier metering apply — do not assume `remaining_monthly <= total_monthly`.
- **HTTP 400 validation:** Most endpoints bill only after successful handler work. Some high-abuse endpoints (e.g. `GET /analytics/workspaces-compare` without required parameters) may deduct the **minimum 1 credit** on client validation failures (anti-abuse). Check `_billing.job.credits_billed` (top-level alias `_billing.credits_billed` when present) on every billed response.

## API Endpoints (Full Reference)

### Job routing pattern — `POST /job/add/{pipeline}`

`POST https://api.paperoffice.ai/latest/job/add/{pipeline}` submits asynchronous AI work. Replace `{pipeline}` with the queue job name in `handler___command` form (triple underscore `___`), e.g. `paperoffice_aiocr___generate`.

#### Overview

Use this URL pattern for OCR, IDP, voice, image, and workflow jobs. Named endpoints in this spec document each concrete pipeline slug; the Postman collection also provides **③ Submit your first job** with `{{pipeline}}`.

#### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `{pipeline}` (path) | string | yes | Full pipeline slug, e.g. `paperoffice_aiocr___generate` |
| `client_wait` | boolean | no | Default `true` — hold connection for inline result |
| `processing_lane` | string | no | Start-SLA lane (omit = workspace default / fair-use) |
| `priority` | integer | no | Legacy queue priority (compat; lane wins) |
| `file` / `source_url` | file / string | varies | Document input — see each pipeline section |

#### Responses

- **200** — result inline when the job completes within the hold window
- **202** — `job_id` + `poll_url` when hold is exceeded — poll with `GET /job/get/{job_id}`
- **400** — invalid pipeline slug or body (`JOB_CONFIG_INVALID`)

---

### Workflow legacy route aliases (no separate Postman items)

These paths are **runtime aliases** — they are not duplicated as standalone Postman requests:

| Legacy alias | Canonical endpoint | Notes |
|--------------|-------------------|-------|
| `GET https://api.paperoffice.ai/latest/workflow/user_list` | `GET /workflow/system_list` | Same handler; prefer `system_list` in new integrations |
| `GET https://api.paperoffice.ai/latest/workflow/system_get` | `GET /workflow/system_list` + `template_id` filter | Fetch one system workflow by ID from the list payload |

The Postman collection documents **`GET /workflow/system_list`** and **`POST /workflow_templates/list`**; use those for discovery.

---

---

## Analytics AI — Analytics & BI

### Get activity heatmap

`GET https://api.paperoffice.ai/latest/analytics/activity-heatmap`

#### Overview
Activity heatmap — daily upload/change intensity over a year (or selected window) for capacity planning. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-heatmap-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `year` | number | No | Year (default: current year) |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get analytics overview

`GET https://api.paperoffice.ai/latest/analytics/overview`

#### Overview

Dashboard KPIs for the document estate — document counts, storage usage, DMS distribution, and high-level activity indicators. Use as the first call when building an operations dashboard. Combine with `GET /analytics/trends` for time series. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

Use query parameters such as `workspace_id` and supported date filters.

**API reference:** `po-analytics-overview-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get audit center findings

`GET https://api.paperoffice.ai/latest/analytics/audit-center`

#### Overview
Workflow audit center — compliance-oriented findings with severity (low/medium/high/critical) and review flags. Monitoring view for potential compliance issues (GDPR/GoBD-oriented signals) — not a legal certification. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-audit-center-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Max results (1-500) (default: 100) |
| `offset` | number | No | Pagination offset (default: 0) |
| `severity` | string | No | Filter by severity (allowed: low, medium, high, critical) |
| `require_review` | boolean | No | Only entries requiring review |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get contact financial statistics

`GET https://api.paperoffice.ai/latest/analytics/contact-stats-financial`

#### Overview
Financial statistics for business contacts (slow endpoint — typically 10–30 seconds).

Use a client timeout of at least **35 seconds** and keep `limit` modest (e.g. `10`) on large estates.

## Performance
Large accounts may need **10–30 seconds**. Use `limit` / `page` query parameters for interactive use (recommended: `limit=10`). This endpoint performs heavy aggregation and is not cached.

**API reference:** `po-analytics-contacts-financial-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Max contacts to return (1-500). Should match contact-stats limit when merging client-side. (default: 50) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get contact statistics

`GET https://api.paperoffice.ai/latest/analytics/contact-stats`

#### Overview
Business partner / contact statistics — document counts, storage, first/last document dates, and optional addresses (`include_addresses=true`).

**Financial amounts are not included** — call `GET /analytics/contact-stats-financial` separately when invoice totals per contact are needed (expensive aggregation).

**Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant).

**API reference:** `po-analytics-contacts-stats-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Max results (1-500) (default: 50) |
| `period` | string | No | Time period (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |
| `include_addresses` | boolean | No | Include address data |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document activity history

`GET https://api.paperoffice.ai/latest/analytics/activity-document`

#### Overview
Complete activity history for a **single document** — revisions, processing events, and user actions where logged. Requires a document identifier (`pofid` or `documents_id`). **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-document-activity-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | One of (`documents_id`, `pofid`) | POFID of the document (required unless documents_id is provided). |
| `documents_id` | string or number | One of (`documents_id`, `pofid`) | Numeric document ID (required unless pofid is provided). |

#### Required alternatives

Provide **at least one** of: `documents_id` **or** `pofid`.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document distribution stats

`GET https://api.paperoffice.ai/latest/analytics/distribution`

#### Overview
Document distribution breakdown — by document type, workspace, processing state, or other dimensions available in your estate. Helpful for portfolio analysis and data-quality reviews before BI exports. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-distribution-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Distribution criterion (allowed: document_type, workspace, dms_tier, file_extension) (default: "document_type") |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document trends

`GET https://api.paperoffice.ai/latest/analytics/trends`

#### Overview
Time-based trends — upload volume, processed pages, storage growth, and related metrics over a selectable period. Parameterize with `period` (e.g. `7d`, `30d`, `1y`) and optional `workspace_id` for scoped tenants. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-trends-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |
| `group_by` | string | No | Grouping (allowed: day, week, month) (default: "day") |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get financial flow analytics

`GET https://api.paperoffice.ai/latest/analytics/financial-flow`

#### Overview
Cash-flow style analysis — money movement between business partners (Sankey-style aggregates) for the selected period. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-financial-flow-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get financial summary

`GET https://api.paperoffice.ai/latest/analytics/financial-summary`

#### Overview

Financial summary — incoming/outgoing invoice totals, top partners, and period aggregates derived from extracted document fields. Not a certified accounting ledger — use for operational BI; validate totals against source documents when required. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

**API reference:** `po-analytics-financial-summary-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get meta field analysis

`GET https://api.paperoffice.ai/latest/analytics/meta-fields-analysis`

#### Overview
Meta-field coverage analysis across documents (slow endpoint — typically 10–30 seconds).

Use a client timeout of at least **35 seconds** and a conservative `limit` on large workspaces.

## Performance
Large accounts may need **10–30 seconds**. Use `limit` / `page` query parameters for interactive use (recommended: `limit=10`). This endpoint performs heavy aggregation and is not cached.

**API reference:** `po-analytics-meta-fields-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get overdue financial items

`GET https://api.paperoffice.ai/latest/analytics/financial-overdue`

#### Overview
Overdue invoices — documents past due date with amounts, aging buckets, and partner references where extracted. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-financial-overdue-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get upcoming due dates

`GET https://api.paperoffice.ai/latest/analytics/calendar-due-dates`

#### Overview
Upcoming and past due dates from documents — invoice due dates, contract deadlines, recall dates, and similar date-driven workflows. **Permissions:** Requires Analytics AI module access on the bearer token.
**Scope:** Single PaperOffice account (tenant). Pass `workspace_id` for sub-users.

#### Request parameters
**API reference:** `po-analytics-due-dates-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `year` | number | No | Year (default: current year) |
| `show_overdue` | boolean | No | Include overdue entries (default: true) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get user activity ranking

`GET https://api.paperoffice.ai/latest/analytics/activity-users`

#### Overview

Rank users by **uploads and document revisions** in the selected time period (not login events). **Scope:** Single PaperOffice account (tenant). Optional `workspace_id` limits activity to one workspace; omit for account-wide rankings (root/administrator). **Sub-users must pass `workspace_id`.** **Permissions:** Analytics AI module — requires module access on the bearer token (account administrator or granted Analytics AI access). This is a team-usage insight endpoint, not workspace-Admin only. **Related:** `GET /analytics/overview`, `GET /analytics/trends`, `GET /analytics/distribution`.

**API reference:** `po-analytics-user-activity-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period for activity counters (allowed: 7d, 30d, 90d, 365d, all) (default: "30d") |
| `workspace_id` | number | No | Optional workspace filter (required for sub-users). Omit for account-wide scope (root/administrator only). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get embedding clusters

`GET https://api.paperoffice.ai/latest/analytics/embeddings-clusters`

#### Overview
Returns embedding counts grouped by type (summary, page, paragraph, entity, metadata). For semantic document grouping use advanced search with `mode=semantic`.

#### Request parameters
**API reference:** `po-embeddings-clusters-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get embedding statistics

`GET https://api.paperoffice.ai/latest/analytics/embedding-stats`

#### Overview
Embedding statistics — count per type, coverage rate, average quality. Shows semantic index processing status.

#### Request parameters
**API reference:** `po-embeddings-stats-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get embedding topics

`GET https://api.paperoffice.ai/latest/analytics/embeddings-topics`

#### Overview
Topic distribution based on embeddings — how documents are distributed across detected topics. Shows confidence scores.

#### Request parameters
**API reference:** `po-embeddings-topics-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get entity network graph

`GET https://api.paperoffice.ai/latest/analytics/entities-network`

#### Overview
Entity network graph — connections between persons, companies, and organizations based on shared documents. Returns nodes and edges for interactive graph visualization.

#### Request parameters
**API reference:** `po-entities-network-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Filter by entity type: person, company, location, amount, date, email, phone, iban, invoice_number, contract_number (also accepts PERSON, ORGANIZATION, LOCATION) |
| `limit` | number | No | Max nodes (1-500) (default: 100) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Compare workspaces

`GET https://api.paperoffice.ai/latest/analytics/workspaces-compare`

#### Overview
Compare workspaces side by side — document count, storage, pages, AI processing rate.

#### Request parameters
**API reference:** `po-workspaces-compare` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_ids` | string | Yes | Comma-separated Workspace IDs (e.g. "1,2,3") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Analytics AI — Knowledge Graph

### Get business case graph

`GET https://api.paperoffice.ai/latest/knowledge_graph/business_case`

#### Overview
Business case analysis — all documents belonging to a reference/transaction (invoice number, order number, contract). Shows timeline, graph and involved partners.

#### Request parameters
**API reference:** `po-knowledge-graph-business-case-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `reference` | string | Yes | Reference/transaction number (e.g. invoice number, order number, contract number) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document relations (path param)

`GET https://api.paperoffice.ai/latest/document_intelligence/relations/{pofid}`

#### Overview
Get document relationships — references, supersedes, attachment_of, invoice_for, payment_for, contract_with. Shows linked documents and relation type. Use `include_all_sources=true` to include all detection sources (default: user-facing relations only).

#### Request parameters
**API reference:** `po-knowledge-graph-document-relations-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `direction` | string | No | outgoing, incoming, or both |
| `limit` | string | No | Max relations (max: 100) |
| `include_all_sources` | boolean | No | Include all relation sources (default: false = user-visible relations only). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document timeline

`GET https://api.paperoffice.ai/latest/knowledge_graph/timeline`

#### Overview
Chronological timeline — documents and events sorted by date, filterable by partner and workspace.

#### Request parameters
**API reference:** `po-knowledge-graph-timeline-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Limit to workspace |
| `partner` | string | No | Filter by business partner |
| `from` | string | No | Start date (YYYY-MM-DD) |
| `to` | string | No | End date (YYYY-MM-DD) |
| `limit` | number | No | Max results (1-200) (default: 50) |
| `offset` | number | No | Pagination offset (default: 0) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get image embeddings

`GET https://api.paperoffice.ai/latest/document_intelligence/image_embeddings/{documents_id}`

#### Overview
Get image embeddings of a document — visual representations of logos, stamps, signatures, page previews. Enables visual similarity search. NOTE: Requires AI-DMS tier "ultra" and documents with detected visual elements (logos, stamps, signatures). Returns empty for documents without visual elements or lower DMS tiers.

#### Request parameters
**API reference:** `po-intelligence-image-embeddings-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documents_id` | string or number | Yes (path) | Document ID (numeric, from po_documents_search) |
| `type` | string | No | Element type: logo, picture, stamp, signature, page |
| `include_snippets` | boolean | No | Include WebP preview images |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get intelligence statistics (Document AI)

`GET https://api.paperoffice.ai/latest/document_intelligence/stats`

#### Overview
Get global Document Intelligence statistics — total entities, embeddings, relations, topics, vision analyses. Shows AI processing status.

#### Request parameters
**API reference:** `po-intelligence-stats-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get knowledge graph document entities

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/{pofid}`

#### Overview
Returns all extracted entities for a document — companies, persons, amounts, dates, locations, IBANs, products, and custom types. Requires prior Document AI / IDP processing.

#### Request parameters
**API reference:** `po-knowledge-graph-document-entities-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_relations` | string | No | Include entity-entity relations |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get knowledge graph for document (path param)

`GET https://api.paperoffice.ai/latest/document_intelligence/knowledge_graph/document/{pofid}`

#### Overview
Returns an interactive graph centered on one document — nodes, edges, group styling, and layout options.

#### Request parameters
**API reference:** `po-knowledge-graph-document-graph-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `depth` | string | No | Hop depth 1-3 (3 requires ULTRA) |
| `include_entities` | string | No | Include entity nodes (companies, persons, etc.) |
| `max_nodes` | string | No | Maximum nodes to return (max: 200) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get knowledge graph statistics (KG counts)

`GET https://api.paperoffice.ai/latest/knowledge_graph/stats`

#### Overview
Returns knowledge graph statistics — document, relation, and entity counts, breakdowns by relation and entity type, and available feature flags for the workspace.

#### Request parameters
**API reference:** `po-knowledge-graph-stats-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | No | Optional: Filter by workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get knowledge graph universe

`GET https://api.paperoffice.ai/latest/knowledge_graph/universe`

#### Overview

Sampled knowledge-graph view for visualization — **not** an unbounded export of every document. **Scope:** Single PaperOffice account (tenant), never cross-tenant. Without `workspace_id`, nodes are sampled from all workspaces of the account (newest documents first, capped by `max_nodes`). **Sub-users must pass `workspace_id`.** **Limits:** `max_nodes` default **100**, maximum **300**. Toggle layers with `include_embeddings`, `include_entities`, `include_relations`. Use `compact=true` to reduce payload size. **Performance:** Prefer a specific `workspace_id` on large estates; increase `max_nodes` only when needed.

**API reference:** `po-knowledge-graph-universe-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Limit graph to one workspace (required for sub-users). |
| `max_nodes` | number | No | Maximum graph nodes sampled (1–300, default 100). (default: 100) |
| `similarity_threshold` | number | No | Embedding similarity threshold (0.0–1.0). (default: 0.65) |
| `include_embeddings` | boolean | No | Include embedding similarity edges. (default: true) |
| `include_entities` | boolean | No | Include entity nodes. (default: true) |
| `include_relations` | boolean | No | Include document relation edges. (default: true) |
| `compact` | boolean | No | Compact mode: strip verbose node/edge metadata (about 70% smaller). (default: false) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get partner graph detail

`GET https://api.paperoffice.ai/latest/knowledge_graph/partner/{partner_name}`

#### Overview
Detailed view of a single business partner — all documents, business cases, graph connections, statistics. 360-degree partner view.

#### Request parameters
**API reference:** `po-knowledge-graph-partner-detail-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `partner_name` | string | Yes (path) | Business partner name (exact or similar) |
| `workspace_id` | number | No | Limit to workspace |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get publisher profile

`GET https://api.paperoffice.ai/latest/document_intelligence/publisher/{documents_id}`

#### Overview
Detect the sender/publisher of a document from logos, letterheads, and metadata. Returns company name, logo URL, aliases, and industry when available.

#### Request parameters
**API reference:** `po-intelligence-publisher-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documents_id` | string or number | Yes (path) | Document ID (numeric, from po_documents_search) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get workspace knowledge graph (path param)

`GET https://api.paperoffice.ai/latest/document_intelligence/knowledge_graph/workspace/{workspace_id}`

#### Overview
Returns an interactive graph for an entire workspace — all documents and their relationships with the same node/edge structure as the document graph endpoint.

#### Request parameters
**API reference:** `po-knowledge-graph-workspace-graph-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_entities` | string | No | Include entity nodes |
| `max_nodes` | string | No | Maximum graph nodes (default 100, maximum 300 per request). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List document topics

`GET https://api.paperoffice.ai/latest/document_intelligence/topics`

#### Overview
List document topics in the account — finance, contracts, HR, legal, projects, customers, suppliers — with document counts per topic.

#### Request parameters
**API reference:** `po-intelligence-topics-list` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Limit to workspace |
| `include_documents` | boolean | No | Include document IDs per topic |
| `limit` | number | No | Max results (default: 20) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List knowledge graph business partners

`GET https://api.paperoffice.ai/latest/knowledge_graph/partners`

List business partners extracted from the knowledge graph — companies and persons linked across documents, with relationship strength and document counts.

#### Overview
Returns partner nodes aggregated from document intelligence and graph read models. Use filters for entity type, sort order, and limits. Responses include partner identifiers, display names, document counts, and optional financial aggregates when meta fields are present.

**API reference:** `po-knowledge-graph-partners` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | Max number of partners (default: 50). |
| `sort_by` | string | No | sorting (allowed: document_count, total_amount, name) |
| `entity_type` | string | No | Filter by type (allowed: company, person, all) |
| `workspace_id` | integer | No | Optional workspace filter. |
| `query` | string | No | Optional name filter (substring match). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List knowledge graph types

`GET https://api.paperoffice.ai/latest/knowledge_graph/types`

#### Overview
Available relationship, document and reference types in the knowledge graph. Schema/vocabulary reference.

#### Request parameters
**API reference:** `po-knowledge-graph-types-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List publishers

`GET https://api.paperoffice.ai/latest/document_intelligence/publishers`

#### Overview
List all automatically detected publishers/senders across all documents. Shows frequency, industry and logo.

#### Request parameters
**API reference:** `po-intelligence-publishers-list` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Max results (1-500) (default: 50) |
| `offset` | number | No | Pagination offset (default: 0) |
| `search` | string | No | Search publisher name |
| `industry` | string | No | Filter by industry |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List reference numbers

`GET https://api.paperoffice.ai/latest/knowledge_graph/references`

#### Overview
Reference network — all detected reference numbers (invoice, order, contract numbers) and how many documents they connect.

#### Request parameters
**API reference:** `po-knowledge-graph-references-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Limit to workspace |
| `type` | string | No | Reference type: invoice_number, order_number, contract_number |
| `limit` | number | No | Max results (1-500) (default: 100) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Search entities across documents

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/search`

#### Overview
Search for entities (companies, persons, IBANs, amounts, etc.) across all documents. Uses the entity index automatically built from your documents by the Document Intelligence pipeline.

#### Request parameters
**API reference:** `po-intelligence-entities-search` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term (Firmenname, Person, IBAN, etc.) |
| `entity_type` | string | No | Filter by entity type (allowed: company, person, iban, amount, reference, address, email, phone, date, all) |
| `limit` | integer | No | Max. results (default: 20) |
| `type` | string | No | Entity type filter (e.g. person, organization, location). |
| `workspace_id` | integer | Yes | Workspace ID to scope entity search. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — Currency Exchange

### Convert currency

`POST https://api.paperoffice.ai/latest/currency_exchange/convert`

#### Overview
Convert an amount between two currencies using current exchange rates from the PaperOffice currency service.

#### Request parameters
**API reference:** `po-currency-convert-currency` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | Yes | Source currency code (ISO 4217, e.g. EUR). |
| `to` | string | Yes | Target currency code (ISO 4217, e.g. USD). |
| `amount` | number | No | Amount to convert (default: 1). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get currency exchange rates

`GET https://api.paperoffice.ai/latest/currency_exchange/get_rates`

#### Overview
Get current exchange rates for supported currency pairs. Base currency and quote symbols are configurable.

#### Request parameters
**API reference:** `po-currency-get-exchange-rates` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from` | string | No | Base currency code (ISO 4217) |
| `amount` | string | No | Base amount (default: 1) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — Geocoding

Address and place lookup (`/geocoding/*`). Distinct from IP geolocation (`/ip2location/*`) and from weather.

### Forward geocoding

`POST https://api.paperoffice.ai/latest/geocoding/forward`

#### Overview
Forward geocoding: resolve a street address or place name to latitude/longitude coordinates.

#### Request parameters
**API reference:** `po-geocoding-forward` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `address` | string | Yes | Full or partial address in any language/script (default: "東京都渋谷区") |
| `lang` | string | No | Response language de, en, ja, ru, ar, zh, etc. (default: "ja") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get geocoding service status

`GET https://api.paperoffice.ai/latest/geocoding/status`

#### Overview
Geocoding service health. Success uses `status: "operational"` (not the generic `status: "success"` envelope).

**API reference:** `po-geocoding-service-status` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Reverse-geocode coordinates

`GET https://api.paperoffice.ai/latest/geocoding/reverse`

#### Overview
Resolves **GPS coordinates** to a human-readable address.

Use **Tool-ID** `po_geocoding_reverse`. For address → coordinates use `po_geocoding_forward` (`POST /geocoding/forward`).

## Required query parameters
- **lat** — latitude (e.g. `52.52`)
- **lng** — longitude (e.g. `13.405`; API alias: `lon`)

Optional: **lang** — response language.

## Example

`GET /geocoding/reverse?lat=52.52&lng=13.405&lang=de`

## Error example (HTTP 400)

```json
{
"success": false,
"error": "MISSING_COORDINATES",
"message": "Parameters \"lat\" and \"lng\" (or \"lon\") are required"
}
```

**API reference:** `po-geocoding-reverse` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90). |
| `lng` | number | Yes | Longitude (-180 to 180). Alias: lon on the API. |
| `lang` | string | No | Response language (e.g. de, en). (default: "de") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — IP Geolocation

IP-derived location. **IP-based weather** is `/ip2location/weather`. City/GPS weather lives under **Data AI — Weather** (`/weather`, `/location2weather`).

### Detect IP VPN usage

`POST https://api.paperoffice.ai/latest/ip2location/vpn`

#### Overview
Detect VPN, proxy, and hosting-provider usage for an IP address. Returns confidence and provider metadata.

#### Request parameters
**API reference:** `po-ip-geolocation-vpn-detection` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IPv4 or IPv6 address to look up. Omit to use the caller's IP address. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get IP device fingerprint

`POST https://api.paperoffice.ai/latest/ip2location/device`

#### Overview

Analyzes device/browser signals and returns a device fingerprint hash plus risk indicators.

**Response scores (0–100):**
- `confidence_score` — match confidence for the fingerprint (higher = more confident identification).
- `trust_score` — trustworthiness of the session (higher = lower estimated fraud risk; computed as inverse of internal risk score).

Use both scores together with IP geolocation and VPN detection for layered fraud checks.

**Auth:** Requires `po_sk_` or `po_ut_` Bearer token.

**API reference:** `po-ip-geolocation-device-fingerprint` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IP address to analyze for device fingerprint |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get IP full information

`GET https://api.paperoffice.ai/latest/ip2location/full`

#### Overview
Resolve complete IP geolocation and ISP data for an IPv4/IPv6 address.

Send `ip` as a query parameter. Returns country, region, city, coordinates, ASN, and ISP fields when available.

**API reference:** `po-ip-geolocation-full-all-information` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IP address to look up. If omitted, the callers IP is used. |
| `locale` | string | No | Response locale (en, de, fr, es, etc.) (default: "en") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get IP location only

`POST https://api.paperoffice.ai/latest/ip2location/location`

#### Overview
Resolve basic location data for an IP address (country, region, city).

Send `ip` in the JSON body or as a form field. Lightweight Alternative to `GET /ip2location/full`.

**API reference:** `po-ip-geolocation-location` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | IPv4 or IPv6 address to look up. Omit to use the caller's IP address. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List IP countries

`POST https://api.paperoffice.ai/latest/ip2location/countrylist`

#### Overview
Get list of all supported countries with basic info. Returns: - Country codes ISO 2-letter - Country names - Currency codes - Primary languages

#### Request parameters
**API reference:** `po-ip-geolocation-country-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `language` | string | No | Language for country names (e.g. de, en, fr). (default: "en") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get weather by IP

`GET https://api.paperoffice.ai/latest/ip2location/weather`

#### Overview
Weather for an **IP address** (geolocation + weather).

Differs from `GET /weather`: when coordinates are missing, the API may fall back to the geolocation of the given IP.

## Query parameters
- **ip** — recommended; public IPv4/IPv6 (if omitted, caller IP is used)
- **lang** or **locale** — optional response language

**API reference:** `po-weather-by-ip` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | No | Public IPv4/IPv6 to geolocate. If omitted, the caller IP is used (often unsuitable in server-side/MCP calls). |
| `lang` | string | No | Response language. (default: "en") |
| `locale` | string | No | Alias for lang. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List weather icons

`GET https://api.paperoffice.ai/latest/ip2location/weathericon_get`

#### Overview
Returns weather icons (Base64 PNG or CDN fallback) for one or more WMO **condition_code** values from weather responses.

## Parameters
- **condition_code** (required): One code or comma-separated list, e.g. `1000` or `1000,1003,1006`
- **size** (optional, default `128x128`): `64x64` or `128x128`
- **is_day** (optional, default `true`): `true` for day icons, `false` for night

## Request

Authenticate with your Bearer token (optional on VISITOR tier; higher limits with token).

The same fields work via `POST` (form-data or `application/x-www-form-urlencoded`).

## Pricing

**1 credit per condition_code** (comma-separated codes are billed per icon). Example: `condition_code=1000,1003` → 2 credits.

**API reference:** `po-weather-icons` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `condition_code` | string | Yes | WMO weather condition code(s). Comma-separated for multiple icons (e.g. 1000 or 1000,1003,1006). |
| `size` | string | No | Icon dimensions. Must match available static assets. (allowed: 64x64, 128x128) (default: "128x128") |
| `is_day` | string | No | Day (true) or night (false) icon variant. (default: "true") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — Map Tiles

### Get map tile

`GET https://api.paperoffice.ai/latest/maptiles/tiles/get/{z}/{x}/{y}.pbf`

#### Overview
Returns a **Mapbox Vector Tile** (`.pbf`, gzip) for the slippy-map indices `z`, `x`, `y`.

This is a **path-parameter** endpoint — not a static map image. Do not send `lat`/`lon` as query parameters.

## Path parameters
- **z** — zoom level (example: `6`)
- **x** — tile column (example: `34`)
- **y** — tile row (example: `24`)

## Example

`GET /maptiles/tiles/get/6/34/24.pbf`

Equivalent public path (without `/get/`): `/maptiles/tiles/6/34/24.pbf`

**API reference:** `po-map-tiles-get-map-tile` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `z` | integer | Yes (path) | Zoom level (0–14). Higher = more detail. |
| `x` | integer | Yes (path) | Tile X index at this zoom level. |
| `y` | integer | Yes (path) | Tile Y index at this zoom level. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get static map by coordinates

`POST https://api.paperoffice.ai/latest/maptiles/staticmap`

#### Overview
Generates a **static map image** (PNG) or JSON metadata from **GPS coordinates**.

Use **Tool-ID** `po_map_tiles_static_map_coordinates`. For IP-based lookup use `po_map_tiles_static_map_ip_address` (`GET`/`POST` with `ip`).

## Required body fields
- **lat** — latitude (e.g. `52.52`)
- **lon** — longitude (e.g. `13.405`)

Optional: `zoom`, `width`, `height`, `marker`, `format`.

## Example

`POST /maptiles/staticmap` with form fields `lat=52.52`, `lon=13.405`, `zoom=12`, `marker=1`

## Error example (HTTP 400)

Missing or zero coordinates:

```json
{
"status": "error",
"message": "INVALID_COORDINATES"
}
```

**API reference:** `po-map-tiles-static-map-coordinates` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90). |
| `lon` | number | Yes | Longitude (-180 to 180). |
| `zoom` | number | No | Zoom level (1–16, default 12). (default: 12) |
| `width` | number | No | Image width in pixels (default 400). (default: 400) |
| `height` | number | No | Image height in pixels (default 150). (default: 150) |
| `marker` | string | No | Show marker: `0` (no) or `1` (yes, default). (default: "1") |
| `format` | string | No | Output format (default `image`). (allowed: image, png, json, base64) (default: "image") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get static map by IP address

`GET https://api.paperoffice.ai/latest/maptiles/staticmap`

#### Overview
Generates a **static map image** centered on an **IP address** (geolocation lookup).

Use **Tool-ID** `po_map_tiles_static_map_ip_address`. For explicit GPS coordinates use `po_map_tiles_static_map_coordinates` (POST with `lat`/`lon`).

## Required query parameters
- **ip** — public IPv4/IPv6 (e.g. `8.8.8.8`)

Optional: `zoom`, `width`, `height`, `marker`, `format`.

## Example

`GET /maptiles/staticmap?ip=8.8.8.8&zoom=12&marker=1`

**API reference:** `po-map-tiles-static-map-ip-address` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ip` | string | Yes | Public IPv4/IPv6 to center the map (geolocation lookup). |
| `zoom` | number | No | Zoom level (1–16, default 12). (default: 12) |
| `width` | number | No | Image width in pixels (default 400). (default: 400) |
| `height` | number | No | Image height in pixels (default 150). (default: 150) |
| `marker` | string | No | Show marker: `0` (no) or `1` (yes, default). (default: "1") |
| `format` | string | No | Output format (default `image`). (allowed: image, png, json, base64) (default: "image") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Style json

`GET https://api.paperoffice.ai/latest/maptiles/style.json`

#### Overview
Get MapLibre/Mapbox style configuration. Returns: JSON style definition for MapLibre GL JS Use this URL directly in your MapLibre map initialization.

#### Request parameters
**API reference:** `po-map-tiles-style-json` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — Validation & VAT

### Validate All (Email + Phone + Website)

`POST https://api.paperoffice.ai/latest/validate/all`

#### Overview
Validate email, phone, and/or website in one request. Only provided fields are checked. **Pricing:** 20 credits flat bundle (cheaper than three separate 10-credit calls when all fields are used).

#### Request parameters
**API reference:** `po-validate-all` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | No | Email address to validate |
| `phone` | string | No | Phone number to validate |
| `url` | string | No | Website URL to validate (canonical field name). |
| `website` | string | No | Alias of `url` — website URL to validate. Prefer `url` in new integrations. |
| `priority` | integer | No | Legacy queue priority (compat). Prefer processing_lane Start-SLA (no_sla / sla_24h / sla_12h / sla_6h / sla_1h / instant). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Validate Email Address

`POST https://api.paperoffice.ai/latest/validate/email`

#### Overview
Validate an email address (syntax and MX lookup).

**API reference:** `po-validate-email` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Email address to validate |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Validate Phone Number

`POST https://api.paperoffice.ai/latest/validate/phone`

#### Overview
Validate a phone number (E.164 format and carrier lookup).

**API reference:** `po-validate-phone` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `phone` | string | Yes | Phone number to validate (with or without country code, e.g. +49171123456) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Validate Website URL

`POST https://api.paperoffice.ai/latest/validate/website`

#### Overview
Validate a website URL (DNS, SSL certificate, reachability).

**API reference:** `po-validate-website` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | Website URL to validate (e.g. https://example.com) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get EU VAT Rates

`GET https://api.paperoffice.ai/latest/vat/rates`

#### Overview
Get EU VAT Rates

Returns current VAT rates for all 27 EU member states including standard and reduced rates.

--- Parameters
No parameters required.

#### Request parameters
**API reference:** `po-vat-rates-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Validate EU VAT ID

`POST https://api.paperoffice.ai/latest/vat/validate`

#### Overview
Validate a European VAT identification number against the EU VIES database. Returns company name, address, validity status, tax context (VAT rates), and optional fraud risk assessment.

| `vat_id` | string | Yes | EU VAT ID with valid format checksum (e.g. `DE111111125`, `FR12345678901`, `NL123456789B01`) |

**API reference:** `po-vat-validate` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `vat_id` | string | Yes | EU VAT ID with valid format checksum (e.g. DE111111125, FR12345678901). |
| `ip` | string | No | IP address for fraud cross-check (optional) |
| `email` | string | No | Email for fraud cross-check (optional) |
| `force_recheck` | boolean | No | Bypass validation cache and re-query VIES (uses full request credits). |
| `geocoding` | string | No | Include geocoded address coordinates in the response when available (default: true). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Calculate Global Tax Quote

`POST https://api.paperoffice.ai/latest/vat/quote`

#### Overview
Calculate global B2B tax quote for appointments or software without Stripe Tax. Supports EU VAT, Reverse Charge, USA states, Canadian provinces and common global VAT/GST jurisdictions.

#### Request parameters
**API reference:** `po-tax-quote-calculate` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `buyer_country` | string | Yes | Buyer country ISO 3166-1 alpha-2 (required, e.g. DE, US). |
| `buyer_subdivision` | string | No | State/province code for US/CA sales tax (e.g. CA, TX). |
| `postal_code` | string | No | Postal/ZIP code for localized tax rates (US/CA). |
| `vat_id` | string | No | EU VAT ID for B2B reverse-charge validation (VIES). |
| `net_cents` | integer | Yes | Net amount in minor currency units (cents). |
| `currency` | string | No | ISO 4217 currency code (e.g. EUR, USD). |
| `product_type` | string | No | Product category for tax rules (e.g. software, appointment, service). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Data AI — Weather

City/GPS weather (`/weather`, `/location2weather`). IP-derived weather is under **Data AI — IP Geolocation** (`/ip2location/weather`).

### Get weather by city

`GET https://api.paperoffice.ai/latest/weather`

#### Overview
Returns current weather and forecast for a **city name** (geocoded server-side).

Use **Tool-ID** `po_weather_by_city`. For raw coordinates use `po_weather_by_coordinates`.

## Required query parameters
- **city** — city name (e.g. `Berlin`)

Optional: **country** — ISO hint (e.g. `DE`); **lang** or **locale** — response language (default `en`).

## Example

`GET /weather?city=Berlin&country=DE&lang=de`

## Error examples

Missing city:

```json
{
"status": "error",
"code": "MISSING_LOCATION_INPUT",
"message": "Provide lat and lon (or latitude and longitude), or city (country optional)."
}
```

City could not be resolved:

```json
{
"status": "error",
"code": "GEOCODING_FAILED",
"message": "Could not resolve city to coordinates."
}
```

**API reference:** `po-weather-by-city` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `city` | string | Yes | City name to geocode (e.g. Berlin, Munich). |
| `country` | string | No | Optional ISO country hint to disambiguate the city (e.g. DE, US). |
| `lang` | string | No | Response language for condition text. (default: "en") |
| `locale` | string | No | Alias for lang. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get weather by coordinates

`GET https://api.paperoffice.ai/latest/weather`

#### Overview
Returns current weather and a multi-day forecast for **GPS coordinates**.

Use **Tool-ID** `po_weather_by_coordinates`. For city-based lookup use `po_weather_by_city` (same path, different required fields). For IP-based lookup use `po_weather_by_ip` (`GET /ip2location/weather`).

## Required query parameters
- **lat** — latitude (e.g. `52.52` for Berlin)
- **lon** — longitude (e.g. `13.405` for Berlin)

Optional: **lang** — response language (default `en`).

## Example

`GET /weather?lat=52.52&lon=13.405&lang=de`

## Error example (HTTP 400)

Missing location input:

```json
{
"status": "error",
"code": "MISSING_LOCATION_INPUT",
"message": "Provide lat and lon (or latitude and longitude), or city (country optional)."
}
```

Validation errors are not billed.

**API reference:** `po-weather-by-coordinates` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90). |
| `lon` | number | Yes | Longitude (-180 to 180). |
| `lang` | string | No | Response language for condition text (e.g. de, en). (default: "en") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — AI Document Operations

### Get document metadata

`GET https://api.paperoffice.ai/latest/document_intelligence/meta_fields/{pofid}`

#### Overview
Get document analysis metadata including extraction confidence, model hints, and field coverage for a processed document.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-document-analysis-metadata` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Optional filter: financial, parties, metadata, dates, content, etc. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document embeddings (read)

`GET https://api.paperoffice.ai/latest/document_intelligence/embeddings/{documents_id}`

#### Overview
Read all embedding types of a document — summary, full, page, paragraph, metadata, entity, and vision layers where available.

Use `include_vectors=false` (default) for metadata-only responses. Enable vectors only when raw embedding data is required (large payload).

## Generate embeddings

Embeddings are created by **Document AI processing** (detection / AI-DMS workflow tier basic or higher), not by a separate public queue endpoint. After processing, use this GET endpoint to read stored vectors.

## Related

- Semantic search: `POST /document_intelligence/embeddings/search`

**API reference:** `po-embeddings-document-get` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documents_id` | string or number | Yes (path) | Document ID (numeric, from po_documents_search) |
| `type` | string | No | Embedding type: document_summary, document_full, page, paragraph, metadata, entity |
| `include_vectors` | boolean | No | Include raw embedding vectors (large payload; default: false). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Search embeddings

`POST https://api.paperoffice.ai/latest/document_intelligence/embeddings/search`

#### Overview
Direct semantic vector search over Document Intelligence embeddings. Choose embedding type (document_summary, page, paragraph, metadata), min-score and workspace filter.

#### Request parameters
**API reference:** `po-embeddings-search` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search query (natural language) |
| `embedding_type` | string | No | Embedding layer (allowed: document_summary, document_full, page, paragraph, metadata) (default: "document_summary") |
| `workspace_id` | number | No | Limit to workspace |
| `limit` | number | No | Max results (1-50) (default: 10) |
| `min_score` | number | No | Min similarity (0.0-1.0, default 0.3) (default: 0.3) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get canonical entities (entity index)

`GET https://api.paperoffice.ai/latest/document_intelligence/entities/canonical`

#### Overview
Canonical deduplicated entities across all documents. Shows how often an entity appears in different documents.

#### Request parameters
**API reference:** `po-entities-get-canonical-entities` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `type` | string | No | Optional: Filter by entity type |
| `workspace_id` | string | No | Optional: Filter by workspace |
| `search` | string | No | Optional: Search term |
| `limit` | string | No | Max results (default: 100, max: 500) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document summary

`GET https://api.paperoffice.ai/latest/document_intelligence/summary/{pofid}`

#### Overview
Compact summary of all Document Intelligence data. An endpoint for all key metrics and API links.

#### Request parameters
**API reference:** `po-summary-stats-get-document-summary` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice File ID (POFID). Passed as URL path segment (/document_intelligence/summary/{pofid}). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get vision data

`GET https://api.paperoffice.ai/latest/document_intelligence/vision/{pofid}`

#### Overview
Vision-extracted data Ultra-Tier. Includes: - Tables - Structured table data with rows/columns - charts - Recognized charts with data - Form Fields - Form fields with values - barcodes - QR codes and barcodes - Layout - Document structure Headers, Paragraphs, etc.

#### Request parameters
**API reference:** `po-vision-get-vision-data` (documentation ID; not a `/job/add/` pipeline slug) • **Pricing:** From 1 credit — variable by plan and feature — see `GET /job/pricelist` or the [Pricing Calculator](https://app.paperoffice.ai/en/pricing/calculator).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include` | string | No | all, tables, charts, forms, barcodes, layout |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — Anonymization

### Anonymize document (single-step)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

One-shot anonymize via template=document_anonymize — detect PII and return anonymized_pdf without HITL. Supports scenario (default gdpr_auskunft), whitelist, custom_redact, custom_instructions, model. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Must be document_anonymize (detect + redact + PDF in one workflow). (default: "document_anonymize") |
| `file` | string | Yes | PDF or image to anonymize (multipart file) |
| `pofid` | string | No | Or existing DMS POFID (default: "") |
| `redact_categories` | string | No | all / none / CSV category list (default: "all") |
| `whitelist` | string | No | Comma-separated terms to NEVER redact (default: "") |
| `custom_redact` | string | No | Comma-separated terms to ALWAYS redact (default: "") |
| `custom_instructions` | string | No | Free-text AI policy (default: "") |
| `scenario` | string | No | Redact policy scenario (default gdpr_auskunft). Slugs: gdpr_auskunft, externe_weitergabe, oeffentliche_publikation, gerichtsverfahren, whistleblower_hinschg, interne_revision, medizinische_unterlagen, anonyme_bewerbung, personalakte_hr, forschung_wissenschaft, finanzdaten, kontaktdaten, benutzerdefiniert. Controls visibility floors (e.g. GDPR Auskunft whitelist vs external sharing). (allowed: gdpr_auskunft, externe_weitergabe, oeffentliche_publikation, gerichtsverfahren, whistleblower_hinschg, interne_revision, medizinische_unterlagen, anonyme_bewerbung, personalakte_hr, forschung_wissenschaft, finanzdaten, kontaktdaten, benutzerdefiniert) (default: "gdpr_auskunft") |
| `model` | string | No | Anonymize model tier: basic / premium / ultra (mapped to billing/orchestrator tiers). Default from account plan. (default: "premium") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Apply redaction

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_dataripper___redact_image`

#### Overview

Step 2 after Detect PII preview: black out regions and build the anonymized PDF via paperoffice_dataripper___redact_image (same path as UI and MCP). Pass files + bounding_boxes + redact_boxes from the preview job. MCP shortcut: po_anonymization_redaction_apply(preview_job_id). Legacy workflow template anonymization___request is obsolete — do not use it. Optional internal template document_anonymize_finalize exists for workflow-only finalize; prefer this redact_image endpoint. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | string | Yes | Page images from preview: HTTPS download URL(s) or JSON array of page image URLs (from preview original_images / page files). Multipart file uploads also accepted. |
| `page_files` | string | No | Optional JSON map of page→image URL (MCP/UI page_files payload). |
| `bounding_boxes` | string | Yes | OCR geometry: JSON ocr_pages / bounding boxes from preview (required for production apply). |
| `redact_boxes` | string | Yes | JSON: which boxes to black out — typically detected_pii.redact_box_ids (per-page or global). |
| `boxes_by_page` | string | No | Alias for redact_boxes as page-keyed index arrays (e.g. {"00001":[0,2,5]}). |
| `override_boxes` | array | No | Optional manual box IDs overriding auto detection (default: []) |
| `redact_color` | string | No | Redaction fill color (hex) (default: "#000000") |
| `output_pdf` | string | No | true = anonymized PDF; false = redacted page images (default: "true") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `override_boxes[]=value1&override_boxes[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Detect PII preview

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Preview PII for redaction via template=document_anonymize_preview. Returns simplified_boxes + detected_pii (redact_box_ids, partial_redactions). Pass scenario (default gdpr_auskunft), whitelist, custom_redact, custom_instructions. Step 2: apply via paperoffice_dataripper___redact_image (or MCP po_anonymization_redaction_apply with preview_job_id). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Must be document_anonymize_preview (PDF→PNG→OCR→PII detect, no PDF output). (default: "document_anonymize_preview") |
| `file` | string | Yes | PDF or image file (PNG/JPG) via multipart field file |
| `pofid` | string | No | Optional DMS document ID instead of file (default: "") |
| `redact_categories` | string | No | all / none / CSV: names,addresses,phone,email,iban,tax_ids,dates,financial,contact,identity (default: "all") |
| `whitelist` | string | No | Comma-separated terms to NEVER redact (default: "") |
| `custom_redact` | string | No | Comma-separated terms to ALWAYS redact (default: "") |
| `custom_instructions` | string | No | Free-text policy for the AI (default: "") |
| `scenario` | string | No | Redact policy scenario (default gdpr_auskunft). Slugs: gdpr_auskunft, externe_weitergabe, oeffentliche_publikation, gerichtsverfahren, whistleblower_hinschg, interne_revision, medizinische_unterlagen, anonyme_bewerbung, personalakte_hr, forschung_wissenschaft, finanzdaten, kontaktdaten, benutzerdefiniert. Controls visibility floors (e.g. GDPR Auskunft whitelist vs external sharing). (allowed: gdpr_auskunft, externe_weitergabe, oeffentliche_publikation, gerichtsverfahren, whistleblower_hinschg, interne_revision, medizinische_unterlagen, anonyme_bewerbung, personalakte_hr, forschung_wissenschaft, finanzdaten, kontaktdaten, benutzerdefiniert) (default: "gdpr_auskunft") |
| `model` | string | No | Anonymize model tier: basic / premium / ultra (mapped to billing/orchestrator tiers). Default from account plan. (default: "premium") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Finalize anonymize (workflow)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Optional workflow finalize: template=document_anonymize_finalize with preview_images + preview_bounding_boxes + redact_boxes. Prefer POST /job/add/paperoffice_dataripper___redact_image (po_anonymization_apply_redaction) — that is the canonical UI/MCP apply path. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template` | string | No | Must be document_anonymize_finalize (no OCR/LLM — apply boxes to preview images). (default: "document_anonymize_finalize") |
| `preview_images` | string | Yes | JSON array of preview page image URLs from document_anonymize_preview |
| `preview_bounding_boxes` | string | Yes | OCR/bounding geometry from preview |
| `redact_boxes` | string | Yes | Boxes to redact (often user-edited after HITL review) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

---

## Document AI — DMS

### Run whitepage scan analysis

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___whitepage_scan`

#### Overview
Scan PDFs or images for blank pages and embedded barcodes/QR codes. Canonical whitepage endpoint — uses the PaperOffice workflow pipeline.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `whitepage_threshold` | string | No | Whitespace threshold 0.0-1.0, default: 0.95 (default: "0.95") |
| `detect_code` | string | No | Detect barcodes and QR codes (default: "true") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Compliance: Activate WORM (300 Credits)

`POST https://api.paperoffice.ai/latest/documents/document-retention-activate`

#### Overview

Activates WORM protection (write-once-read-many) for a document. The document becomes immutable for the configured retention period (`retention_years`); deletion is only possible after expiry.

**API reference:** `po-compliance-activate-worm` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 300 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice document ID (POFID). |
| `document_type_id` | integer | No | Optional document type ID (overrides the workspace default). |
| `anchor_mode` | string | No | Retention anchor: `immediate` (upload time) or `document_date` (document date). (allowed: immediate, document_date) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create document folder

`POST https://api.paperoffice.ai/latest/documents/folder-create`

#### Overview
Bundle **at least two existing documents** (POFIDs) into a stapled folder/heft in the Headless DMS. This is not an empty directory create — it links documents that already exist.

#### Request parameters
Required: `pofids` (array, min. 2). Optional: `folder_name`, `folder_type` (`staple` or `binder`), `folder_description`, `parent_pofid`.

**API reference:** `po-documents-folders-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofids` | array | Yes | List the PaperOffice-Document IDs (POFIDs) that are to be summarized in the folder. At least 2 are required. |
| `folder_name` | string | No | Name of the document folder. If empty, it is automatically generated (e.g., '3 linked Documents'). |
| `folder_type` | string | No | Folder type: staple (stapled stack) or binder (ring binder). (allowed: staple, binder) (default: "staple") |
| `folder_description` | string | No | Optional description for the document folder. |
| `parent_pofid` | string | No | POFParent document ID. Default: first document in the list. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `folder_id` (`folder_…` format) and `parent_pofid` — reuse `folder_id` for folder-update/dissolve. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Dissolve (unstaple) folder

`POST https://api.paperoffice.ai/latest/documents/folder-dissolve`

#### Overview
Dissolve a folder and optionally relocate contained documents. Use for cleanup and restructuring workspace trees.

#### Request parameters
**API reference:** `po-documents-folders-dissolve` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folder_id` | string | No | Document folder ID. Alternative to `pofid` when dissolving by folder. |
| `pofid` | string | Yes | POFID of a document in the folder (`.podf` map). Alternative to `folder_id`. |
| `confirm` | boolean | Yes | Must be true to confirm this destructive action. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Export document list

`POST https://api.paperoffice.ai/latest/documents/documents-export`

#### Overview
Export Documents Bulk export documents as ZIP archive. Options: - Specific POFIDs - All from workspace

#### Request parameters
**API reference:** `po-document-lists-documents-export` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `selected_pofids` | array | Yes | JSON array of POFIDs to export. |
| `export_format` | string | Yes | Export format: excel/xlsx (spreadsheet), csv, json, pdf. Legacy alias zip maps to json bundle with original files (use archive_format for zip/7z). (allowed: excel, xlsx, csv, json, pdf, zip) |
| `selected_fields` | array | Yes | JSON array of field names to export (e.g. ['file_name', 'created_datetime', 'file_size']). |
| `field_order` | array | No | Optional column order for the export. |
| `include_original_files` | boolean | No | Include original files in the export bundle (typically with export_format=json or zip alias). (default: false) |
| `include_ocr_text` | boolean | No | Include OCR-extracted text in the export. (default: false) |
| `include_ocr_bounding_boxes` | boolean | No | Include OCR bounding boxes (position data) in the export. (default: false) |
| `archive_format` | string | No | Archive format for file exports (zip or 7z). (allowed: zip, 7z) (default: "zip") |
| `excel_options` | object | No | Optional Excel-specific settings (column width, header formatting etc.). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List folders

`POST https://api.paperoffice.ai/latest/documents/folder-list`

#### Overview
List folders in a workspace with optional parent filter and pagination.

#### Request parameters
**API reference:** `po-documents-folders-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | Yes | Required: Workspace ID to list folders from |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Run DMS document analysis

`POST https://api.paperoffice.ai/latest/documents/document-analysis`

#### Overview
Run AI document analysis on a document (summary, classification, extraction hints).

**Model parameter:** common values include `basic`, `premium`, and `ultra`. The API also accepts extended agent and per variants (e.g. `agent-premium`, `premium-per-max`, `paperoffice-agent-ultra`) — see the error message for the full runtime list when an invalid model is sent. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-document-analysis-analysis-dms` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI analysis tier: basic, premium, or ultra (default ultra). (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "document_analysis") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Suggest AI Model

`POST https://api.paperoffice.ai/latest/documents/suggest-llm-model`

#### Overview
Suggest an LLM model tier for a document based on content complexity.

Returns a recommended model from the same family as `document-analysis` (basic/premium/ultra and extended agent/per variants). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-document-analysis-suggest-llm-model` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | LLM tier for field suggestions: basic, premium, or ultra (default premium). (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "suggest_paperoffice_llm_model") |
| `prompt` | string | Yes | Natural-language description of fields to extract (guides model selection). (default: "I want to extract invoice number, date, vendor name, and total amount") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update folder

`POST https://api.paperoffice.ai/latest/documents/folder-update`

#### Overview
Update folder name, parent, or metadata for an existing DMS folder.

#### Request parameters
**API reference:** `po-documents-folders-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folder_id` | string | Yes | ID of the document folder to update. |
| `folder_name` | string | No | New name for the document folder. |
| `folder_description` | string | No | New description for the document folder. |
| `folder_icon` | string | No | New icon for the document folder (emoji or icon key). |
| `folder_color` | string | No | New color for the document folder (hex code, e.g. `#3b82f6`). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Acquire Edit-Session (Presence-Lock)

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-acquire/{pofid}`

#### Overview
Acquire a cooperative metadata edit lock for a document. If another user is editing, the response returns `status=readonly`. The lock is ephemeral — it expires after about 60 seconds without a heartbeat. Poll **`POST /documents/document-edit-session-heartbeat/{pofid}`** while editing.

#### Request parameters
> **Availability:** Requires account DB columns `editing_by_account_id`, `editing_heartbeat_at`, and `editing_session_token`. Without migration, the API returns HTTP `501` (`PRESENCE_LOCK_UNAVAILABLE`).

**API reference:** `po-documents-edit-session-acquire` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice document ID (pofid) — URL path parameter or request body. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create Document from Content

`POST https://api.paperoffice.ai/latest/document_generation/create-from-content`

#### Overview
Generate a PDF in the DMS from Markdown or HTML.

**Required body field:** `content` (Markdown or HTML string). Set `content_type` to `markdown` or `html`.

This endpoint does **not** use `html_content` — that field name applies only to `POST /document_generation/template-create`.

**HTTP status:** Returns **201 Created** on success (also accept **200** in clients). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-documents-create-from-content` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `content` | string | Yes | Markdown or HTML source (required). Not html_content. |
| `content_type` | string | Yes | Format of the content field. (allowed: markdown, html) (default: "markdown") |
| `output_format` | string | No | Output format of the created document (allowed: pdf) (default: "pdf") |
| `title` | string | No | Document title (also used as the filename) |
| `workspace_id` | integer | Yes | Target workspace ID (required). Use po_workspaces_list to find valid workspace IDs. |
| `metadata` | object | No | Metadata as key-value pairs (stored as IDP fields). |
| `language` | string | No | Language for formatting (de/en) (default: "de") |
| `auto_classify` | boolean | No | Automatic classification after creation. (default: false) |
| `custom_css` | string | No | Additionals CSS for the PDF-Layout |
| `header_html` | string | No | HTML for page header |
| `footer_html` | string | No | HTML for footer |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Success HTTP: **200** or **201**. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create Document from Template

`POST https://api.paperoffice.ai/latest/document_generation/create-from-template`

#### Overview
Create a new document in a workspace from a document generation template.

Requires `template_id`, `workspace_id`, and template variable values as documented in the template schema.

**HTTP status:** Returns **201 Created** on success (also accept **200** in clients). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-documents-create-from-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template ID (e.g. tpl_rechnung_standard) |
| `variables` | object | Yes | Variable values for the placeholders in the template. Arrays for {{#each}} blocks. |
| `output_format` | string | No | Rendered output format (currently only pdf). (allowed: pdf) (default: "pdf") |
| `workspace_id` | integer | Yes | Target workspace ID (required). Use po_workspaces_list to find valid workspace IDs. |
| `title` | string | No | Document title (overrides the template name). Can contain {{variable}} placeholders. |
| `metadata` | object | No | Additional Metadaten |
| `auto_classify` | boolean | No | When true, run document classification after generation. (default: false) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Success HTTP: **200** or **201**. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-create`

#### Overview
Create a reusable document-generation template.

**HTML field:** use `html_content` (not `content`). Merge placeholders such as `{{invoice_number}}` and `{{customer_name}}` are supported.

**HTTP status:** Returns **201 Created** on success (also accept **200** in clients).

**API reference:** `po-templates-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | No | Optional template ID (auto-generated from name when omitted). |
| `name` | string | Yes | Display name for the template. |
| `html_content` | string | Yes | HTML body with {{variable}} placeholders for merge fields. |
| `description` | string | No | Optional template description. |
| `category` | string | No | category (e.g. invoices, contracts, reports) (default: "general") |
| `variables_schema` | object | No | JSON schema of expected template variables (merge fields). |
| `page_format` | string | No | Page size (A4, A3, Letter, etc.). (default: "A4") |
| `page_orientation` | string | No | Page orientation: portrait or landscape. (allowed: portrait, landscape) (default: "portrait") |
| `margin_top` | integer | No | Top page margin in millimeters. (default: 20) |
| `margin_right` | integer | No | Right page margin in millimeters. (default: 15) |
| `margin_bottom` | integer | No | Bottom page margin in millimeters. (default: 20) |
| `margin_left` | integer | No | Left page margin in millimeters. (default: 15) |
| `header_html` | string | No | HTML for page header |
| `footer_html` | string | No | HTML for footer |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `template_id`. Optional `_billing` and `processing_time`. Success HTTP: **200** or **201**. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create document type

`POST https://api.paperoffice.ai/latest/documents/document-types-create`

#### Overview

Creates a custom document type (including retention_years/retention_mode).

**API reference:** `po-documents-document-types-create` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Display name of the document type. |
| `source_locale` | string | Yes | Source locale for type labels (e.g. de-DE). |
| `retention_years` | integer | No | Retention period in years (GoBD/compliance workflows). |
| `retention_mode` | string | No | Retention policy: none or compliance (WORM-style). (allowed: none, compliance) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-delete`

#### Overview
Delete a document generation template by ID.

Send `template_id` in the JSON body. Legacy aliases `id` and `template` are accepted but deprecated.

**API reference:** `po-templates-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete document type

`POST https://api.paperoffice.ai/latest/documents/document-types-delete`

#### Overview

Deletes a custom document type (only when no document and no workspace default references it).

**API reference:** `po-documents-document-types-delete` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | Document type id from po_documents_document_types_list |
| `confirm` | boolean | Yes | MCP safety gate: must be true to delete |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Document: Automation history

`GET https://api.paperoffice.ai/latest/documents/automation-timeline/{pofid}`

#### Overview
Returns the chronological automation history for a document (AI-DMS, IDP Agent, Workflow).

Events include pipeline type, status, timestamps, and human-readable labels. Requires read access in the document workspace.

#### Request parameters
**API reference:** `po-documents-automation-timeline` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 0 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_context` | string | No | Optional share context for sub-users |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Document: Podcast audiobook estimate

`POST https://api.paperoffice.ai/latest/documents/podcast-audiobook-estimate`

#### Overview

Estimates characters, chapters and TTS Basic credits for generating a podcast audiobook from a document text layer.

**API reference:** `po-documents-podcast-audiobook-estimate` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID (POFID) of the source document |
| `language` | string | No | ISO language code for intro/outro (default de; non-de uses English script) |
| `voice` | string | No | TTS catalog voice name (default: language female default, e.g. Anneliese) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Document: Podcast audiobook start

`POST https://api.paperoffice.ai/latest/documents/podcast-audiobook-start`

#### Overview

Starts asynchronous podcast audiobook generation (TTS Basic). Poll podcast-audiobook-status. Creates a new MP3 document in the same workspace.

**API reference:** `po-documents-podcast-audiobook-start` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID (POFID) of the source document |
| `language` | string | No | ISO language code for intro/outro (default de; non-de uses English script) |
| `voice` | string | No | TTS catalog voice name (default: language female default, e.g. Anneliese) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Document: Podcast audiobook status

`POST https://api.paperoffice.ai/latest/documents/podcast-audiobook-status`

#### Overview

Returns podcast audiobook job progress for a source document (phase, percent, audio POFID when completed).

**API reference:** `po-documents-podcast-audiobook-status` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID (POFID) of the source document |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Download document

`GET https://api.paperoffice.ai/latest/documents/document-download/{pofid}`

#### Overview
Download the original file of a document as a **binary HTTP attachment** (`Content-Disposition: attachment`).

Pass `pofid` as a path segment (`GET /documents/document-download/{pofid}`) or query parameter (`?pofid=`). The response body is the raw file bytes — not a JSON wrapper with `download_url`.

For time-limited URLs (jobs, exports), use `GET /job/download/{token}` instead.

#### Request parameters
| Parameter | Required | Description |
|---|---|---|
| `pofid` | Yes | PaperOffice File ID |

**API reference:** `po-documents-download` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID of the document. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Download document audit report PDF

`POST https://api.paperoffice.ai/latest/documents/audit-report-pdf`

#### Overview

Generates a printable PDF security audit report for a document (AI-DMS Ultra). Allowed during audit quarantine for external review. Optionally appends the original document as a combined PDF.

**API reference:** `po-documents-audit-report-pdf` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | Document POFID |
| `language` | string | No | ISO-639-1 UI language for PDF labels (default en) |
| `include_original` | boolean | No | Append original document as PDF appendix |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Find similar documents

`GET https://api.paperoffice.ai/latest/documents/document-similar-find`

#### Overview
Find documents similar to a reference document using AI embeddings. Requires AI-DMS processing (basic+ tier) on the reference document — unprocessed documents have no embeddings. Use for duplicate detection, finding related invoices or contracts.

#### Request parameters
**API reference:** `po-documents-similar-find` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `documents_id` | number | One of (`documents_id`, `pofid`) | Numeric document ID of the reference document. At least one of documents_id or pofid MUST be provided. |
| `pofid` | string | One of (`documents_id`, `pofid`) | POFID of the reference document (resolved to documents_id). At least one of documents_id or pofid MUST be provided. |
| `threshold` | number | No | Similarity threshold 0.0-1.0 (default: 0.7 = 70%) |
| `limit` | number | No | Max results 1-50 (default: 10) |

#### Required alternatives

Provide **at least one** of: `documents_id` **or** `pofid`.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get DMS statistics

`GET https://api.paperoffice.ai/latest/documents/stats`

#### Overview

Get global DMS statistics — total documents, entities, embeddings, breakdown by document type, and optional workspace filter. Best effort counts for overview dashboards.

**API reference:** `po-documents-stats-get` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | number | No | Statistics for a specific workspace only |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document audit trail

`GET https://api.paperoffice.ai/latest/documents/document-audit-trail`

#### Overview
Get compliance audit trail — who changed what, when. Filter by document (pofid or documents_id), user, action. For compliance audits (GoBD, GDPR/DSGVO).

#### Request parameters
**API reference:** `po-documents-audit-trail-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | One of (`documents_id`, `pofid`) | Filter by document POFID — resolved to documents_id automatically. Alternative to documents_id. |
| `documents_id` | string or number | One of (`documents_id`, `pofid`) | Only show changes for this document (numeric ID) |
| `user_id` | string or number | No | Only show changes from this user |
| `action` | string | No | Filter by action type. Common values: document_created, field_changed, field_created, status_changed, document_deleted_soft, document_checked_out, document_checked_in, folder_created, folder_dissolved. Server validates against actual recorded actions. |
| `limit` | number | No | Maximum number of entries (default: 50) |
| `offset` | number | No | Offset for pagination (default: 0) |

#### Required alternatives

Provide **at least one** of: `documents_id` **or** `pofid`.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-get`

#### Overview
Retrieve a single document generation template by ID.

Legacy aliases `id` and `template` are accepted but deprecated — use `template_id`.

**API reference:** `po-templates-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document thumbnail

`GET https://api.paperoffice.ai/latest/documents/document-thumb-get/{pofid}/{page_number}`

#### Overview
Get a thumbnail preview image of a specific document page. Returns base64-encoded WebP/JPEG image. Accepts pofid or documents_id. Use for document preview, visual comparison, page inspection.

#### Request parameters
**API reference:** `po-documents-thumbnail-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | One of (`documents_id`, `pofid`) | PaperOffice File ID (POFID). At least one of pofid or documents_id MUST be provided. |
| `documents_id` | number | One of (`documents_id`, `pofid`) | Numeric document ID — Alternative to pofid. |
| `page_number` | number | No | Page number (default: 1) |

#### Required alternatives

Provide **at least one** of: `documents_id` **or** `pofid`.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Heartbeat Edit-Session

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-heartbeat/{pofid}`

#### Overview
Keeps a previously acquired edit-session lock alive. Call every **30 seconds** while editing. Returns **HTTP 409** with `EDIT_SESSION_LOST` if the lock was already released or expired.

#### Request parameters
> **Availability:** Requires account DB columns `editing_by_account_id`, `editing_heartbeat_at`, and `editing_session_token`. Without migration, the API returns HTTP `501` (`PRESENCE_LOCK_UNAVAILABLE`).

**API reference:** `po-documents-edit-session-heartbeat` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 0 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice document ID (pofid) — URL path parameter or request body. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Document Templates

`POST https://api.paperoffice.ai/latest/document_generation/templates-list`

#### Overview
List document generation templates available in the account with name, format, and last-updated metadata.

#### Request parameters
**API reference:** `po-templates-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `category` | string | No | Category filter (e.g. invoices, contracts, reports) |
| `limit` | integer | No | Max results (1-200) (default: 50) |
| `offset` | integer | No | Pagination offset (0-based, default 0). (default: 0) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List document types

`GET https://api.paperoffice.ai/latest/documents/document-types-list`

#### Overview

Document types including retention policy per type.

**API reference:** `po-documents-document-types-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List IDP collections

`GET https://api.paperoffice.ai/latest/documents/idp-collections-list`

#### Overview

Catalog of all IDP extraction templates including field definitions.

**API reference:** `po-documents-idp-collections-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List meta fields (index schema)

`GET https://api.paperoffice.ai/latest/documents/meta-fields-list`

#### Overview

List system and custom meta fields for bulk edit/export (workspace index schema).

**API reference:** `po-documents-meta-fields-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Optional workspace scope |
| `compact` | boolean | No | MCP only: true (default) returns compact field catalog; false returns full UI export catalog (very large) (default: true) |
| `locale` | string | No | MCP only: label locale for compact output (default en) |
| `fields_limit` | integer | No | MCP only: max fields in compact output (default 120, sorted by usage_count) (default: 120) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Merge publisher

`POST https://api.paperoffice.ai/latest/publishers/{publisher_id}/merge`

#### Overview
Merge two publisher profiles when duplicates exist. The `{publisher_id}` path segment is the **source** publisher to retire; provide `target_publisher_id` in the JSON body. Logos, aliases, and document references move to the target.

#### Request parameters
**API reference:** `po-publishers-merge` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `target_publisher_id` | integer | Yes | ID of the publisher to keep — the source `{publisher_id}` from the URL is merged into this profile. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Process document (AI-DMS)

`POST https://api.paperoffice.ai/latest/documents/document-process/{pofid}`

#### Overview

Trigger AI-DMS processing on a document that is already stored in PaperOffice. Use when a document was uploaded without AI-DMS or when re-processing with a different tier. Queues OCR, classification, and metadata extraction; previous analysis results are reset on re-process. This does not upload a file — the document must already exist. Upload new files via **Upload document** (`PUT /documents/document-put/{pofid}`) in Headless DMS first.

Tier downgrade or same-tier reprocess requires confirm_tier_downgrade=true and/or confirm_reprocess=true (HTTP 409 otherwise). Upgrades need no extra confirmation. Single-document AI-DMS process. Optional processing_lane sets Start-SLA (default no_sla).

**API reference:** `po-documents-process` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice File ID (POFID). At least one of pofid or documents_id MUST be provided. |
| `documents_id` | number | One of (`documents_id`, `pofid`) | Numeric document ID — Alternative to pofid. |
| `ai_dms_tier` | string | Yes | AI-DMS processing tier: basic (OCR + classification), premium (+ entity extraction), ultra (+ deep analysis) (allowed: basic, premium, ultra) |
| `confirm_tier_downgrade` | boolean | No | Required for tier downgrade on an existing document. MCP ≡ API. |
| `confirm_reprocess` | boolean | No | Required for same-tier reprocess after successful completion. MCP ≡ API. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

#### Required alternatives

Provide **at least one** of: `documents_id` **or** `pofid`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Query Edit-Session Status

`GET https://api.paperoffice.ai/latest/documents/document-edit-session-status/{pofid}`

#### Overview
Get the current edit-session status for a document (`free`, `mine`, or `taken`) without acquiring the lock. Use before **`POST /documents/document-edit-session-acquire/{pofid}`** to avoid unnecessary lock attempts.

#### Request parameters
> **Availability:** Requires account DB columns `editing_by_account_id`, `editing_heartbeat_at`, and `editing_session_token`. Without migration, the API returns HTTP `501` (`PRESENCE_LOCK_UNAVAILABLE`).

**API reference:** `po-documents-edit-session-status` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 0 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice document ID (pofid) — URL path parameter or request body. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Release Edit-Session

`POST https://api.paperoffice.ai/latest/documents/document-edit-session-release/{pofid}`

#### Overview
Releases the edit-session lock for a document so other users can edit. Call when the user finishes editing or navigates away.

#### Request parameters
> **Availability:** Requires account DB columns `editing_by_account_id`, `editing_heartbeat_at`, and `editing_session_token`. Without migration, the API returns HTTP `501` (`PRESENCE_LOCK_UNAVAILABLE`).

**API reference:** `po-documents-edit-session-release` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 0 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice document ID (pofid) — URL path parameter or request body. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Rename publisher

`POST https://api.paperoffice.ai/latest/publishers/{publisher_id}/rename`

#### Overview
Rename a publisher profile. The `{publisher_id}` path segment identifies the publisher; provide `new_name` in the JSON body.

#### Request parameters
**API reference:** `po-publishers-rename` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `new_name` | string | Yes | New display name for the publisher identified by `{publisher_id}` in the URL path. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Resolve document POFID

`POST https://api.paperoffice.ai/latest/documents/document-pofid-resolve`

#### Overview

Normalizes a POFID against the database (O/0 in the hash segment) and returns documents_id and file_name.

**API reference:** `po-documents-pofid-resolve` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | Document POFID (byte-copy from search; O/0 in hash is normalized) |
| `include_deleted` | boolean | No | Include soft-deleted documents (default: false) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Run IDP Agent on document

`POST https://api.paperoffice.ai/latest/documents/idp-agent-run`

#### Overview

Run an IDP Agent: provide idp_agent_id plus pofid, upload_id, or file_url. Returns extracted_fields and confidence when done. Poll via po_documents_get profile=status.

**API reference:** `po-documents-idp-agent-run` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `idp_agent_id` | string | Yes | IDP Agent ID from po_agents_list (kind idp_extract) |
| `pofid` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `upload_id` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `file_url` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `file_name` | string | No |  |
| `workspace_id` | integer | One of (`workspace_id`, `workspace_name`) |  |
| `workspace_name` | string | One of (`workspace_id`, `workspace_name`) |  |
| `client_wait` | boolean | No | (default: false) |
| `wait_timeout_sec` | integer | No | (default: 300) |
| `poll_interval_sec` | integer | No | (default: 5) |

#### Required alternatives

Provide **at least one** of: `file_url` **or** `pofid` **or** `upload_id`.

Provide **at least one** of: `workspace_id` **or** `workspace_name`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Run Redact Agent on document

`POST https://api.paperoffice.ai/latest/documents/redact-agent-run`

#### Overview

Run a Redact Agent: provide redact_agent_id plus pofid, upload_id, or file_url. Uses stored scenario/whitelist and imports the anonymized PDF. Poll via po_documents_get profile=status.

**API reference:** `po-documents-redact-agent-run` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `redact_agent_id` | string | Yes | Redact Agent ID from po_agents_list (kind pdf_redact) |
| `pofid` | string | One of (`file_url`, `pofid`, `upload_id`) | Existing PDF in DMS (Alternative to upload_id/file_url) |
| `upload_id` | string | One of (`file_url`, `pofid`, `upload_id`) | From po_documents_upload_url_get after curl upload |
| `file_url` | string | One of (`file_url`, `pofid`, `upload_id`) | Public HTTPS URL to PDF |
| `file_name` | string | No | Filename hint when using upload_id or file_url |
| `workspace_id` | integer | One of (`workspace_id`, `workspace_name`) | Target workspace when uploading a new PDF |
| `workspace_name` | string | One of (`workspace_id`, `workspace_name`) | Auto-create workspace by name when uploading |
| `client_wait` | boolean | No | Wait server-side for pipeline completion (default: false) |
| `wait_timeout_sec` | integer | No | (default: 300) |
| `poll_interval_sec` | integer | No | (default: 5) |

#### Required alternatives

Provide **at least one** of: `file_url` **or** `pofid` **or** `upload_id`.

Provide **at least one** of: `workspace_id` **or** `workspace_name`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Run Split Agent on document

`POST https://api.paperoffice.ai/latest/documents/split-agent-run`

#### Overview

Run a Split Agent: provide split_agent_id plus pofid, upload_id, or file_url. Optional client_wait waits for split_imported_documents. Poll status via po_documents_get profile=status.

**API reference:** `po-documents-split-agent-run` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `split_agent_id` | string | Yes | Split Agent ID from po_agents_list (kind pdf_split) |
| `pofid` | string | One of (`file_url`, `pofid`, `upload_id`) | Existing PDF in DMS (Alternative to upload_id/file_url) |
| `upload_id` | string | One of (`file_url`, `pofid`, `upload_id`) | From po_documents_upload_url_get after curl upload |
| `file_url` | string | One of (`file_url`, `pofid`, `upload_id`) | Public HTTPS URL to PDF |
| `file_name` | string | No | Filename hint when using upload_id or file_url |
| `workspace_id` | integer | One of (`workspace_id`, `workspace_name`) | Target workspace when uploading a new PDF |
| `workspace_name` | string | One of (`workspace_id`, `workspace_name`) | Auto-create workspace by name when uploading |
| `client_wait` | boolean | No | Wait server-side for pipeline completion (default: false) |
| `wait_timeout_sec` | integer | No | (default: 300) |
| `poll_interval_sec` | integer | No | (default: 5) |

#### Required alternatives

Provide **at least one** of: `file_url` **or** `pofid` **or** `upload_id`.

Provide **at least one** of: `workspace_id` **or** `workspace_name`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Run Trust Agent on document

`POST https://api.paperoffice.ai/latest/documents/trust-agent-run`

#### Overview

Run a Trust Agent: provide trust_agent_id plus pofid, upload_id, or file_url. Returns integrity_score, integrity_verdict, and findings when done. Poll via po_documents_get profile=status.

**API reference:** `po-documents-trust-agent-run` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `trust_agent_id` | string | Yes | Trust Agent ID from po_agents_list (kind pdf_trust) |
| `pofid` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `upload_id` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `file_url` | string | One of (`file_url`, `pofid`, `upload_id`) |  |
| `file_name` | string | No |  |
| `workspace_id` | integer | No |  |
| `client_wait` | boolean | No | (default: false) |
| `wait_timeout_sec` | integer | No | (default: 300) |
| `poll_interval_sec` | integer | No | (default: 5) |

#### Required alternatives

Provide **at least one** of: `file_url` **or** `pofid` **or** `upload_id`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Search documents (advanced)

`POST https://api.paperoffice.ai/latest/documents/documents-list`

#### Overview
Advanced multi-source document search **within the workspace you provide** (`workspace_id` is required).

Combines full-text search, OCR text, entity matching, and semantic embeddings. Supports intelligent query mode detection, pagination, workspace filters, and relevance scoring.

This endpoint does **not** search across all workspaces — pass the target `workspace_id` (or filter list) explicitly.

#### Request parameters
**API reference:** `po-storage-documents-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Required: ID of the workspace |
| `global_search` | string | No | Search term for multi-source document search (fulltext, OCR, entities, semantic). |
| `search_mode` | string | No | Search mode: `intelligent` (auto), `hybrid`, `semantic`, `fulltext`, or `exact`. (allowed: intelligent, hybrid, semantic, fulltext) (default: "intelligent") |
| `search_preference` | string | No | keyword=BM25 only; semantic=vector search; balanced=blend both (default). (allowed: keyword, semantic, balanced) (default: "balanced") |
| `search_scope` | string | No | current=search only the active workspace; all=search all accessible workspaces. (allowed: current, all) (default: "current") |
| `similarity_threshold` | number | No | Minimum Similarity for Semantic Search (0.0-1.0) (default: 0.35) |
| `page` | integer | No | Page number for pagination (default: 1) |
| `limit` | integer | No | documents per page (max 500) (default: 500) |
| `sort` | string | No | Sort field (e.g. created_at, updated_at, title). (default: "created_datetime") |
| `order` | string | No | Sort direction for listed documents: ASC or DESC (default DESC). (allowed: ASC, DESC) (default: "DESC") |
| `__document__data__classification__document_type` | array | No | Filter: Documenttypen (JSON Array or komma-separiert) |
| `__document__content__extraction__keywords` | array | No | Filter: Keywords |
| `__document__data__workflow__state` | array | No | Filter: Workflow-Status |
| `__document__data__classification__locale` | array | No | Filter: language/Locale |
| `__document__data__metadata__save_paths` | array | No | Filter by storage path (PREFIX_WILDCARD:/path or EXACT:/path). |
| `ai_dms_status` | array | No | Filter: AI-DMS Tier |
| `ai_agent_status` | array | No | Filter: AI-Agent Status |
| `date_from` | string | No | Filter: Date from (YYYY-MM-DD) |
| `date_to` | string | No | Filter: date bis (YYYY-MM-DD) |
| `share_context` | string | No | External share context token JSON for scoped access in a shared workspace. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `__document__data__classification__document_type[]=value1&__document__data__classification__document_type[]=value2`, `__document__content__extraction__keywords[]=value1&__document__content__extraction__keywords[]=value2`, `__document__data__workflow__state[]=value1&__document__data__workflow__state[]=value2`, `__document__data__classification__locale[]=value1&__document__data__classification__locale[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update Document Template

`POST https://api.paperoffice.ai/latest/document_generation/template-update`

#### Overview
Update an existing document generation template (HTML content, metadata, variables schema).

Send `template_id` in the JSON body. Legacy aliases `id` and `template` are accepted but deprecated.

**API reference:** `po-templates-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `template_id` | string | Yes | Template-ID (required) |
| `name` | string | No | Updated template display name. |
| `html_content` | string | No | Updated HTML body with {{variable}} merge placeholders. |
| `description` | string | No | Updated template description. |
| `category` | string | No | Template category (e.g. invoices, contracts, reports). |
| `variables_schema` | object | No | JSON schema describing expected merge-field variables. |
| `page_format` | string | No | Page size (A4, A3, Letter, etc.). |
| `page_orientation` | string | No | Page orientation: portrait or landscape. (allowed: portrait, landscape) |
| `margin_top` | integer | No | Top page margin in millimeters. |
| `margin_right` | integer | No | Right page margin in millimeters. |
| `margin_bottom` | integer | No | Bottom page margin in millimeters. |
| `margin_left` | integer | No | Left page margin in millimeters. |
| `header_html` | string | No | HTML snippet rendered at the top of each page. |
| `footer_html` | string | No | HTML snippet rendered at the bottom of each page. |
| `is_active` | integer | No | 1 = active template, 0 = disabled (hidden from generation). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update document type

`POST https://api.paperoffice.ai/latest/documents/document-types-update`

#### Overview

Updates a document type including retention period.

**API reference:** `po-documents-document-types-update` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | No | Document type numeric id from po_documents_document_types_list |
| `type_key` | string | No | Document type key (Alternative to id) |
| `name_default` | string | No | New display name for custom document types |
| `retention_years` | integer | No | Updated retention period in years. |
| `retention_mode` | string | No | Updated retention policy: none or compliance. (allowed: none, compliance) |
| `description_default` | string | No | Updated default description for the custom document type. |
| `description` | string | No | Alias for description_default (accepted for MCP/Postman compatibility). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Upgrade Start-SLA for pending documents

`POST https://api.paperoffice.ai/latest/documents/processing-lane-upgrade`

#### Overview

Upgrade Start-SLA (processing_lane) for untouched pending AI-DMS documents only. Higher factor only — no downgrade, no refund. Pass processing_lane and confirm=1 (or dry_run=1).

**API reference:** `po-documents-processing-lane-upgrade` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `processing_lane` | string | Yes | Target Start-SLA lane (no_sla / sla_24h / sla_12h / sla_6h / sla_1h / instant). Must be strictly higher than current. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |
| `confirm` | boolean | No | Set true to apply the upgrade (required unless dry_run). |
| `dry_run` | boolean | No | Preview upgradable/skipped docs without writing. |
| `scope` | string | No | pending (default, all untouched pending) or pofids. (allowed: pending, pofids) |
| `pofids` | array | Yes | Optional document IDs when scope=pofids. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `pofids[]=value1&pofids[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Workspace: Classical IDP readiness

`POST https://api.paperoffice.ai/latest/documents/workspace-classical-idp-readiness`

#### Overview

Evaluate classical IDP workflow readiness for a workspace. Pass workspace_id. Optional preview: ai_dms_mode, default_document_type_mode, workspace_tier, workspace_idp_agent_pipeline.

**API reference:** `po-documents-workspace-classical-idp-readiness` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Workspace ID (required). |
| `ai_dms_mode` | string | No | Optional unsaved preview of AI-DMS mode. |
| `default_document_type_mode` | string | No | Optional preview: none / auto / fixed. |
| `workspace_tier` | string | No | Optional preview tier (standard / business / compliance). |
| `workspace_idp_agent_pipeline` | array | No | Optional preview of workspace IDP pipeline entries. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `workspace_idp_agent_pipeline[]=value1&workspace_idp_agent_pipeline[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get entity statistics

`GET https://api.paperoffice.ai/latest/documents/entity-statistics`

#### Overview
Get detailed statistics for a specific entity (company, person, IBAN) — which documents mention it, total amounts, time range. Use for: "How much did we order from company X?".

#### Request parameters
**API reference:** `po-entities-stats-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `entity_value` | string | Yes | Entity value (e.g. company name, IBAN, person name) |
| `entity_type` | string | No | Filter type: company, person, iban, tax_id, amount, address, email, phone |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document revisions

`GET https://api.paperoffice.ai/latest/documents/document-revisions`

#### Overview
Document version history. Displays all changes with timestamp, user, and change details.

#### Request parameters
**API reference:** `po-revisions-get-document-revisions` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice document ID whose revisions are retrieved (URL parameter). |
| `limit` | integer | No | Maximum number of revisions returned. (default: 50) |
| `offset` | integer | No | Offset for pagination. (default: 0) |
| `action` | string | No | Filter by action type (e.g. 'field_changed', 'folder_created'). |
| `field_key` | string | No | Filter by changed field (e.g. 'invoice_number'). |
| `date_from` | string | No | revisions from this date (YYYY-MM-DD). |
| `date_to` | string | No | revisions bis zu this date (YYYY-MM-DD). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Add Document Tag

`POST https://api.paperoffice.ai/latest/documents/document-tag-add`

#### Overview
Add one or more tags to a document. Creates the tag in the workspace if it does not exist yet.

#### Request parameters
**API reference:** `po-documents-tags-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `tag_name` | string | Yes | Tag-Name (max 100 characters) |
| `tag_color` | string | No | Optional hex color (#RGB or #RRGGBB format, e.g. #FF0000). Invalid formats will be rejected. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Batch-process documents (AI-DMS)

`POST https://api.paperoffice.ai/latest/documents/document-batch-process`

#### Overview

Triggers AI-DMS processing for multiple documents simultaneously. Max 50 POFIDs per batch. Each document is processed asynchronously via OCR, Entity Extraction, Classification, etc.

#### Request parameters

Authenticate with your Bearer token.

**API reference:** `po-documents-batch-process` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofids` | array | Yes | Array of POFIDs to process (max 50) |
| `ai_dms_tier` | string | No | AI-DMS processing tier: basic (OCR + classification), premium (+ entity extraction), ultra (+ deep analysis) (allowed: basic, premium, ultra) (default: "basic") |
| `confirm` | boolean | No | Required for bulk (>5 POFIDs) or mode=instant — MCP matches the API. |
| `confirm_tier_downgrade` | boolean | No | Required when ai_dms_tier is lower than the document's current tier (downgrade). MCP ≡ API. |
| `confirm_reprocess` | boolean | No | Required when ai_dms_tier equals the current tier and the document was successfully processed before (same-tier reprocess). MCP ≡ API. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Check for duplicate documents

`POST https://api.paperoffice.ai/latest/documents/duplicate-check`

#### Overview
Check whether similar documents already exist before upload. Compares fingerprints and metadata to reduce duplicate imports.

#### Request parameters
**API reference:** `po-documents-duplicate-check` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_hash` | string | Yes | SHA-256 hex digest of the file (64 characters). |
| `workspace_id` | integer | No | Optional workspace scope for duplicate detection. |
| `exclude_pofid` | string | No | Optional POFID to exclude from match. |
| `exclude_documents_id` | integer | No | Optional documents_id to exclude. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Copy document

`POST https://api.paperoffice.ai/latest/documents/document-copy`

#### Overview
Copy a document to another folder or workspace. Preserves metadata where configured; returns the new document POFID.

#### Request parameters
**Chaining:** On success read ``copy.pofid` for the duplicated document` from the response for the next API call.

**API reference:** `po-documents-copy` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID of the document to copy |
| `target_workspace_id` | integer | Yes | ID of the target workspace the document is copied to. |
| `locale` | string | No | Optional locale for copied metadata labels (e.g. de-DE). |
| `new_file_name` | string | No | Destination filename after copy (include extension). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; key fields: nested `copy.pofid` for the new document. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-create`

#### Overview
Create a comment on a document. Supports optional parent comment ID for threaded replies and @mentions within the workspace.

#### Request parameters
**API reference:** `po-documents-comments-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `content` | string | Yes | Comment text (required). |
| `parent_id` | integer | No | Parent comment ID for reply (optional) |
| `page_number` | integer | No | Page number (optional). |
| `anchor_text` | string | No | Anchor text in the document (optional). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; key fields: `comment_id` (and optional `parent_id`). Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-create`

#### Overview
Create an internal note attached to a document. Notes are visible to workspace users with document access (not external signers).

#### Request parameters
**API reference:** `po-documents-notes-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `content` | string | Yes | Note content (required). |
| `title` | string | No | Optional title. |
| `category` | string | No | Category (default: general). (allowed: general, review, legal, technical, financial, internal) |
| `is_pinned` | integer | No | Pin note to top (0 = no, 1 = yes, default: 0) (allowed: 0, 1) |
| `is_private` | integer | No | Private note visible only to you (0 = no, 1 = yes, default: 0) (allowed: 0, 1) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; key fields: `note_id`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete document

`DELETE https://api.paperoffice.ai/latest/documents/document-delete`

#### Overview
Move a document to trash or permanently delete when trash retention allows. Requires delete permission on the document.

#### Request parameters
**API reference:** `po-documents-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `share_context` | string | No | External share context token JSON for scoped access in a shared workspace. |
| `mode` | string | No | Deletion mode: `trash` (soft delete when trash enabled) or `instant` (permanent; requires confirm:true). (allowed: trash, instant) (default: "trash") |
| `confirm` | boolean | No | Required for bulk delete (>5 POFIDs) or mode=instant. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-delete`

#### Overview
Delete a document comment by comment ID. Requires permission to edit the document or ownership of the comment.

#### Request parameters
**API reference:** `po-documents-comments-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | ID of the comment to delete |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-delete`

#### Overview
Delete an internal document note by note ID.

#### Request parameters
**API reference:** `po-documents-notes-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `note_id` | integer | Yes | ID of the note to delete |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Edit document fields

`POST https://api.paperoffice.ai/latest/documents/document-edit/{pofid}`

#### Overview
Edit document metadata fields (title, dates, custom IDP fields) for a document identified by POFID in the URL path.

#### Request parameters
**API reference:** `po-documents-edit` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice File ID |
| `fields` | object | Yes | Key-Value-pairs with Alias-Keys (document_type, sender_name, total_amount, etc.) or nativen __-Pfade |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document details

`GET https://api.paperoffice.ai/latest/documents/document-get/{pofid}`

#### Overview

Get full document details by POFID — metadata, workspace, processing status, extracted fields, and download references.

**API reference:** `po-documents-get` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes (path) | PaperOffice File ID |
| `share_context` | string | No | External share context token JSON for scoped access in a shared workspace. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get Document Lifecycle

`GET https://api.paperoffice.ai/latest/documents/document-lifecycle-get`

#### Overview
Get lifecycle state for a document — retention stage, legal hold flags, trash status, and next allowed transitions.

#### Request parameters
**API reference:** `po-documents-lifecycle-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document OCR text

`GET https://api.paperoffice.ai/latest/documents/ocr-get`

#### Overview
Returns the OCR-extracted text of a document. Contains text per page with confidence scoring.

#### Request parameters
**API reference:** `po-documents-ocr-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File Document ID |
| `locale` | string | No | OCR language/locale hint (e.g. de-DE). Omit for auto-detect. |
| `page` | integer | No | 1-based page number (omit for full-document OCR text). |
| `include_bounding_boxes` | boolean | No | When true, include OCR bounding-box coordinates per text block. |
| `format` | string | No | Response shape: `json` (structured OCR pages, default) or `text` (plain text without layout). (allowed: json, text) (default: "json") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get trash settings

`GET https://api.paperoffice.ai/latest/documents/trash-settings`

#### Overview
Get or update account-wide trash retention settings.

**GET** (no parameters): returns `trash_retention_days`, `trash_enabled`, `delete_mode_effective_default`, `workspace_tier_effective`, and `_capabilities` (derived from the highest workspace tier on the account). Use this before restore/delete flows — on tiers without trash, deletes are permanent.

**POST/GET with `retention_days`:** root administrator only; value must be 1–3650.

Pair with `GET /documents/workspaces-list` (`_capabilities.trash_enabled` per workspace).

**API reference:** `po-documents-trash-settings` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `retention_days` | integer | No | Optional: set retention period in days before permanent deletion. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Deleted Documents (Trash)

`POST https://api.paperoffice.ai/latest/documents/trash-list`

#### Overview
Displays all soft-deleted documents in the trash. Paginated with days_remaining and is_restorable. Optionally filterable by workspace.

#### Request parameters
**API reference:** `po-documents-trash-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Optional: Filter by workspace |
| `page` | integer | No | Page number (default: 1) |
| `pro_page` | integer | No | Items per page (10-200, default: 50) (default: 50) |
| `per_page` | integer | No | Items per page (10-200, default: 50). Alias of pro_page. (default: 50) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Document Comments

`GET https://api.paperoffice.ai/latest/documents/document-comments`

#### Overview
List comments on a document with author, timestamp, resolution status, and optional thread hierarchy.

#### Request parameters
**API reference:** `po-documents-comments-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `include_resolved` | string | No | Also show resolved comments (default: 0) (allowed: 0, 1) |
| `page_number` | integer | No | Only comments for these page (optional) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Document Notes

`GET https://api.paperoffice.ai/latest/documents/document-notes`

#### Overview
List internal notes on a document with author, category, and timestamps.

#### Request parameters
**API reference:** `po-documents-notes-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `include_private` | string | No | Include private notes of OTHER users (default: false). Your own private notes are always visible regardless of this setting. (allowed: 0, 1) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Document Tags

`GET https://api.paperoffice.ai/latest/documents/document-tags`

#### Overview
List all tags applied to a document with optional color and category metadata.

#### Request parameters
**API reference:** `po-documents-tags-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Legal Holds

`GET https://api.paperoffice.ai/latest/documents/document-legal-holds-list`

#### Overview
List active legal holds in the account with document references, reason, and hold timestamps. Read-only for auditors with list permission; does not modify holds.

#### Request parameters
**API reference:** `po-documents-legal-holds-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Workspace ID to filter holds. Omit both workspace_id and pofid to list ALL legal holds account-wide (compliance mode). |
| `pofid` | string | Yes | PaperOffice File ID to filter holds for a specific document. Omit both workspace_id and pofid for account-wide listing. |
| `active_only` | string | No | Only aktive Holds (default: 1) (allowed: 0, 1) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Move document

`POST https://api.paperoffice.ai/latest/documents/document-move`

#### Overview
Move a document to another folder within the same workspace or to a permitted target workspace.

#### Request parameters
**API reference:** `po-documents-move` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID of the document to move |
| `target_workspace_id` | integer | Yes | ID of the target workspace the document is moved to. |
| `locale` | string | No | Optional locale for folder/path labels during the move. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Place legal hold

`POST https://api.paperoffice.ai/latest/documents/document-legal-hold`

#### Overview

Place a legal hold on a document. Requires `pofid` and a `reason` string (audit trail).

**API reference:** `po-documents-legal-holds-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `reason` | string | Yes | Reason for the legal hold (required, e.g. lawsuit, audit). |
| `reference` | string | No | Optional reference (case ID, matter number). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Remove Document Tag

`POST https://api.paperoffice.ai/latest/documents/document-tag-remove`

#### Overview
Remove a tag from a document without deleting the tag definition from the workspace.

#### Request parameters
**API reference:** `po-documents-tags-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `tag_name` | string | No | Name of the tag to delete (REQUIRED if tag_id not provided) |
| `tag_id` | integer | No | ID of the day to delete (REQUIRED if tag_name not provided) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Rename document

`POST https://api.paperoffice.ai/latest/documents/document-rename`

#### Overview
Rename a document. The original extension is always preserved. Path separators (/, \, .) are rejected. Special characters are removed, leading dots are deleted. Maximum length: 255 characters.

#### Request parameters
**API reference:** `po-documents-rename` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | Document POFID to rename |
| `new_file_name` | string | Yes | New file name (extension preserved if omitted) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Resolve Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-resolve`

#### Overview
Mark a document comment as resolved. Use after the discussed issue is addressed; resolved comments remain visible in history.

#### Request parameters
**API reference:** `po-documents-comments-resolve` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | Root comment ID (not a reply) |
| `resolved` | boolean | No | true = as erledigt mark, false = again open (default: true) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Restore Document from Trash

`POST https://api.paperoffice.ai/latest/documents/document-restore`

#### Overview
Restore one or more soft-deleted documents from the trash. Also supports document folders (`.podf`).

Only restorable while `phase=pending` (not permanently deleted).

**Before calling restore:** check `GET /documents/trash-settings` and `GET /documents/workspaces-list` (`_capabilities.trash_enabled`). On tiers without trash, restore returns HTTP `404`.

**API reference:** `po-documents-restore` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string or array | Yes | POFID or array of POFIDs to restore |
| `target_workspace_id` | integer | No | Optional: Restore to this workspace instead of original |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Search documents (full-text)

`GET https://api.paperoffice.ai/latest/documents/document-search`

#### Overview

Full-text and hybrid document search **within the workspace you provide**.

`workspace_id` is **required** — this endpoint does not search all workspaces in your account. Use `workspace_ids` to search multiple explicit workspaces in one call.

Supports filters, semantic mode, and pagination.

**API reference:** `po-documents-search` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | Yes | Search term (full text, semantic vector, or hybrid keyword+vector). |
| `workspace_id` | integer | Yes | Workspace ID to scope the search (required for single-workspace search). |
| `search_mode` | string | No | Search strategy: intelligent (auto), fulltext, semantic, hybrid, or exact field match (exact requires field_key). (allowed: intelligent, fulltext, semantic, hybrid, exact) (default: "intelligent") |
| `mode` | string | No | Legacy alias for search_mode (same values). |
| `search_scope` | string | No | current = only the workspace in workspace_id; all = all workspaces the bearer may access. (allowed: current, all) (default: "current") |
| `search_preference` | string | No | Bias when mode=intelligent: keyword (BM25), semantic (vectors), or balanced (default). (allowed: keyword, semantic, balanced) (default: "balanced") |
| `field_key` | string | No | Meta-field key for exact mode (required when search_mode=exact). |
| `limit` | integer | No | Maximum results (default 20, max 100). (default: 20) |
| `page` | integer | No | 1-based page number for paginated results. (default: 1) |
| `locale` | string | No | Optional locale hint for query normalization (e.g. de:DE). |
| `workspace_ids` | array | No | Explicit list of workspace IDs (Alternative to search_scope=all). |
| `include_meta_fields` | boolean | No | Include matched meta-field snippets in each hit. (default: false) |
| `include_ocr_preview` | boolean | No | Include short OCR text previews (larger payload). (default: false) |
| `similarity_threshold` | number | No | Minimum semantic similarity score (0.0–1.0, default 0.5). (default: 0.5) |
| `multi_vector` | string | No | Advanced: restrict embedding types used in semantic leg (comma-separated). |
| `vector_weight` | number | No | Hybrid mode: semantic leg weight (0.0–1.0). |
| `bm25_weight` | number | No | Hybrid mode: keyword/BM25 leg weight (0.0–1.0). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Tag Autocomplete

`GET https://api.paperoffice.ai/latest/documents/tag-autocomplete`

#### Overview
Autocomplete tag names used in the account or workspace. Useful for consistent tagging in upload and edit flows.

#### Request parameters
**API reference:** `po-documents-tags-autocomplete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | Yes | Search term (mind. 1 characters) |
| `workspace_id` | integer | No | Optional: Auf Workspace einschraenken |
| `limit` | integer | No | Max. results (default: 20, max: 50) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Transition document lifecycle

`POST https://api.paperoffice.ai/latest/documents/document-lifecycle-transition`

#### Overview
Change the lifecycle status of a document. Only allowed transitions are possible.

#### Request parameters
**API reference:** `po-documents-lifecycle-transition` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID |
| `new_state` | string | Yes | New lifecycle state. (allowed: draft, in_review, approved, published, archived, expired, superseded) |
| `comment` | string | No | Optional comment for the lifecycle transition. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update Document Comment

`POST https://api.paperoffice.ai/latest/documents/document-comment-update`

#### Overview
Update the text of an existing document comment. Only the comment author or users with document edit permission may change content.

#### Request parameters
**API reference:** `po-documents-comments-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `comment_id` | integer | Yes | Document comment ID to update. |
| `content` | string | Yes | New comment text. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update Document Note

`POST https://api.paperoffice.ai/latest/documents/document-note-update`

#### Overview
Update title, category, or content of an existing document note.

#### Request parameters
**API reference:** `po-documents-notes-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `note_id` | integer | Yes | Note ID (Required) |
| `title` | string | No | New title. |
| `content` | string | No | New note content. |
| `category` | string | No | new category (allowed: general, review, legal, technical, financial, internal) |
| `is_pinned` | integer | No | Pin or unpin. (allowed: 0, 1) |
| `is_private` | integer | No | Private or public. (allowed: 0, 1) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Upload document

`POST https://api.paperoffice.ai/latest/documents/document-put`

#### Overview
Upload one or more documents via **multipart/form-data** or provide a **`source_url`** (HTTPS) to fetch a file server-side.

**Workspace (required):** provide **`workspace_id`** or **`workspace_name`** (auto-creates workspace when the name is new).

On success returns **`results[]`** (one object per file with `pofid`, `documents_id`, `filename`, …) — not a top-level `pofid`.

Accepted multipart field names: `file`, `files`, `upload`, `attachment`, `document`, `UploadFiles`.

**Chaining:** On success read **results[0].pofid** (array of upload results; not top-level pofid) from the response for the next API call. Document upload/put. Optional processing_lane sets Start-SLA for AI-DMS enqueue.

**API reference:** `po-documents-upload` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | One of (`file`, `source_url`) | Multipart file field (file, files, upload, attachment, document, UploadFiles). |
| `source_url` | string | One of (`file`, `source_url`) | Alternative: HTTPS URL to download (alias: file_url, document_url). |
| `workspace_id` | integer | One of (`workspace_id`, `workspace_name`) | Target workspace ID. Required unless workspace_name is set. |
| `workspace_name` | string | One of (`workspace_id`, `workspace_name`) | Target workspace name (creates workspace if missing). Required unless workspace_id is set. Example: My Workspace. |
| `processing_mode` | string | No | Upload processing mode. |
| `ai_dms_tier` | string | No | AI-DMS processing tier: basic, premium, or ultra. (allowed: basic, premium, ultra) |
| `document_agent_enabled` | boolean | No | When true, enable document agent automation on upload. |
| `share_context` | object | No | Optional external share token JSON for uploads into a shared workspace. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

#### Required alternatives

Provide **at least one** of: `file` **or** `source_url`.

Provide **at least one** of: `workspace_id` **or** `workspace_name`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; key fields: `results[]` with per-file `pofid` (not a top-level `pofid`). Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Accept workspace share by ID

`POST https://api.paperoffice.ai/latest/paperoffice_account/accept_share_by_id`

#### Overview

Accepts a share from the inbox via share_id.

**API reference:** `po-workspaces-share-accept-by-id` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Share ID from shared_with_me inbox |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Accept workspace share invitation

`POST https://api.paperoffice.ai/latest/paperoffice_account/accept_share`

#### Overview

Accepts a share invitation via token.

**API reference:** `po-workspaces-share-accept` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_token` | string | No | Invitation token from email link |
| `token` | string | No | Alias for share_token |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Cancel pending workspace share

`POST https://api.paperoffice.ai/latest/paperoffice_account/cancel_invite`

#### Overview

Withdraws a pending invitation (owner).

**API reference:** `po-workspaces-share-cancel-invite` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Pending share ID |
| `confirm` | boolean | Yes | Must be true to confirm this destructive action. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Check workspace security access

`POST https://api.paperoffice.ai/latest/workspaces/access-check`

#### Overview

Checks workspace security (password/SMS), ACL, and whether a valid unlock session exists for the bearer.

**API reference:** `po-workspaces-security-check-access` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | string | Yes | Required: Workspace ID to check access for |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create workspace

`POST https://api.paperoffice.ai/latest/documents/workspaces-create`

#### Overview

Create a new workspace to organize documents by client, project, or topic. Optional fields include security tier (`standard`, `business`, `compliance`; legacy alias `confidential` → `business`) and AI-DMS settings. After creation, use `List workspaces` to confirm the new `id`. **Permissions:** Workspace management (`workspaces-create`) — account admin or equivalent role required. **Related:** `List workspaces`, `Update workspace` in the same Headless DMS folder. Optional default_processing_lane (alias processing_lane) sets workspace Start-SLA default for Auto AI-DMS. Workspace priority remains legacy plan-gated queue weight, not Start-SLA.

**API reference:** `po-workspaces-create` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Workspace name (required, must not be empty). |
| `description` | string | No | Description of the workspace. |
| `type` | string | Yes | Business workspace type slug (required). Examples: `ablage`, `abinvoice`, `department`, `agentur`, `akte`, `quote`, `Archive`, `order`, `ausschreibung`, `bauprojekt` — 107 types total (use the workspace type picker in the app or MCP workspace tools; invalid values return `allowed_types_hint`). |
| `workspace_tier` | string | No | Security tier: `standard` (no recycle bin), `business` (recycle bin + sharing), `compliance` (business + compliance watermark). Legacy alias: `confidential` is accepted and normalized to `business`. (allowed: standard, business, compliance) (default: "standard") |
| `is_revision_secure` | boolean | No | Enable revision-safe mode (WORM protection). Once activated, cannot be disabled. Requires PaperOffice EU Cloud. (default: false) |
| `retention_years` | integer | No | Retention period in years (default: 10 years, GoBD-compliant). |
| `ai_dms_mode` | string | No | AI-DMS processing mode for the workspace. Allowed: disabled, basic, premium, ultra. Default: disabled. (allowed: disabled, basic, premium, ultra) (default: "disabled") |
| `storage_mode` | string | No | Storage mode: 'cloud' (PaperOffice EU Cloud) or 'byos' (Bring Your Own Storage). After creation, not deletable. (allowed: cloud, byos) (default: "cloud") |
| `storage_mount_id` | integer | No | Identify the Storage Mounts for BYOS Mode. |
| `storage_mount_path` | string | No | Path on the Storage Mount for BYOS mode. |
| `default_locale` | string | No | Default language/region in the Format 'de:DE', 'en:US' etc. |
| `image` | string | No | Image URL for the workspace. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. For workspaces: legacy plan-gated weight 100–999 — not Start-SLA; use default_processing_lane. (default: 500) |
| `is_default` | boolean | No | Mark as standard workspace. |
| `is_stealth` | boolean | No | Workspace im Stealth-Modus (versteckt). |
| `is_archived` | boolean | No | Archive workspace. |
| `workspace_password` | string | No | Password for the workspace access. |
| `color` | string | No | Color code the workspace. |
| `icon` | string | No | Icon the workspace. |
| `tags` | array | No | Tags for the workspace. |
| `contact_salutation` | string | No | Salutation Ansprechpartners. |
| `contact_firstname` | string | No | First name of the contact person. |
| `contact_lastname` | string | No | Last name of the contact person. |
| `contact_email` | string | No | E-Mail the Ansprechpartners. |
| `contact_phone` | string | No | Telefon the Ansprechpartners. |
| `company_name` | string | No | Firmenname. |
| `address_street` | string | No | Street address. |
| `address_zip` | string | No | Postal code. |
| `address_city` | string | No | City. |
| `address_country` | string | No | Country code (ISO 3166-1 alpha-2). |
| `metadata` | object | No | Additional metadata as JSON object. |
| `default_processing_lane` | string | No | Workspace default Start-SLA. Used when Auto AI-DMS omits processing_lane. Alias: processing_lane. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create workspace share

`POST https://api.paperoffice.ai/latest/paperoffice_account/share_workspace`

#### Overview
Create an external workspace share (email and/or telephony channel).

**Requires** `workspace_tier: business` (or legacy `confidential`) on the target workspace. `standard` workspaces return `WORKSPACE_TIER_NOT_SHAREABLE`. Check `GET /documents/workspaces-list` (`workspace_tier` or `_capabilities`) before calling.

Owner permissions are enforced by the Bearer token scope.

**HTTP status:** Returns **201 Created** on success (also accept **200** in clients).
**Performance:** The HTTP response is synchronous. When email or SMS delivery is enabled, expect **10–30 seconds** latency while invitations are sent before the JSON response returns.

**API reference:** `po-workspaces-share-create` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Workspace ID to share |
| `target_email` | string | No | Recipient email (required when share_document_access=true) |
| `share_document_access` | boolean | No | Enable email/document channel (default: true) |
| `telephony_enabled` | boolean | No | Enable telephony channel (default: false) |
| `access_level` | string | No | Share access level (read, write, admin) (allowed: read, write, admin) |
| `message` | string | No | Invitation message |
| `expires_days` | integer | No | Share validity in days (1–3650, default 30). (default: 30) |
| `require_2fa` | boolean | No | When true, recipient must complete 2FA before access. |
| `require_strict_email_match` | boolean | No | When true, login email must exactly match target_email. |
| `folder_restriction` | string | No | Optional folder restriction JSON |
| `telephony_registered_phones` | array | No | E.164 phone numbers allowed to call the share IVR (array of strings). |
| `telephony_pin` | string | No | Optional PIN callers must enter after the voice prompt. |
| `telephony_language` | string | No | IVR language code (e.g. de, en) for voice prompts. |
| `telephony_prompt_addon` | string | No | Optional extra text appended to the spoken welcome prompt. |
| `telephony_voice` | string | No | TTS voice ID override for telephony prompts (provider-specific). |
| `telephony_delivery_email` | string | No | Email address for telephony access links or notifications. |
| `telephony_delivery_security_mode` | string | No | How access credentials are delivered: link, pin, or sms. |
| `telephony_delivery_sms_phone` | string | No | SMS destination when telephony_delivery_security_mode=sms. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `share_id`. Optional `_billing` and `processing_time`. Success HTTP: **200** or **201**. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Decline workspace share invitation

`POST https://api.paperoffice.ai/latest/paperoffice_account/decline_share`

#### Overview

Declines a pending workspace share invitation.

**API reference:** `po-workspaces-share-decline` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Share ID to decline |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get workspace share info by token

`GET https://api.paperoffice.ai/latest/paperoffice_account/share_info`

#### Overview

Public share metadata by token (no login). Provide `token` or `share_token` query parameter from the share invite link.

**API reference:** `po-workspaces-share-info` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | string | Yes | Share token from invite link. |
| `share_token` | string | No | Alias for token. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get workspace telephony agent assignment

`GET https://api.paperoffice.ai/latest/paperoffice_account/workspace_telephony_agent`

#### Overview

Read conversation agent assignment for phone shares in the workspace.

**API reference:** `po-workspaces-telephony-agent-get` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Numeric workspace ID. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List external workspace users

`GET https://api.paperoffice.ai/latest/paperoffice_account/external_users`

#### Overview

Lists external users with workspace access (admin view, root/administrator).

**API reference:** `po-workspaces-external-users-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List my workspace shares

`GET https://api.paperoffice.ai/latest/paperoffice_account/my_shares`

#### Overview

Lists shares created by the current user as owner.

**API reference:** `po-workspaces-shares-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | No | Optional: filter by workspace |
| `include_history` | boolean | No | Include revoked/expired shares (default: false) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List workspaces

`GET https://api.paperoffice.ai/latest/documents/workspaces-list`

#### Overview

List all workspaces accessible to the authenticated account. Returns workspace `id`, `name`, `type`, document counts, and storage metadata when available. Use this before uploads, searches, or updates that require a `workspace_id`. **Permissions:** Workspace management (`workspaces-list`) — account admin or equivalent role required. **Related:** `Create workspace`, `Update workspace` in the same Headless DMS folder.

**API reference:** `po-workspaces-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | string | No | Response language: de_DE, en_US, es_ES, fr_FR, it_IT, pt_PT |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List workspaces shared with me

`GET https://api.paperoffice.ai/latest/paperoffice_account/shared_with_me`

#### Overview

Lists workspaces shared with the current user (recipient perspective).

**API reference:** `po-workspaces-shares-shared-with-me` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Resend workspace share invitation

`POST https://api.paperoffice.ai/latest/paperoffice_account/resend_invite`

#### Overview

Resends a pending share invitation (owner only, rate-limited).

**API reference:** `po-workspaces-share-resend-invite` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Pending share ID |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Revoke or leave workspace share

`POST https://api.paperoffice.ai/latest/paperoffice_account/revoke_share`

#### Overview

Revokes a share (owner) or leaves it (recipient).

**API reference:** `po-workspaces-share-revoke` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Share ID to revoke or leave |
| `confirm` | boolean | Yes | Must be true to confirm this destructive action. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Set workspace telephony agent assignment

`POST https://api.paperoffice.ai/latest/paperoffice_account/workspace_set_telephony_agent`

#### Overview

Set or remove the primary conversation agent for phone shares (funnel_id=0 clears assignment).

**API reference:** `po-workspaces-telephony-agent-set` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Numeric workspace ID. |
| `funnel_id` | integer | Yes | Conversation Agent funnel ID (0 = clear assignment) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update workspace

`POST https://api.paperoffice.ai/latest/documents/workspaces-update`

#### Overview
Update an existing workspace — rename, change description, adjust security tier, or metadata.

Call `GET /documents/workspaces-list` first to obtain the numeric workspace ID.

**ID parameter:** send `id` (canonical) or `workspace_id` (alias accepted by the API).

Partial updates are supported where noted in the parameter schema. Optional default_processing_lane (alias processing_lane) updates workspace Start-SLA default for Auto AI-DMS. Workspace priority remains legacy plan-gated queue weight, not Start-SLA.

**API reference:** `po-workspaces-update` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | Yes | Workspace ID from workspaces-list (canonical). |
| `name` | string | No | New workspace name. |
| `description` | string | No | New description. |
| `workspace_tier` | string | No | Security tier (only Upgrade erlaubt, no Downgrade). (allowed: standard, confidential, compliance) |
| `is_revision_secure` | boolean | No | Enable revision-safe mode (one-time, irreversible). |
| `retention_years` | integer | No | Retention period in years. Increase allowed only for WORM only. |
| `ai_dms_mode` | string | No | AI-DMS processing mode for the workspace. When changed, existing documents may be reprocessed according to the new mode. (allowed: disabled, basic, premium, ultra) |
| `default_locale` | string | No | Default language/region. |
| `workspace_password` | string | No | New workspace password. |
| `status` | string | No | Workspace-Status. |
| `type` | string | No | Business workspace type (optional on update). |
| `image` | string | No | Image URL. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. For workspaces: legacy plan-gated weight 100–999 — not Start-SLA; use default_processing_lane. |
| `is_default` | boolean | No | Mark as standard. |
| `is_stealth` | boolean | No | Stealth-Modus. |
| `is_archived` | boolean | No | Archiviert. |
| `color` | string | No | Color code. |
| `icon` | string | No | Workspace icon key or emoji shown in the UI. |
| `tags` | array | No | Comma-separated workspace tags for filtering. |
| `contact_salutation` | string | No | Contact salutation (e.g. Mr, Ms, Dr). |
| `contact_firstname` | string | No | Contact given name for workspace metadata. |
| `contact_lastname` | string | No | Contact family name for workspace metadata. |
| `contact_email` | string | No | Contact email address for workspace metadata. |
| `contact_phone` | string | No | Contact phone number (E.164 recommended). |
| `company_name` | string | No | Company or organization name. |
| `address_street` | string | No | Street address line. |
| `address_zip` | string | No | Postal or ZIP code. |
| `address_city` | string | No | City name. |
| `address_country` | string | No | Country ISO 3166-1 alpha-2 code. |
| `metadata` | object | No | Additional Metadaten. |
| `password_enabled` | boolean | No | Enable or disable password protection. |
| `sms_enabled` | boolean | No | SMS-Verifizierung enable. |
| `sms_phone` | string | No | Phone number for SMS verification. |
| `dual_auth_enabled` | boolean | No | 2-persons-approval enable. |
| `dual_auth_phone_1` | string | No | Phone number Person 1. |
| `dual_auth_phone_2` | string | No | Phone number Person 2. |
| `workspace_id` | integer | No | Alias for `id` (same numeric workspace ID). |
| `default_processing_lane` | string | No | Workspace default Start-SLA. Used when Auto AI-DMS omits processing_lane. Alias: processing_lane. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) (default: "no_sla") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update workspace share

`POST https://api.paperoffice.ai/latest/paperoffice_account/update_share`

#### Overview

Updates permissions and settings of an existing workspace share (owner only).

**API reference:** `po-workspaces-share-update` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `share_id` | integer | Yes | Workspace share ID to update or revoke. |
| `access_level` | string | No | Share access level (read, write, admin) (allowed: read, write, admin) |
| `require_2fa` | boolean | No | When true, recipient must complete 2FA before access. |
| `require_strict_email_match` | boolean | No | When true, login email must exactly match the invited address. |
| `folder_restriction` | string | No | JSON array of folder IDs the share may access (omit for full workspace). |
| `expires_at` | string | No | ISO 8601 expiry timestamp (UTC). |
| `telephony_enabled` | boolean | No | Enable or disable the telephony channel for this share. |
| `telephony_registered_phones` | array | No | E.164 phone numbers allowed to call the share IVR (array of strings). |
| `telephony_pin` | string | No | Optional PIN callers must enter after the voice prompt. |
| `telephony_language` | string | No | IVR language code (e.g. de, en) for voice prompts. |
| `telephony_prompt_addon` | string | No | Optional extra text appended to the spoken welcome prompt. |
| `telephony_voice` | string | No | TTS voice ID override for telephony prompts (provider-specific). |
| `telephony_delivery_email` | string | No | Email address for telephony access links or notifications. |
| `telephony_delivery_security_mode` | string | No | How access credentials are delivered: link, pin, or sms. |
| `telephony_delivery_sms_phone` | string | No | SMS destination when telephony_delivery_security_mode=sms. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Validate Workspace Storage Health

`POST https://api.paperoffice.ai/latest/documents/workspace-storage-health`

#### Overview
Check storage connectivity and health for a workspace — cloud mode, **BYOS** (Bring Your Own Storage) mount status, latency, offline detection, and auto-lock reasons.

Especially relevant for workspaces that use **Storage Mounts** with external SSH/SFTP storage.

Requires workspace **view** permission.

#### Request parameters
**API reference:** `po-workspaces-validate-storage` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Workspace ID to check |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — E-Signatures

### Cancel signature request (eSignatures API)

`POST https://api.paperoffice.ai/latest/signatures/cancel`

#### Overview
Cancel a pending e-signature request. Signers can no longer complete after cancellation; completed requests cannot be cancelled.

#### Request parameters
**API reference:** `po-esignatures-cancel-signature-request` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID (default: "") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Configure signing reminders

`GET https://api.paperoffice.ai/latest/signature_link/get_reminder_settings`

#### Overview
Returns global reminder settings for signing requests (**GET only**).

To update settings, use `POST /signature_link/save_reminder_settings` (`po_signature_link_save_reminder_settings`).

**API reference:** `po-signing-reminders-configure` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `action` | string | Yes | get = read settings, save = save settings (allowed: get, save) |
| `reminder_enabled` | boolean | No | Enable/disable reminders (only for save) |
| `first_after_days` | number | No | Days until first reminder |
| `interval_days` | number | No | Days between reminders |
| `max_count` | number | No | Maximum number of reminders |
| `channels` | array | No | Channels: email, sms |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create signature request (eSignatures API)

`POST https://api.paperoffice.ai/latest/signatures/create`

#### Overview

Create an e-signature request. Requires `document_pofid` (or `pofid`) and a `signers` array; each signer needs `name`, `email`, and `phone` (E.164, required for SMS verification).

**API reference:** `po-esignatures-create-signature-request` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | One of (`document_pofid`, `pofid`) | Alias for document_pofid. |
| `document_pofid` | string | One of (`document_pofid`, `pofid`) | POFID of the document to sign (required). |
| `signers` | array | Yes | Signers array; each entry requires name, email, and phone (E.164). |
| `channel` | string | No | Delivery channel (default email). Use none for headless signing_url only. (allowed: email, none) |
| `signature_type` | string | No | Signature compliance tier (default: ses). (allowed: ses, aes, qes) |
| `signing_order` | string | No | Signing order (default: parallel). (allowed: parallel, sequential) |
| `expires_days` | integer | No | Validity period in days (default: 7, max: 90). |
| `message` | string | No | Optional message to signers. |

#### Required alternatives

Provide **at least one** of: `document_pofid` **or** `pofid`.

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create signature request (signing link)

`POST https://api.paperoffice.ai/latest/signature_link/create_and_send`

#### Overview
Create a signing request and send invitations.

Each signer requires `name`, `email`, and **`phone` (E.164)** — SMS verification is enforced by default even when `channel` is `none`.

**Latency:** `channel: "email"` may block this HTTP request while SMTP delivery runs (often 20+ seconds). For API automation and tests, use `channel: "none"` and deliver links separately; production email sending may move to async delivery in a future release.

**API reference:** `po-signing-request-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_pofid` | string | Yes | POFID of the document to sign (required). |
| `signers` | array | Yes | Signers array; each entry requires name, email, and phone (E.164). |
| `channel` | string | No | Delivery channel (default: email) (allowed: email, sms, both, none) |
| `message` | string | No | Personal message to signers |
| `expires_days` | number | No | Validity period in days (default: 30) |
| `language` | string | No | Language (de, en, es, fr, ...) |
| `signature_fields` | array | No | Positioning of signature fields in the PDF |
| `reminder` | object | No | Reminder configuration |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Download eSignature Document

`GET https://api.paperoffice.ai/latest/signatures/download`

#### Overview

Download the signed PDF for a completed e-signature request. Provide the signature request UUID from create/status endpoints; returns the final signed document file.

**API reference:** `po-esignatures-download-signed-document` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Generate mobile signing link

`POST https://api.paperoffice.ai/latest/signature_link/generate_mobile_token`

#### Overview
Generate a mobile-friendly signing URL (QR code flow). **JSON body required** — send `application/json`, not multipart.

**Required:** `document_pofid` (POFID of the document to sign).

**API reference:** `po-signing-mobile-link-generate` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_pofid` | string | Yes | Document PO-FID for mobile QR signing. |
| `document_name` | string | No | Display name shown to the signer on mobile. |
| `expires_hours` | integer | No | Link validity in hours (default 24). (default: 24) |
| `language` | string | No | Signer UI language code (e.g. de, en). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get signature details

`GET https://api.paperoffice.ai/latest/signatures/get`

#### Overview

Get status and signer details for an e-signature request — pending, completed, or declined.

**API reference:** `po-esignatures-get-signature-details` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List signature requests (eSignatures API)

`GET https://api.paperoffice.ai/latest/signatures/list`

#### Overview
List e-signature requests with status filters — pending, completed, declined, or expired.

#### Request parameters
**API reference:** `po-esignatures-list-signature-requests` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter by signature status (pending, completed, declined, expired). (allowed: draft, pending, sent, completed, declined, expired, cancelled) |
| `page` | integer | No | Page number for pagination (1-based). (default: 1) |
| `limit` | integer | No | Number of results per page. (default: 20) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List signature requests (signing link / batch)

`POST https://api.paperoffice.ai/latest/signature_link/get_batch_status`

#### Overview
Batch signing status for multiple documents.

**JSON body:** `pofids` — array of POFID strings (alias `document_pofids` also accepted).

**API reference:** `po-signing-requests-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | number | No | Specific request ID for detail view |
| `request_uuid` | string | No | UUID of a request (Alternative to request_id) |
| `document_pofid` | string | One of (`document_pofid`, `pofids`) | POFID to view all signatures of a document |
| `document_pofids` | array | No | Deprecated alias for pofids. |
| `status` | string | No | Filter by status (allowed: draft, pending, completed, cancelled, expired) |
| `page` | number | No | Page (default: 1) |
| `limit` | number | No | Results per page (default: 20) |
| `pofids` | array | One of (`document_pofid`, `pofids`) | POFID list for batch status (canonical). Alias: document_pofids. |

#### Required alternatives

Provide **at least one** of: `document_pofid` **or** `pofids`.

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List signature types

`GET https://api.paperoffice.ai/latest/signatures/types`

#### Overview
List available signature types and saved signature templates. Returns eIDAS signature levels (SES simple, AES advanced, QES qualified) and stored signature/initial templates for the account. Use before creating signing requests to know available options.

#### Request parameters
**API reference:** `po-signing-types-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `include_types` | boolean | No | Load eIDAS types (default: true) |
| `include_templates` | boolean | No | Load saved templates (default: true) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Save signature template

`POST https://api.paperoffice.ai/latest/signatures/save_template`

#### Overview
Save signer field placements and template metadata for reuse in future e-signature requests.

#### Request parameters
**API reference:** `po-signing-template-save` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_image` | string | Yes | Base64-encoded image of signature/initials |
| `type` | string | No | Template type (default: signature) (allowed: signature, initials) |
| `name` | string | No | Name of the template |
| `is_default` | boolean | No | Set as default template |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Send reminder

`POST https://api.paperoffice.ai/latest/signatures/remind`

#### Overview
Send a reminder email to pending signers on an e-signature request.

#### Request parameters
**API reference:** `po-esignatures-send-reminder` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signature_id` | string | No | Signature request ID (default: "") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Verify signature

`POST https://api.paperoffice.ai/latest/signature_link/verify_document`

#### Overview
Verify, check and validate digital signatures on a document. Validates signature integrity, certificate chain, eIDAS compliance (SES/AES/QES). Accepts POFID, upload_id, or file_url.

#### Request parameters
**API reference:** `po-signing-verify` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_pofid` | string | One of (`document_pofid`, `file_url`, `upload_id`) | POFID of the document to verify |
| `upload_id` | string | One of (`document_pofid`, `file_url`, `upload_id`) | Upload ID from the upload page |
| `file_url` | string | One of (`document_pofid`, `file_url`, `upload_id`) | Public URL of a PDF file |
| `file_name` | string | No | Filename for uploaded file |

#### Required alternatives

Provide **at least one** of: `document_pofid` **or** `file_url` **or** `upload_id`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Cancel signing request (signing link)

`POST https://api.paperoffice.ai/latest/signature_link/cancel_signing_request`

#### Overview
Cancel a pending signing-link request by signing ID. Signers can no longer complete after cancellation.

**API reference:** `po-signature-links-cancel-signing-request` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | Yes | Signing request ID to cancel. |
| `reason` | string | No | Optional cancellation reason. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Check signing status

`GET https://api.paperoffice.ai/latest/signature_link/get_signing_status`

#### Overview
Check the signing status of a signature-link request — pending, completed, or expired.

#### Request parameters
**API reference:** `po-signature-links-check-signing-status` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | Yes | Signing request ID (legacy alias: signing_id). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Download Signing Link Document

`GET https://api.paperoffice.ai/latest/signature_link/download_signed_document`

#### Overview
Download a signed PDF or certificate.

- **Authenticated:** pass `request_id` (alias `signing_id`).
- **Public signer link:** pass `token` query parameter (no Bearer).

Optional `type`: `full` (default) or `certificate`.

**API reference:** `po-signature-links-download-signed-document` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | No | Authenticated download: signing request ID. |
| `token` | string | No | Public signer download: access token from signing URL (?token=). |
| `type` | string | No | Download package: full (signed PDF) or certificate (audit trail only). (allowed: full, certificate) (default: "full") |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get document signatures

`GET https://api.paperoffice.ai/latest/signature_link/get_document_signatures`

#### Overview
List signature records and signer status for a document accessed via signature links.

#### Request parameters
**API reference:** `po-signature-links-get-document-signatures` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_pofid` | string | Yes | Document PO-FID (aliases: pofid, document_id). |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Resend invitation

`POST https://api.paperoffice.ai/latest/signature_link/resend_invitation`

#### Overview
Resend a signing invitation email for a pending signature-link participant.

#### Request parameters
**API reference:** `po-signature-links-resend-invitation` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `signer_id` | integer | Yes | Signer row ID from signatures table (legacy alias: invitation_id). |
| `channel` | string | No | Delivery channel for the invitation (currently email only). (allowed: email) (default: "email") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Save signing reminder settings

`POST https://api.paperoffice.ai/latest/signature_link/save_reminder_settings`

#### Overview
Persist **account-wide** signing reminder defaults (not per signing request).

with JSON or form body.

To read current values use `GET /signature_link/get_reminder_settings`.

**API reference:** `po-signature-link-save-reminder-settings` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `reminder_enabled` | boolean | No | Enable automatic reminders (default true). |
| `first_after_days` | integer | No | Days after send before first reminder (default 2). |
| `interval_days` | integer | No | Days between follow-up reminders (default 2). |
| `max_count` | integer | No | Maximum reminders per signer (default 3). |
| `channels` | array | No | Delivery channels, e.g. ["email"] or ["email","sms"]. |
| `sms_window_start` | string | No | SMS window start HH:MM (default 09:00). |
| `sms_window_end` | string | No | SMS window end HH:MM (default 20:00). |
| `escalate_to_sender` | boolean | No | Notify sender after max reminders (default true). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Send Signing Request

`POST https://api.paperoffice.ai/latest/signature_link/send_signing_request`

#### Overview
Send a signature-link signing request to one or more external signers.

#### Request parameters
**API reference:** `po-signature-links-send-signing-request` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `request_id` | string | Yes | Signature request ID |
| `signers` | array | No | Array of signer objects with name and email |
| `message` | string | No | Message to the signer |
| `channel` | string | No | Delivery channel (allowed: email, sms) (default: "email") |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Sign document

`POST https://api.paperoffice.ai/latest/signature_link/sign`

#### Overview
Signer-facing **public** endpoint — **no Bearer token**. Submit a signature image or text for an active signing request.

#### Request parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token` | string | Yes | Signing token from the invitation email/SMS (`?token=` query parameter) |
| `signature_data` | string | No | Base64 PNG signature image (drawn signature) |
| `signer_name` | string | No | Display name for text-field signatures |

**API reference:** `po-signature-links-sign-document` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `verified_token` | string | No | Verification token after OTP check. |
| `signature` | string | Yes | Signature payload (Base64 PNG for drawn signatures, plain text for typed signatures). |
| `signature_type` | string | No | Signature method: drawn, typed, or uploaded image. (allowed: draw, type, upload) (default: "draw") |
| `signer_name` | string | No | Signer name (for text-field signature) |
| `client_data` | object | No | Additional client data (IP, timestamp, User-Agent). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Verify otp

`POST https://api.paperoffice.ai/latest/signature_link/verify_otp`

#### Overview
Signer-facing **public** endpoint — **no Bearer token**. Verifies the one-time password (OTP) for a signing-link session.

#### Request parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `token` | string | Yes | Signing token from the invitation (`?token=` query parameter) |
| `otp` | string | Yes | OTP code from SMS or email |

**API reference:** `po-signature-links-verify-otp` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `otp` | string | Yes | One-time password for identity verification (6 digits). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — HITL

### Approve Task (Legacy)

`POST https://api.paperoffice.ai/latest/hitl_review/approve`

#### Overview

Legacy alias of po_tasks_resolve_task with decision=approve. Same HITL consensus kernel as /workflow_tasks/resolve. Prefer po_tasks_resolve_task. There is no MCP tool named po_hitl_submit_review.

**API reference:** `po-hitl-approve` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Task UUID (required). |
| `result` | object | No | Optional structured review result payload. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Claim Review Task

`POST https://api.paperoffice.ai/latest/hitl_review/claim`

#### Overview

Claim a pending/awaiting_reviews task. Blind review enforced.

**API reference:** `po-hitl-claim` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Task UUID (required). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Complete Task (Legacy)

`POST https://api.paperoffice.ai/latest/hitl_review/complete`

#### Overview

Legacy alias of po_tasks_resolve_task with decision=approve (complete). Prefer po_tasks_resolve_task. There is no MCP tool named po_hitl_submit_review.

**API reference:** `po-hitl-complete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Task UUID (required). |
| `result` | object | No | Optional structured review result payload. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### HITL Health Check

`GET https://api.paperoffice.ai/latest/hitl_review/check`

#### Overview

Health check for HITL review service.

**API reference:** `po-hitl-check` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Reject Task (Legacy)

`POST https://api.paperoffice.ai/latest/hitl_review/reject`

#### Overview

Legacy alias of po_tasks_resolve_task with decision=reject. Requires a reason. Prefer po_tasks_resolve_task. There is no MCP tool named po_hitl_submit_review.

**API reference:** `po-hitl-reject` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Task UUID (required). |
| `reason` | string | No | Rejection reason (required). |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — Import & Migration

### Cancel import job

`POST https://api.paperoffice.ai/latest/import/import-cancel`

#### Overview
Cancel a running import job. Already imported files remain; queued work is stopped.

#### Request parameters
**API reference:** `po-import-cancel` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job to cancel. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create import job

`POST https://api.paperoffice.ai/latest/import/import-create`

#### Overview
Create an import job.

**Recommended ZIP flow:**
1. `POST /import/upload-source` (multipart `file` = ZIP) → copy `data.temp_file_id`
2. `POST /import/import-create` with `source_type: local_upload` (or `elo_office`) and `source_config: { "temp_file_id": "<handle>" }`

For SFTP/S3/WebDAV, use the matching `source_type` with a JSON `source_config` object (`host`, credentials, `path`). Create import job. Optional processing_lane is persisted and applied when documents are enqueued.

**API reference:** `po-import-create` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `workspace_id` | integer | Yes | Target workspace into which the files will be imported |
| `source_type` | string | Yes | Import source: sftp, local_upload, or watchfolder. (allowed: sftp, local_upload, watchfolder) |
| `source_config` | object | Yes | Source-specific connection object (see endpoint description). |
| `include_subfolders` | boolean | No | Include subfolders (default: true) |
| `file_pattern` | string | No | File filter pattern, e.g. "*.pdf" (default: "*") |
| `ai_processing` | boolean | No | Enable AI processing (derived from workspace setting if omitted) |
| `ai_tier` | string | No | AI processing tier (basic, premium, ultra) (allowed: basic, premium, ultra) |
| `max_file_size_mb` | integer | No | Optional max file size in MB (default server limit). |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `import_job_id`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete import job

`POST https://api.paperoffice.ai/latest/import/import-delete`

#### Overview
Delete an import job record and its temporary staging artifacts. Does not delete documents already committed to the DMS.

#### Request parameters
**API reference:** `po-import-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job to delete, including all file entries. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get import status

`POST https://api.paperoffice.ai/latest/import/import-status`

#### Overview
Returns the current import job status including live file counters.

**Response `data` fields:** `total_files` and `processed_files` (aliases), plus `total_files_found`, `total_files_imported`, `total_files_failed`, `total_files_skipped`, `progress_percent`, `result_state`.

Set `include_report: true` for skip/failure breakdown on completed jobs.

**API reference:** `po-import-status` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job whose current status is queried. |
| `include_report` | boolean | No | Include detailed import report in response |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List import files

`POST https://api.paperoffice.ai/latest/import/import-files`

#### Overview
Return the paginated file list for an import job (per-file status: pending, imported, failed, skipped).

Send `job_id` in a JSON body (`application/json`) or as a query parameter.

**API reference:** `po-import-files` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job whose file list is retrieved. |
| `skip` | integer | No | Number of entries to skip (offset for pagination) |
| `limit` | integer | No | Maximum number files per page (Default: 50, Max: 500) |
| `page` | integer | No | 1-based page for paginated import file listings. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List import jobs

`POST https://api.paperoffice.ai/latest/import/import-jobs-list`

#### Overview
List all import jobs of the account including KPI statistics (Total, Completed, In Progress, Failed).

#### Request parameters
**API reference:** `po-import-jobs-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | No | Maximum number Jobs (Default: 50, Max: 200) |
| `offset` | integer | No | Offset for pagination (Default: 0) |
| `status` | string | No | Filter by job status (pending, scanning, scan_complete, importing, completed, failed, cancelled) (allowed: pending, scanning, scan_complete, importing, completed, failed, cancelled) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Request import upload URL

`POST https://api.paperoffice.ai/latest/import/request-upload-url`

#### Overview
Generate a signed upload URL for **direct file upload** (Cloudflare bypass).

Returns `upload_url`, HMAC `upload_token`, and `expires_in`. An empty POST body is valid when `purpose` defaults to `import/upload-source` (form field or query).

The `upload_url` targets the **direct upload node** for your account cluster (bypasses the CDN). This is intentional for large files.

#### Request parameters
| Parameter | Required | Notes |
|-----------|----------|-------|
| `purpose` | no | `import/upload-source` (default) or `import/upload-local-files` |

**API reference:** `po-import-request-upload-url` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `purpose` | string | Yes | Upload-Zweck (allowed: import/upload-source, import/upload-local-files) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Retry import job

`POST https://api.paperoffice.ai/latest/import/import-retry`

#### Overview
Retry a failed import job from the last checkpoint. Use after fixing source files or connector configuration.

#### Request parameters
**API reference:** `po-import-retry` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job whose failed files are retried. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Scan import source

`POST https://api.paperoffice.ai/latest/import/import-scan`

#### Overview
Scans the import source and lists all found files. Returns count, sizes, and type breakdown.

#### Request parameters
**API reference:** `po-import-scan` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | ID of the import job for which the source is scanned. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Start import job

`POST https://api.paperoffice.ai/latest/import/import-start`

#### Overview

Start the import process (in batches, 50 files per call). Repeat calls until all files are imported.

**API reference:** `po-import-start` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | integer | Yes | Identify the import jobs that have started (status must be scan_complete) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Upload local files to import

`POST https://api.paperoffice.ai/latest/import/upload-local-files`

#### Overview
Upload multiple files with folder structure (local batch import).

Files are grouped in a temporary account-scoped import session for the duration of the import job. Use `session_id` to correlate batches from the same import run.

#### Request parameters
**API reference:** `po-import-upload-local-files` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | Files to upload as multipart/form-data (field name `files[]`). |
| `relative_paths` | array | No | Relative paths for files to preserve folder structure |
| `session_id` | string | No | Optional session identifier to group related upload batches. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Upload ZIP source for import

`POST https://api.paperoffice.ai/latest/import/upload-source`

#### Overview
Upload a ZIP archive for bulk import (ELO export or local_upload ZIP mode).

**Response:** `data.temp_file_id` (opaque handle) — **not** an internal server path.

**Next step:** `POST /import/import-create` with `source_type: local_upload` or `elo_office` and `source_config: { "temp_file_id": "<from upload-source>" }`.

Legacy `source_config.zip_path` with an absolute server path is still accepted for backward compatibility but is not returned by this endpoint.

**API reference:** `po-import-upload-source` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | ZIP-file |
| `source_type` | string | No | Import source type (e.g. zip_upload, cloud_connector). (allowed: elo_office, local_upload) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — OCR & IDP

### Analyze document with AI-OCR

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview
AI-powered OCR document analysis — extract text, detect tables, layout, bounding boxes. Modes: text (fast), grid (+ bounding boxes/QR), complete (+ tables/layout/markdown). Optional: create searchable PDF. File input: upload_id (preferred), file_url, or pofid. Call without file input to get an upload link.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `upload_id` | string | No | Upload ID from the upload page |
| `file_url` | string | One of (`file_1`, `file_url`, `pofid`) | Public URL of a PDF or image (Alternative to file_1 upload). |
| `file_name` | string | No | Filename (e.g. "invoice.pdf", "scan.png") |
| `pofid` | string | One of (`file_1`, `file_url`, `pofid`) | PaperOffice File ID (Alternative to file_1 upload). |
| `ocr_mode` | string | No | "text" = text only (about 3s/page), "grid" = + bounding boxes (about 5s/page), "complete" = + tables/layout (about 7s/page). Default: "complete" (allowed: text, grid, complete) |
| `output_searchable_pdf` | boolean | No | Create searchable PDF (sandwich PDF with invisible OCR layer). Default: false |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `file_1` | string | One of (`file_1`, `file_url`, `pofid`) | Image or PDF upload (multipart). Supported: PNG, JPG, JPEG, TIFF, BMP, WEBP, PDF. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

#### Required alternatives

Provide **at least one** of: `file_1` **or** `file_url` **or** `pofid`.

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract AI-OCR grid boxes

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview

Extract AI-OCR grid boxes (layout regions) from a document. Useful for table detection and coordinate-based extraction. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "grid") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract AI-OCR plain text

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview

Extract plain text from a document via AI-OCR without full layout analysis. Fast path for searchable text. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "text") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Run complete AI-OCR analysis

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview

Run a complete AI-OCR analysis on a document. Returns structured text, layout blocks, tables, and confidence metadata in one job. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `ocr_mode` | string | No | OCR mode: text fastest, text only, grid + bounding boxes, complete + tables + layout (default: "complete") |
| `output_searchable_pdf` | string | No | Create searchable PDF Sandwich PDF with invisible OCR layer. Default: false (default: "false") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract ID card or passport

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Extract structured fields from ID cards and passports — name, document number, nationality, and expiry date. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "identity_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract insurance policy

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract insurance policy fields — policy number, insured party, coverage period, and premium.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "insurance_policy") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract legal document

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract structured sections and parties from legal documents and contracts.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "legal_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract payroll / pay stub

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Payroll / Pay Stub Extract salary and payroll data. Fields: employee_name, pay_period, gross, net, deductions, taxes, employer

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "payroll") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract government form data

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview
Extract data from government and official forms (applications, civic/ID forms). Fields: all_fields, checkboxes, signatures. Pipeline: paperoffice_aiocr___generate — not IDP workflow.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "government_forms") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract handwritten customer form

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview
Handwritten customer/intake form recognition (filled forms). Fields: extracted_text, confidence, language. Pipeline: paperoffice_aiocr___generate.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "handwritten_customer_form") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract handwritten document

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview

General handwritten page/note recognition (not a structured intake form). Fields: extracted_text, confidence, language. Pipeline: paperoffice_aiocr___generate. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "handwritten_document") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract US tax forms

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_aiocr___generate`

#### Overview
Extract data from US tax forms (W-2, 1040, 1099 and similar). Fields: all_fields, checkboxes, signatures. Pipeline: paperoffice_aiocr___generate — not IDP workflow.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "us_tax_forms") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract hotel invoice

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract hotel invoice fields — guest, stay dates, room charges, taxes, and total amount.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "hotel_invoice") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Export DATEV SKR03 accounting

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract structured accounting data in DATEV SKR03 format. Fields: document date, document number, posting text, debit/credit account, amount, tax rate.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "accounting_datev") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract bank check data

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Extract structured data from bank checks — payer, payee, amount, MICR line, and date fields. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "bank_check") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract bank details

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract bank account details from financial documents — IBAN, BIC, account holder, and bank name fields.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "basic") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "bank_details") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract cash receipt data

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract structured fields from cash receipts — amount, date, vendor, and payment method.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "cash_receipt") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract custom fields (IDP)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract custom IDP field definitions configured for the account from uploaded documents.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_fields` | string | No | Custom extraction fields as JSON array (default: "[{\"key\":\"company_name\",\"description\":\"Name of the company\"},{\"key\":\"invoice_number\",\"description\":\"Invoice number\"},{\"key\":\"total_amount\",\"description\":\"Total amount with currency\"}]") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract invoice

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Extract invoice fields — vendor, line items, amounts, tax, due date, and reference numbers. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP template name. Default: invoice (English). For localized versions use the dedicated tools (e.g. the German/DATEV-optimized extraction profile in Document AI). Advanced: append :lang:LOCALE for custom localization e.g. invoice:fr:FR (default: "invoice") |
| `idp_fields` | string | No | OPTIONAL: Additional fields as JSON, e.g., {"key":"has_stamp","description":"Is there a stamp?"} (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract invoice (German/DATEV-optimized)

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract data from German invoices with DATEV-compatible fields. Fields: invoice number, date, supplier, customer, net, gross, VAT, IBAN, BIC.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | invoice:de = German output, invoice:en = English, invoice:es = Spanish (default: "invoice:de") |
| `idp_fields` | string | No | OPTIONAL: Additional fields as JSON (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract invoice basic fields

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Lightweight invoice extraction with essential fields only — vendor, total, date, and invoice number.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "basic") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "idp_light") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract statement of account

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract account statement fields — period, opening balance, transactions, and closing balance.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "statement_of_account") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract utility bill

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract utility bill fields — provider, billing period, consumption, and amount due.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "utility_bill") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract letter or mail

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Letter / Mail Extract letter metadata and content. Fields: sender, recipient, date, subject, body_summary Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "letter_mail") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract receipt

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract retail receipt fields — merchant, line items, tax, and total.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "receipt") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract delivery note

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract delivery note fields — shipper, recipient, items, quantities, and delivery date.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "delivery_note") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract purchase order

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract structured purchase order data from an uploaded document via the workflow job pipeline.

**Fields extracted:** order_number, date, vendor, buyer, items, delivery_date, total.

Submit with **POST /job/add/workflow** using multipart `file` (or `pofid`) plus required workflow discriminator fields. See **Parameters** below. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "order") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract shipping waybill

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract shipping waybill fields — tracking number, carrier, sender, recipient, and weight.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "shipping_waybill") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract construction plan/blueprint

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Extract metadata and annotations from construction plans and blueprints via AI-IDP workflow.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "ultra") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "construction_plan") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Extract vehicle registration

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Vehicle Registration Extract vehicle registration data. Fields: plate_number, make, model, VIN, owner, registration_date

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `model` | string | Yes | AI processing tier (flat pricing). Basic=OCR+Vision, Premium=+AI thinking, Ultra=+AI reasoning. per/per-Max variants add higher page limits. (allowed: basic, basic-per, basic-per-max, premium, premium-per, premium-per-max, ultra, ultra-per, ultra-per-max) (default: "premium") |
| `idp_collection` | string | No | IDP collection slug for workflow discrimination (e.g. invoice, receipt, bank_check). (default: "vehicle_license") |
| `idp_fields` | string | No | OPTIONAL: Extra fields as JSON array (default: "") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

---

## Document AI — PDF

### Add password to PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___lock_with_password_pdf`

#### Overview
Add password protection to a PDF via the PDF Studio workflow pipeline.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `password` | string | No | PDF password to set (min. 8 characters). |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Compress PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___compress_pdf`

#### Overview

Compress a PDF to reduce file size while preserving readability. Submit with multipart `file`/`files` or a JSON `files` array of HTTPS URLs (Bearer token required for protected demo URLs). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | string | No | Compression quality: low (72dpi, smallest), medium (150dpi, balanced), high (300dpi, best quality), lossless (no quality loss) (allowed: low, medium, high, lossless) (default: "medium") |
| `linearize` | boolean | No | Linearize PDF for fast web view (default: true) |
| `remove_metadata` | boolean | No | Remove metadata during compression (default: false) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert eBook to PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___ebook_to_pdf`

#### Overview

Convert eBooks (EPUB, MOBI) to PDF. Submit via multipart `file`/`file_1`/`files` or JSON `files` with HTTPS URLs. At least one file is required. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | JSON array of HTTPS file URLs or multipart `files[]` uploads. |
| `output_format` | string | No | Output format (default: pdf) (allowed: pdf) |
| `page_size` | string | No | Target page size for e-book conversion (e.g. A4, letter). (allowed: A4, A3, Letter) (default: "A4") |
| `margin` | integer | No | Seitenrand in mm (default: 20) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `file` | string | No | Multipart file upload (primary input). |
| `file_1` | string | No | Multipart file upload field `file_1`. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert images to PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___image_to_pdf`

#### Overview

Convert images (JPG, PNG, TIFF) to PDF. Submit via multipart `file`/`file_1`/`files` or JSON `files` with HTTPS URLs. At least one file is required. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | JSON array of HTTPS file URLs or multipart `files[]` uploads. |
| `fit_to_a4` | boolean | No | Scale the image to A4 format with a white background (default: false) |
| `merge` | boolean | No | Merge all bills into a single PDF (default: true) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `file` | string | No | Multipart file upload (primary input). |
| `file_1` | string | No | Multipart file upload field `file_1`. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert Office files to PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___office_to_pdf`

#### Overview

Convert Office documents (Word, Excel, PowerPoint) to PDF. Submit via multipart `file`/`file_1`/`files` or JSON `files` with HTTPS URLs. At least one file is required. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 30 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | JSON array of HTTPS file URLs or multipart `files[]` uploads. |
| `provider` | string | No | Conversion Engine (automatic selection for optimal quality) (allowed: auto) (default: "auto") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `file` | string | No | Multipart file upload (primary input). |
| `file_1` | string | No | Multipart file upload field `file_1`. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to Excel

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_excel`

#### Overview

Convert a PDF spreadsheet or table layout into an Excel workbook. Pipeline: `pdfstudio___pdf_to_excel`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 30 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to JPG

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_jpg`

#### Overview

Rasterize PDF pages to JPG images. Pipeline: `pdfstudio___pdf_to_jpg`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | integer | No | Quality (Integer) (default: 70) |
| `max_size` | integer | No | Max size (Integer) (default: 1200) |
| `dpi` | integer | No | Resolution in DPI (default: 150) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to PDF/A

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_pdfa`

#### Overview

Convert a PDF to PDF/A for long-term archival compliance. Pipeline: `pdfstudio___pdf_to_pdfa`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `level` | string | No | PDF/A conformance level: pdfa-1b, pdfa-2b (default), or pdfa-3b. (allowed: pdfa-1b, pdfa-2b, pdfa-3b) (default: "pdfa-2b") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to PowerPoint

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_powerpoint`

#### Overview

Convert a PDF presentation into an editable PowerPoint file. Pipeline: `pdfstudio___pdf_to_powerpoint`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 30 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to WebP

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_webp`

#### Overview

Rasterize PDF pages to WebP images. Pipeline: `pdfstudio___pdf_to_webp`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `quality` | integer | No | Quality (Integer) (default: 70) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert PDF to Word

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___pdf_to_word`

#### Overview

Convert a PDF to an editable Word document while preserving layout where possible. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Convert URL to PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___url_to_pdf`

#### Overview

Render a public HTTPS page to PDF. Pipeline: `pdfstudio___url_to_pdf` — set `url` (e.g. `https://paperoffice.ai`). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 30 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | Yes | Public http(s) URL to render. Private, loopback, and metadata IPs are blocked server-side. |
| `screen_width` | integer | No | Browser viewport width in pixels (default: 1920) |
| `screen_height` | integer | No | Browser viewport height in pixels (default: 1080) |
| `page_size` | string | No | PDF page size (allowed: A4, A3, A5, Letter, Legal, Tabloid) (default: "A4") |
| `page_orientation` | string | No | Page orientation: portrait or landscape. (allowed: portrait, landscape) (default: "portrait") |
| `page_margins` | integer | No | Page margins in pixels (default: 20) |
| `scale` | string | No | Scale factor 0.1-2.0 (default: "1") |
| `print_background` | string | No | Print background colors/images (true/false) (allowed: true, false) (default: "true") |
| `page_ranges` | string | No | Pages to print, e.g. 1-5,8 |
| `header_template` | string | No | HTML header template |
| `footer_template` | string | No | HTML footer template |
| `remove_classes` | string | No | CSS selectors to remove |
| `cookies` | string | No | Advanced: JSON array of cookies for authenticated pages. |
| `extra_headers` | string | No | Advanced: JSON object of extra HTTP request headers. |
| `user_agent` | string | No | Custom User-Agent |
| `wait_until` | string | No | Navigation completion event (allowed: load, domcontentloaded, networkidle0, networkidle2) (default: "networkidle0") |
| `timeout` | integer | No | Navigation timeout in ms (default: 60000) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Edit PDF metadata

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___edit_metadata_pdf`

#### Overview
Edit or read PDF metadata via pipeline `pdfstudio___edit_metadata_pdf`.

When `operation` is `edit` (default), **`metadata`** object is required (at least `title` recommended). Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF file URL(s) or paths. |
| `operation` | string | No | read returns metadata; edit updates XMP/custom fields. (allowed: read, edit) (default: "edit") |
| `metadata` | object | No | Required when operation=edit (title, author, subject, keywords). |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. (default: 50) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Merge pdf

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___merge_pdf`

#### Overview

Merge multiple PDF files into a single document. Order is determined by input file sequence. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofids` | array | One of (`file_urls`, `pofids`) | Array of PaperOffice Document IDs (pofids) to merge in order. Min 2, max 50. |
| `file_urls` | array | One of (`file_urls`, `pofids`) | Alternative: public URLs of PDFs to download and merge. |
| `pofid` | string | No | Single PaperOffice Document ID (rarely useful alone — merge expects 2+). |
| `order` | array | No | Optional explicit merge order as 0-based indices into pofids/file_urls. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `output_filename` | string | No | Name of the merged output file (default: "merged.pdf") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

#### Required alternatives

Provide **at least one** of: `file_urls` **or** `pofids`.

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `pofids[]=value1&pofids[]=value2`, `file_urls[]=value1&file_urls[]=value2`, `order[]=value1&order[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Remove password from PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___unlock_with_password_pdf`

#### Overview
Remove known password protection from a PDF (alias of unlock-with-password). Pipeline: `pdfstudio___unlock_with_password_pdf` — same job as po_pdfstudio_unlock_with_password.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pofid` | string | Yes | PaperOffice File ID to decrypt the PDFs |
| `password` | string | Yes | Current PDF password (required to remove protection). |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Remove restrictions

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___remove_restrictions_pdf`

#### Overview
Remove printing and editing restrictions from a password-protected PDF.

Upload the PDF as multipart `file_1`. Optional `password` when the file is encrypted.

Returns an unlocked PDF via the standard job runtime — poll `GET /job/get/{job_id}` when HTTP 202. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_1` | string | Yes | Multipart file upload (PDF or image). At least one document input is required. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Rotate pdf

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___rotate_pdf`

#### Overview

Rotate PDF pages by 90°, 180°, or 270°. Pipeline: `pdfstudio___rotate_pdf`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `angle` | string | No | Rotation angle in degrees (clockwise): 90, 180, or 270 (allowed: 90, 180, 270) (default: "90") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `page_range` | string | No | Pages to rotate: "all" (default) or specific pages like "1-5,7,9-10" (default: "all") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Split PDF

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___split_pdf`

#### Overview

Split a PDF into separate files by page ranges or bookmarks. Pipeline: `pdfstudio___split_pdf`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF file to split |
| `mode` | string | No | Split mode: burst = every page becomes a separate PDF (default), ranges = custom page ranges via splits parameter (allowed: burst, ranges) (default: "burst") |
| `splits` | array | No | For ranges mode: Array of split definitions. Each item has pages (e.g. 1-5,7) and optional filename. |
| `output_prefix` | string | No | Prefix for burst mode output filenames (default: page_) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Split PDF via AI

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview

Split a PDF into logical segments using AI layout analysis. Returns separate documents or page ranges. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | PDF file to analyze and split |
| `template` | string | No | Workflow template (required discriminator for this tool). (default: "pdf_ai_split") |
| `naming_instruction` | string | No | Naming pattern for output files optional (default: "documenttyp_Datum_Absender") |
| `locale` | string | No | Locale for ALL output: 'de_DE', 'en_US', 'fr_FR' - affects document_type, reasoning, filenames (default: "de_DE") |
| `document_types` | string | No | Allowed types, comma-separated: 'invoice,Schreiben,quote' optional (default: "") |
| `date_format` | string | No | Date format: 'YYYY-MM-DD', 'DD.MM.YYYY', 'MM/DD/YYYY' optional (default: "DD.MM.YYYY") |
| `include_document_type` | string | No | Include document_type in response default: false (default: "false") |
| `include_date` | string | No | Include date in response default: false (default: "false") |
| `include_sender` | string | No | Include sender in response default: false (default: "false") |
| `include_reasoning` | string | No | Include reasoning in response default: false (default: "false") |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Unlock PDF with password

`POST https://api.paperoffice.ai/latest/job/add/pdfstudio___unlock_with_password_pdf`

#### Overview

Unlock an encrypted PDF when the password is supplied. Primary pipeline: `pdfstudio___unlock_with_password_pdf`. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | PDF files |
| `password` | string | Yes | Current PDF password required to unlock the file. |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

---

## Document AI — Storage Mounts

### Add Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/add`

#### Overview

Add an external storage mount (SFTP example). Required: `name`, `host`, `username`, and credentials (`password` or `ssh_key`). BYOS mounts also require `encryption_key`.

**API reference:** `po-storage-mounts-add` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Display name for the mount. |
| `host` | string | Yes | Remote host (SFTP/FTP). |
| `connector_type` | string | No | Storage connector type. (allowed: sftp, s3, azure_blob, webdav, google_drive, onedrive, dropbox, box, imap) (default: "sftp") |
| `mount_purpose` | string | Yes | Mount purpose: 'byos' (Bring Your Own Storage) or 'connector' (data source). Immutable after creation. (allowed: byos, connector) |
| `description` | string | No | Optional description of the mount. |
| `port` | integer | No | Port (default 22 for SFTP). |
| `username` | string | Yes | Login username. |
| `password` | string | No | Password for SFTP/FTP login (or use `ssh_key` for key-based auth). |
| `ssh_key` | string | No | SSH private key (stored encrypted). |
| `api_token` | string | No | API token (stored encrypted). |
| `base_path` | string | No | Base path on the remote server. Parent-directory segments (..) are not allowed. (default: "/") |
| `encryption_key` | string | No | BYOS encryption key when required by plan. |
| `connection_options` | object | No | Additional connection options as JSON (e.g. S3 region, IMAP folder). |
| `icon_url` | string | No | Optional URL for a custom icon. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `mount_id`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Browse storage mount files

`GET https://api.paperoffice.ai/latest/storage_mounts/browse`

#### Overview

Browse files and directories on a storage mount. Returns file listing with metadata (size, modified date, type).

**API reference:** `po-storage-mounts-browse` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | ID of the storage mount to browse |
| `path` | string | No | Path to browse. Relative paths are resolved against mount base_path. Use / for root. |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create storage mount directory

`POST https://api.paperoffice.ai/latest/storage_mounts/mkdir`

#### Overview
Create a folder on a configured storage mount (SFTP/FTP).

## Required JSON body

| Field | Required | Description |
|-------|----------|-------------|
| `mount_id` | Yes | Mount ID from `GET /storage_mounts/list` |
| `folder_name` | Yes | New folder name (not the full path) |
| `path` | No | Parent directory on the mount (defaults to mount base path) |

Connection failures to the remote host return HTTP **422** with `MOUNT_UNREACHABLE`, not HTTP 500.

**API reference:** `po-storage-mounts-mkdir` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | ID of the storage mount |
| `folder_name` | string | Yes | Name of the new folder (no special characters) |
| `path` | string | No | Parent path where the folder will be created (relative to base_path) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-add`

#### Overview
Add a new mirror target for a storage mount. Configure destination, sync interval, and filter rules.

#### Request parameters
**API reference:** `po-storage-mounts-mirrors-create` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `source_mount_id` | integer | Yes | Source mount ID (data origin) |
| `target_mount_id` | integer | Yes | Target mount ID (mirror destination) |
| `sync_mode` | string | No | Synchronization mode (allowed: realtime, scheduled, manual) (default: "realtime") |
| `priority` | integer | No | Legacy queue priority (compat). Prefer processing_lane Start-SLA (no_sla / sla_24h / sla_12h / sla_6h / sla_1h / instant). (default: 0) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/delete`

#### Overview
Delete a storage mount configuration. Fails when active connectors still reference the mount.

#### Request parameters
**API reference:** `po-storage-mounts-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-remove`

#### Overview
Remove a mirror configuration from a storage mount. Stops future syncs but does not delete mirrored data.

#### Request parameters
**API reference:** `po-storage-mounts-mirrors-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mirror_id` | integer | Yes | Mirror ID to remove |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get storage mount details

`GET https://api.paperoffice.ai/latest/storage_mounts/get`

#### Overview
Get full details for one storage mount — connector type, host, base path, health status, and linked connectors.

#### Request parameters
**API reference:** `po-storage-mounts-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get storage mount health status

`GET https://api.paperoffice.ai/latest/storage_mounts/health`

#### Overview
Check health status of all configured storage mounts. Returns availability, latency, and disk usage per mount.

#### Request parameters
**API reference:** `po-storage-mounts-health` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List storage mount mirrors

`GET https://api.paperoffice.ai/latest/storage_mounts/mirrors-list`

#### Overview
List all configured mirror targets for storage mounts. Shows mirror destinations, sync status, and last sync time.

#### Request parameters
**API reference:** `po-storage-mounts-mirrors-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | Yes | Source mount ID to list mirrors for |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List storage mounts

`GET https://api.paperoffice.ai/latest/storage_mounts/list`

#### Overview

List configured storage mounts for the account with connection status and mount purpose.

**API reference:** `po-storage-mounts-list` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Test storage mount connection

`POST https://api.paperoffice.ai/latest/storage_mounts/test`

#### Overview

Test whether a saved storage mount is reachable, or validate connector credentials before saving.

**Dry-run credentials:** Pass `connector_type`, `host`, `port`, `username`, and `password` in the JSON body to test a connection without persisting a mount. Use placeholder credentials in shared collections — never store production secrets in Postman.

**Saved mount:** Provide `mount_id` only to test an existing configured mount.

**API reference:** `po-storage-mounts-test` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | string | No | ID of an existing storage mount to test (omit when sending dry-run connector credentials in the body). |
| `connector_type` | string | No | Connector type for dry-run test: `sftp`, `ftp`, `ftps`, `smb`, `webdav`, or `s3`. |
| `host` | string | No | Hostname for dry-run connection test (example: `files.example.com`). |
| `port` | string | No | Port for dry-run connection test (example: `22` for SFTP). |
| `username` | string | No | Username for dry-run connection test. |
| `password` | string | No | Password for dry-run connection test — use a placeholder in shared collections. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Toggle storage mount mirror

`POST https://api.paperoffice.ai/latest/storage_mounts/mirrors-toggle`

#### Overview
Enable or disable a storage mount mirror without deleting the configuration. Useful for temporary maintenance.

#### Request parameters
**API reference:** `po-storage-mounts-mirrors-toggle` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mirror_id` | integer | Yes | Mirror ID to toggle |
| `is_active` | integer | Yes | 1 = active, 0 = paused (allowed: 0, 1) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update Storage Mount

`POST https://api.paperoffice.ai/latest/storage_mounts/update`

#### Overview
Update Storage Mount Modify an existing storage mount. Required: mount_id Optional: Any field to update

#### Request parameters
**API reference:** `po-storage-mounts-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `mount_id` | integer | No | Parameter: mount_id |
| `name` | string | No | Parameter: name |
| `is_active` | boolean | No | Parameter: is_active |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — Tasks & Substitutes

### Claim task

`POST https://api.paperoffice.ai/latest/workflow_tasks/claim`

#### Overview

Claim an open workflow task for the authenticated user.

**API reference:** `po-tasks-claim-task` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Complete task

`POST https://api.paperoffice.ai/latest/workflow_tasks/complete`

#### Overview

Mark a task as completed

**API reference:** `po-tasks-complete-task` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Escalate workflow task

`POST https://api.paperoffice.ai/latest/workflow_tasks/escalate`

#### Overview

Escalates a workflow task.

**API reference:** `po-tasks-escalate-task` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Workflow task UUID to escalate. |
| `reason` | string | No | Human-readable escalation reason for the audit trail. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get task details

`POST https://api.paperoffice.ai/latest/workflow_tasks/get`

#### Overview

Return full details for a single workflow task by ID.

**API reference:** `po-tasks-get-task-details` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List my tasks

`GET https://api.paperoffice.ai/latest/workflow_tasks/my`

#### Overview

Lists tasks assigned to the current user. Filter by status, priority (low|normal|high|urgent), and step type.

**API reference:** `po-tasks-list-my-tasks` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter by status. Omit for open tasks (pending, in_progress, awaiting_reviews). Use all for every status. (allowed: pending, in_progress, awaiting_reviews, completed, rejected, expired, escalated, all) |
| `priority` | string | No | Task priority filter: low, normal, high, urgent (HITL/workflow task field — not Start-SLA). Alias: medium → normal. (allowed: low, normal, high, urgent) |
| `step_type` | string | No | Filter by step type (e.g. approval, review, manual_input, hitl_review) |
| `limit` | integer | No | Maximum number of tasks (default: 50) |
| `offset` | integer | No | Pagination offset (default: 0) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Mark Task Read

`POST https://api.paperoffice.ai/latest/workflow_tasks/mark_read`

#### Overview

Mark a task as read

**API reference:** `po-tasks-mark-as-read` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | No | ID of the task (default: "") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Reject workflow task

`POST https://api.paperoffice.ai/latest/workflow_tasks/reject`

#### Overview

Rejects a workflow/approval task.

**API reference:** `po-tasks-reject-task` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Workflow task UUID to reject. |
| `reason` | string | No | Human-readable rejection reason for the audit trail. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Release workflow task claim

`POST https://api.paperoffice.ai/latest/workflow_tasks/release`

#### Overview

Releases a claimed task (inbox).

**API reference:** `po-tasks-release-task` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | Yes | Workflow task UUID to release back to the queue. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Resolve task

`POST https://api.paperoffice.ai/latest/workflow_tasks/resolve`

#### Overview

Resolves a human or HITL task via `/workflow_tasks/resolve`. Requires a decision and one of task_uuid, task_id, or uuid.

**API reference:** `po-tasks-resolve-task` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_uuid` | string | No | Task UUID. Provide one of task_uuid, task_id, or uuid. |
| `task_id` | string or integer | No | Task UUID string or numeric database id. Provide one of task_uuid, task_id, or uuid. |
| `uuid` | string | No | Task UUID alias. Provide one of task_uuid, task_id, or uuid. |
| `decision` | string | Yes | Reviewer decision (required): approve, reject, escalate, or postpone. (allowed: approve, reject, escalate, postpone) |
| `comment` | string | No | Optional comment. |
| `reject_comment` | string | No | Rejection comment (when decision is `reject`). |
| `reject_reason_id` | string | No | Rejection reason ID. |
| `field_results` | object | No | HITL field review map keyed by field id. Each value: { action: accept / correct, value, corrected_value }. |
| `check_results` | object | No | HITL binary check map keyed by check id. Each value: { answer } or a scalar answer. |
| `claim_session_id` | string | No | Claim session ID for parallel review locking. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — User Groups

### Groups: Get Group Details

`POST https://api.paperoffice.ai/latest/user_groups/get`

#### Overview

Get detailed information about a specific group including settings and members.

**API reference:** `po-groups-get` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group_id` | integer | Yes | ID of the group |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Groups: Get Group Members

`POST https://api.paperoffice.ai/latest/user_groups/get_members`

#### Overview

Get all members of a specific group with their profile information.

**API reference:** `po-groups-get-members` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group_id` | integer | Yes | ID of the group |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Groups: Get My Groups

`POST https://api.paperoffice.ai/latest/user_groups/get_user_groups`

#### Overview

Get all groups the currently authenticated user belongs to.

**API reference:** `po-groups-get-user-groups` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Groups: List All Groups

`POST https://api.paperoffice.ai/latest/user_groups/list`

#### Overview

List all user groups in the organization with member count, settings, and metadata.

**API reference:** `po-groups-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — Webhooks

### Create Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/subscribe`

#### Overview

Create a new webhook subscription. Payloads are signed with HMAC-SHA256.

**Common event types:** `document.uploaded`, `document.updated`, `document.deleted`, `document.note_added`, `job.completed`, `job.failed`, or `["*"]` for all events.

`secret` is auto-generated when empty.

**API reference:** `po-webhooks-subscribe` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Display name for the subscription (required). |
| `url` | string | Yes | Webhook target URL (HTTPS recommended). |
| `events` | array | Yes | Array of event types or [*] for all |
| `secret` | string | No | HMAC secret (auto-generated if empty). |
| `filters` | object | No | Optional Filter (e.g. workspace_id, pofid) |
| `headers` | object | No | Additional HTTP headers as key-value pairs |
| `retry_policy` | string | No | Retry policy: none, linear, or exponential (default: exponential). (allowed: none, linear, exponential) |
| `max_retries` | integer | No | Maximum delivery retries after failure (0–10, default 5). (default: 5) |
| `timeout_ms` | integer | No | Timeout in ms (1000-30000, default: 10000) |
| `is_active` | string | No | Set subscription active (true) or inactive (false). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `subscription_id` and one-time `secret`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/delete`

#### Overview

Delete a webhook subscription. The delivery log is preserved.

**API reference:** `po-webhooks-delete` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the subscription to delete |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Webhook Subscriptions

`GET https://api.paperoffice.ai/latest/webhooks/list`

#### Overview

List all webhook subscriptions of the account.

**API reference:** `po-webhooks-list` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Test webhook

`POST https://api.paperoffice.ai/latest/webhooks/test`

#### Overview

Send a test event to a webhook subscription to verify delivery.

**API reference:** `po-webhooks-test` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the Subscription (Required) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update Webhook Subscription

`POST https://api.paperoffice.ai/latest/webhooks/update`

#### Overview
Update an existing webhook subscription (URL, events, headers, retry policy, or active flag).

Requires `subscription_id` from `POST /webhooks/subscribe` or `GET /webhooks/list`.

**API reference:** `po-webhooks-update` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `subscription_id` | integer | Yes | ID of the Subscription (Required) |
| `name` | string | No | New subscription name. |
| `url` | string | No | New webhook URL. |
| `events` | array | No | New event list. |
| `secret` | string | No | New signing secret. |
| `filters` | object | No | new Filter |
| `headers` | object | No | New custom headers. |
| `is_active` | boolean | No | Set subscription active (true) or inactive (false). |
| `retry_policy` | string | No | Retry policy: none, linear, or exponential (default: exponential). (allowed: none, linear, exponential) |
| `max_retries` | integer | No | New maximum retry count. |
| `timeout_ms` | integer | No | New timeout in milliseconds. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Document AI — Workflow Orchestration

### System templates

`GET https://api.paperoffice.ai/latest/workflow/system_list`

#### Overview
List built-in **system** workflow templates (read-only catalog).

or `POST /workflow/system_list` (empty body).

Pair with `GET /workflow/system_get` for a single template. For user-owned templates use `GET /workflow/user_list`.

**API reference:** `po-orchestration-list-system-templates` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Create template

`POST https://api.paperoffice.ai/latest/workflow_templates/add`

#### Overview
Create a custom user workflow template.

Send a JSON body with `name` and `steps` (array of `{id, endpoint, params}`). Legacy `nodes` / `connections` fields are not used by the API runtime.

**API reference:** `po-workflow-templates-create-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Workflow template name. (default: "New workflow") |
| `description` | string | No | Workflow template description. |
| `steps` | array | Yes | Workflow steps (required). Each item: {id, endpoint, params}. |
| `timeout_ms` | integer | No | Execution timeout in milliseconds (default: 300000). |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; key fields: `uuid` workflow template id. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Delete template

`POST https://api.paperoffice.ai/latest/workflow_templates/delete`

#### Overview
Deactivate a user workflow template (soft delete).

Requires `workflow_id` (aliases: `uuid`, `template_id`, `id`). Only user-owned templates can be deleted.

**API reference:** `po-workflow-templates-delete-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No | Workflow template UUID from po_workflow_templates_list_templates (preferred). |
| `template_id` | string | No | Alias for uuid. |
| `workflow_id` | string | No | Legacy alias for template uuid (not system workflow id). Mapped to uuid server-side. |
| `id` | string | No | Alias for uuid. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Execute template

`POST https://api.paperoffice.ai/latest/job/add/workflow`

#### Overview
Execute a saved workflow template.

Provide either a multipart **file** upload or a `pofid` in the body. Set `workflow_id` (alias `uuid`) to the template to run. Supports `client_wait`, `async_only`, and `priority` like other job endpoints. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-workflow-templates-execute-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No | Deprecated alias for workflow_id. |
| `input_data` | object | No | Optional input payload for the workflow run. |
| `file` | string | One of (`file`, `pofid`) | Multipart file upload (Alternative to pofid). |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. (default: 800) |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `workflow_id` | string | No | Workflow template ID to execute (alias: uuid). |
| `pofid` | string | One of (`file`, `pofid`) | Document POFID (Alternative to multipart file upload). |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

#### Required alternatives

Provide **at least one** of: `file` **or** `pofid`.

**Request body:** `multipart/form-data` — upload via field `file` **or** pass `pofid` in the form body. **Exception:** JSON `files` URL arrays are **not** supported on `/job/add/workflow` (unlike most `/job/add/{pipeline}` endpoints). Use multipart `file` or `pofid` only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Get template

`POST https://api.paperoffice.ai/latest/workflow_templates/get`

#### Overview
Load a single system workflow template by ID.

Call `GET /workflow/system_list` first to obtain valid IDs. Pass `workflow_id` (aliases: `uuid`, `template_id`, `id`).

**API reference:** `po-workflow-templates-get-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No | Deprecated alias for workflow_id. |
| `template_id` | string | No | Deprecated alias for workflow_id. |
| `workflow_id` | string | Yes | System workflow ID from GET /workflow/system_list (canonical). |
| `id` | string | No | Deprecated alias for workflow_id. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### List Workflow Templates

`GET https://api.paperoffice.ai/latest/workflow_templates/list`

#### Overview
List user workflow templates (graph + agent templates) for the authenticated account.

Legacy alias: `GET /workflow/user_list` routes to this endpoint.

Returns `data[]` with template UUIDs — use `workflow_id` / `uuid` for update and delete.

**API reference:** `po-workflow-templates-list-templates` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Update template

`POST https://api.paperoffice.ai/latest/workflow_templates/update`

#### Overview
Update an existing user workflow template.

Requires `workflow_id` (aliases: `id`, `uuid`, `template_id`). Partial updates supported for `name`, `description`, and `steps`.

**API reference:** `po-workflow-templates-update-template` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `uuid` | string | No | Workflow template UUID from po_workflow_templates_list_templates (preferred). |
| `template_id` | string | No | Alias for uuid. |
| `workflow_id` | string | No | Legacy alias for template uuid (not system workflow id). Mapped to uuid server-side. |
| `id` | string | No | Alias for uuid. |
| `name` | string | No | New template name |
| `description` | string | No | New template description |
| `category` | string | No | Workflow template category label. |
| `trigger_type` | string | No | Trigger identifier (must start with trigger_, e.g. trigger_manual). |
| `is_active` | boolean | No | When false, template is disabled and cannot be executed. |
| `steps` | array | No | Updated workflow steps ({id, endpoint, params}). |
| `timeout_ms` | integer | No | Execution timeout in milliseconds |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `steps[]=value1&steps[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Documentation & Discovery

### Get MCP server integration info

`GET https://api.paperoffice.ai/latest/docs/markdown`

#### Overview

Returns MCP server integration guidance for AI clients — authentication, profiles, tool discovery, and Document AI patterns.

**Recommended endpoint (DocuWare-style DMS):** `https://mcp.paperoffice.ai/dms` (about 165 tools: CRUD + capture + workflow + signatures + schema). `/claude` is an alias.

**Lighter module:** `/mcp-document-ai` (about 119 tools: read + CRUD + capture + comments/notes).

**Other profiles:** `/mcp-workflow-ai` (workflow), `/mcp-document-workflow-ai` (combined), `/mcp` (37 read-only default), `/mcp-full` (all MCP tools). Legacy: `/mcp-headless`, `/mcp-headless-plus`.

**Auth:** Same Bearer token as REST (`po_sk_`, `po_ut_`). Streamable HTTP MCP (JSON-RPC 2.0).

**Aliases:** `po_documents_update_index` → document-edit; `po_job_get` → job poll; see llms-full.txt MCP section.

**Voice clone (MCP):** `po_tts_voice_clone` — upload sample via `voice_sample_base64`, set `reference_text` (transcript) and `quality` (`premium` or `ultra`). Same REST pipeline as Postman **Clone voice (TTS)**.

**Document anonymization (MCP):** `po_anonymization_pii_detect` (preview) → `po_anonymization_redaction_apply` (`preview_job_id`), or one-shot `po_anonymization_anonymize` (`template=document_anonymize`). Pass `scenario` (default `gdpr_auskunft`). Redact Agent: `po_documents_redact_agent_run`. Apply path: `paperoffice_dataripper___redact_image` (not obsolete `anonymization___request`).

**Usage:** `GET {{base_url}}/docs/markdown` or llms-full.txt — 0 credits with user Bearer or VISITOR tier.

**API reference:** `po-documentation-mcp-server-ai-integration` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** Free (included — documentation export; user Bearer or VISITOR auto-tier, 0 credits)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get Postman collection

`GET https://api.paperoffice.ai/latest/docs/postman`

#### Overview
Returns the live Postman collection JSON. Re-import when the footer release ID changes.

**Usage:** `GET {{base_url}}/docs/postman` — same URL as this documentation item (public import link).

**Note:** No Bearer required. 0 credits (documentation export).

#### Request parameters
**API reference:** `po-documentation-postman-collection` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** Free (included — documentation export; user Bearer or VISITOR auto-tier, 0 credits)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## General

### Parse email files (EML, MSG, PST)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_dataripper___email_parser`

#### Overview

Parse email containers (EML, MSG, PST). **Postman:** use **multipart form-data** and upload via the `files` field (pick `public_assets/demo_email.eml` or your own `.eml`/`.msg`). JSON `files` URL arrays are also supported for automation. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 5 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | string | One of (`file`, `file_1`, `files`) | Email file upload (EML, MSG, or PST). Multipart field `files`. |
| `extract_attachments` | boolean | No | Extract file attachments from the email into separate outputs (default: true) |
| `parse_headers` | boolean | No | Parse email headers (From, To, Subject, Date, Message-ID) (default: true) |
| `decode_html` | boolean | No | Decode HTML body content to plain text where applicable (default: true) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `file` | string | One of (`file`, `file_1`, `files`) | Multipart file upload (primary input). |
| `file_1` | string | One of (`file`, `file_1`, `files`) | Multipart file upload field `file_1`. |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

#### Required alternatives

Provide **at least one** of: `file` **or** `file_1` **or** `files`.

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Redact image regions

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_dataripper___redact_image`

#### Overview

Redact image regions (canonical Step-2 anonymize apply). Submit multipart file(s) or JSON files with HTTPS URLs plus bounding_boxes and redact_boxes from document_anonymize_preview. Same pipeline as po_anonymization_apply_redaction and MCP po_anonymization_redaction_apply. Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Cost:** 20 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `files` | array | Yes | Image files to redact (PNG, JPG, WEBP) |
| `bounding_boxes` | array | Yes | OCR bounding boxes per page (from a prior OCR pass) |
| `redact_boxes` | array | Yes | List the box-IDs to be blacked out |
| `override_boxes` | array | No | Optional manual box IDs to override auto-detected redaction regions (default: []) |
| `priority` | integer | No | LEGACY queue weight (numeric). Prefer processing_lane (Start-SLA). If processing_lane is set, the lane wins. Do not use as the public SLA product. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force async: same as client_wait=false. Returns job_id immediately; poll GET /job/get/{job_id}. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.
**Array fields (multipart):** repeat the field name with `[]` — e.g. `files[]=value1&files[]=value2`, `bounding_boxes[]=value1&bounding_boxes[]=value2`, `redact_boxes[]=value1&redact_boxes[]=value2`, `override_boxes[]=value1&override_boxes[]=value2`. JSON bodies with array properties are rejected on these endpoints.
#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

---

## Media AI — Image Studio

### Generate image

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___generate`

#### Overview
Generate images from a text **prompt** using PaperOffice **Image Studio**.

Use this endpoint for **text-to-image** jobs. Set `model` to control the maximum resolution tier; use `output` to choose how the result is returned.

**Pipeline:** `paperoffice_imagestudio___generate`

## Model tiers (size limits)

All tiers share the same Image Studio capability; limits are **maximum width/height** (snapped to a **16 px grid**, minimum 512 px per side):

| `model` | Max size | Typical use |
|---------|----------|-------------|
| `basic` | 512×512 | Icons, thumbnails, fast drafts |
| `premium` | 1280×1280 | Web graphics, presentations (default) |
| `ultra` | 2048×2048 | Print-ready, large hero images |

Oversized `width`/`height` values are clamped to the selected tier.

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `prompt` | yes | — | Text description of the image to generate. |
| `model` | no | `premium` | `basic`, `premium`, or `ultra` (see table above). |
| `width` | no | tier default | Pixels (128–2048), snapped to 16 px grid. |
| `height` | no | tier default | Same as `width`. |
| `output` | no | `inline` | `inline` (raw image bytes in HTTP body), `base64` (embedded in JSON), `url` (download link in JSON). |
| `precompile_prompt` | no | `true` | `true` = AI prompt optimizer; `false` = use your exact wording (recommended with fixed `seed`). |
| `num_images` | no | `1` | Generate 1–8 images in one job (each image is a separate unit in the result). |
| `negative_prompt` | no | — | Elements to avoid (e.g. `blurry, watermark, text`). |
| `seed` | no | random | Fixed integer ≥ 0 for reproducibility; use with `precompile_prompt=false`. |
| `priority` | no | plan default | Leave **unchecked** in Postman. |

## Prompt context (optional)

When `precompile_prompt=true` (default), Image Studio may enrich the scene using location and weather context:

| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `inject_weather` | no | `true` | `true` = include local weather in the optimized prompt; `false` = omit weather hints. |
| `force_location` | no | — | City/region name **or** IP address. Overrides automatic geo detection from the request. If omitted, the caller IP is used when available. |

**Automatic (not a Postman field):** Client IP is taken from the HTTP request when `force_location` is empty — no need to send `user_ip` manually.

**Fixed inference profile:** quality settings are fixed per model tier and are not customer-configurable via the API.

#### Connection hold
& polling (about 5 minute limit)

- **Default:** This HTTP request is held up to **about 5 minutes (about 295 s)**; then **200** or **202** + `poll_url`.
- **Poll:** `GET /job/get/{job_id}` every 5–10 s after **202** until `job_status` is `completed` or `failed`.
- **Immediate job id:** Send `client_wait=false` or `async_only=true` in the JSON request body to receive `job_id` immediately, then poll **`GET /job/get/{job_id}`**.

## Start-SLA / processing_lane
(optional)

- **Omitted** → workspace `default_processing_lane` (else fair-use `no_sla`).
- Lanes: `no_sla` | `sla_24h` | `sla_12h` | `sla_6h` | `sla_1h` | `instant` (job price ×1 … ×5).
- **`instant`** → interactive / sync-capable start.
- Legacy `priority` is compat only; **`processing_lane` wins** when both are sent.

## Related endpoint

| Use case | Postman item |
|----------|----------------|
| Remove background from an existing image | Remove background | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate (required). Default demo: photorealistic portrait with legible "Tokyo" sign — pair with force_location=Tokyo. (default: "{see_params_tab}") |
| `model` | string | No | Resolution tier: basic (max 512×512), premium (max 1280×1280), ultra (max 2048×2048). Default: premium. (allowed: basic, premium, ultra) (default: "premium") |
| `width` | integer | No | Width in pixels (snapped to 16 px grid, clamped to model tier). Optional. (default: 896) |
| `height` | integer | No | Height in pixels (snapped to 16 px grid, clamped to model tier). Optional. (default: 1152) |
| `output` | string | No | Delivery mode: `inline` (binary HTTP body), `base64`, or `url`. When `output` is `inline` or `base64`, set `client_wait=true` (default) — otherwise HTTP 400 `CLIENT_WAIT_REQUIRED`. (allowed: inline, base64, url) (default: "inline") |
| `precompile_prompt` | string | No | true = AI prompt optimizer (default). false = use exact prompt (pair with fixed seed for reproducibility). (allowed: true, false) (default: "true") |
| `inject_weather` | string | No | true = include local weather in prompt optimizer (default). false = omit weather context. (allowed: true, false) (default: "true") |
| `force_location` | string | No | Optional. City/region name or IP. Default demo: Tokyo (pairs with the sign text in the default prompt). (default: "Tokyo") |
| `num_images` | integer | No | Number of images to generate in one job (1–8). Each image is processed as a separate unit in the job result. (default: 1) |
| `negative_prompt` | string | No | Optional. Elements to exclude (e.g. blurry, misspelled letters, distorted typography). (default: "blurry, low quality, watermark, misspelled letters, distorted typography") |
| `seed` | integer | No | Optional. Fixed seed ≥ 0 for reproducibility; omit or -1 for random. Use with precompile_prompt=false. (default: -1) |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Remove background

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_imagestudio___remove_bg`

#### Overview
Remove the background from an uploaded image using PaperOffice **Image Studio** (AI segmentation).

Returns a transparent or clean foreground subject. Use when you already have an image file and need a cut-out for compositing or product shots.

**Pipeline:** `paperoffice_imagestudio___remove_bg`

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `file` | yes | — | Image upload: JPEG, PNG, WebP, GIF, BMP (multipart). |
| `output_format` | no | `webp` | `webp` (smaller) or `png` (lossless transparency). |
| `output` | no | `inline` | `inline` (raw image in HTTP body), `base64`, or `url` (download link in JSON). |
| `segmentation_profile` | no | `standard` | Optional segmentation quality profile: `standard`, `portrait`, or `general`. Invalid values fall back to default. |
| `priority` | no | plan default | Leave **unchecked** in Postman. |

#### Connection hold
& polling

Same as other job endpoints: when **`client_wait` is omitted** (recommended) or `client_wait=true`, the API keeps the HTTP connection open up to **about 295 s** and returns the finished image (or **202** with `poll_url` if processing takes longer). Set `client_wait=false` or `async_only=true` for immediate `job_id` + polling only.

## Start-SLA / processing_lane
(optional)

Prefer `processing_lane=instant` for sync-capable start. Legacy `priority` is compat only.

## Related endpoint

| Use case | Postman item |
|----------|----------------|
| Generate new images from text | Generate image | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file` | string | Yes | Image file to process (required). JPEG, PNG, WebP, GIF, BMP. |
| `output_format` | string | No | Output format: webp (default, smaller) or png (lossless transparency). (allowed: webp, png) (default: "webp") |
| `output` | string | No | Delivery mode: `inline` (binary HTTP body), `base64`, or `url`. When `output` is `inline` or `base64`, set `client_wait=true` (default) — otherwise HTTP 400 `CLIENT_WAIT_REQUIRED`. (allowed: inline, base64, url) (default: "inline") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

---

## Media AI — Translation

### Get supported languages

`GET https://api.paperoffice.ai/latest/translate/languages`

#### Overview
Return the **PaperOffice Translation language catalog**: all **35** supported language codes with display names, flags, and tier metadata.

Use this endpoint **before** `POST /translate/text` to validate `source_language` and `target_language`. This is a **direct REST call** (not a job) — the response is JSON immediately.

**Billing:** **1 credit per API request** (external authenticated call). **Free in the PaperOffice app** (browser session / `credits_ui` subsidy — same pattern as the TTS voice catalog).

#### Request parameters
No parameters required. Optional filters may be added in future API versions — today the full catalog is always returned.

## Regional variants (`data.target_locale`)

Optional **locale variants** refine output (spelling, vocabulary, register) via LLM prompt hints only — **billing stays on the 2-letter `target_language`**.

| Field | Description |
|-------|-------------|
| `data.target_locale.bases` | Language codes that offer variants (e.g. `de`, `en`, `es`, `fr`, `pt`, `nl`, `it`, `zh`, `ar`) |
| `data.target_locale.variants` | Map: base code → list of `{ code, label, instruction }` — first entry is **Standard** (`code` = `""`) |

**Examples:** `de-DE`, `de-AT`, `de-CH` (German); `en-US`, `en-GB`, `en-AU`, `en-CA`; `es-ES`, `es-419`, `es-MX`; `fr-FR`, `fr-CA`, `fr-BE`, `fr-CH`; `pt-BR`, `pt-PT`; `nl-NL`, `nl-BE`; `it-IT`, `it-CH`; `zh-Hans`, `zh-Hant`; `ar-SA`, `ar-EG`, `ar-AE`, `ar-MA`.

Pass the chosen variant code as **`target_locale`** on **`POST /translate/text`** (must match `target_language` base).

## Using the catalog for translation

1. Call **`GET /translate/languages`** once per session or cache client-side.
2. Pick valid ISO-style codes from `data.languages` for **`POST /translate/text`**.
3. When needed, pick a regional variant from `data.target_locale.variants[target_language]` and send it as **`target_locale`**.
4. Choose `tier` (`basic`, `premium`, `ultra`) — quality/speed trade-off; omit only when the plan default is intended.

**API reference:** `po-translate-get-languages` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Translate text

`POST https://api.paperoffice.ai/latest/translate/text`

#### Overview
Translate text with PaperOffice **Translation** — one endpoint for **string**, **string array**, and **JSON object** payloads.

Supports **35** languages, optional **preserve_terms** for brand/product names, and **hybrid client-wait** (inline result, **HTTP 202** + poll, or immediate `job_id`).

with **`Content-Type: application/json`**.

**Billing:** Per character volume and `tier` — see the account **Pricing Calculator** (not duplicated here).

## Input types (`text` field)

| `text` shape | Behavior | Response field |
|--------------|----------|----------------|
| **string** | Single passage | `translation` (string) |
| **string[]** | Batch of strings (max 500 items) | `translations` (array) |
| **object** | JSON structure (keys/values localized) | `translated_json` (object) |

Send the shape as native JSON (not a stringified JSON blob inside a string).

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `text` | **yes** | `Guten Morgen — PaperOffice Translation API showroom.` | string, string[], or JSON object |
| `target_language` | **yes** | `en` | Target code from **Get supported languages** |
| `target_locale` | no | — | Regional variant (e.g. `de-AT`, `en-GB`) from catalog `data.target_locale.variants`; prompt hint only |
| `source_language` | no | `auto` | Source code or `auto` for detection |
| `tier` | no | `premium` | `basic`, `premium`, or `ultra` |
| `tone` | no | `neutral` | `formal`, `informal`, or `neutral` (register hint) |
| `style` | no | `general` | `legal`, `medical`, `marketing`, or `general` (domain hint) |
| `preserve_terms` | no | — | Up to 50 terms kept verbatim (brand/plan names) |
| `preserve_terms_preset` | no | — | Opt-in server preset, e.g. `paperoffice_brand` |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | no | `false` | Force immediate `job_id`; optional JSON body field (omitted from Postman form) |
| `priority` | no | plan default | 1–900; **≥900** sync path; optional JSON body field (omitted from Postman form) |

#### Connection hold
& polling (about 5 minute limit)

- **Default:** This HTTP request is held up to **about 5 minutes (about 295 s)**; then **200** with translation or **202** + `poll_url`.
- **Poll:** `GET /job/get/{job_id}` every 5–10 s after **202** until `job_status` is `completed` or `failed`.
- **Immediate job id:** Send `client_wait=false` or `async_only=true` in the JSON request body to receive `job_id` immediately, then poll **`GET /job/get/{job_id}`**.

## Start-SLA / processing_lane
(optional)

- **Omitted** → workspace `default_processing_lane` (else fair-use `no_sla`).
- Lanes: `no_sla` | `sla_24h` | `sla_12h` | `sla_6h` | `sla_1h` | `instant` (job price ×1 … ×5).
- **`instant`** → interactive / sync-capable start.
- Legacy `priority` is compat only; **`processing_lane` wins** when both are sent.

## Related endpoint

| Use case | Postman item |
|----------|----------------|
| List valid language codes (35) | Get supported languages |

**API reference:** `po-translate-text` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to translate: send as JSON string, string[], or object in the raw body (see Input types in docs). (default: "Guten Morgen — PaperOffice Translation API showroom.") |
| `source_language` | string | No | Source language code or auto for detection. (default: "de") |
| `target_language` | string | Yes | Target language code (required). Must be one of the 35 supported codes. (default: "en") |
| `target_locale` | string | No | Optional regional variant (e.g. de-AT, en-GB). From GET /translate/languages → data.target_locale.variants. Prompt hint only. (default: "") |
| `tier` | string | No | Quality tier: basic (fast), premium (balanced), ultra (best). (allowed: basic, premium, ultra) (default: "premium") |
| `preserve_terms` | array | No | Optional terms kept verbatim (brand, plan, product names). Max 50 entries. |
| `preserve_terms_preset` | string | No | Optional server preset merged with preserve_terms, e.g. paperoffice_brand. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Force immediate job_id (same as client_wait=false). optional JSON body field. |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while translation runs, up to the **dynamic pipeline timeout** (minimum about 20s, infrastructure cap about 295s). On success you receive the translation inline; on timeout → **HTTP 202** with `job_id`, `poll_url`, and `client_wait: false`.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` quickly (about 100ms), then poll **`GET /job/get/{job_id}`** every 5–10 seconds until `job_status` is `completed` or `failed`.
- **Sync translation path:** `processing_lane=instant` (or legacy `priority` ≥ 900) requests synchronous completion inside the hold window when capacity allows.

**Response field:** `client_wait` (boolean) indicates whether this response used connection hold.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start billing — see **Start-SLA / processing_lane** below and the collection guide **Start-SLA (`processing_lane`) — wait-to-start**.

---

## Media AI — Voice

### Transcribe audio

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___stt`

#### Overview
Transcribe uploaded **audio** to text (Speech-to-Text) via `paperoffice_voice___stt`.

Supports plain JSON transcripts plus subtitle/diarization formats on higher tiers. This is a **job** endpoint (async-capable with connection hold), not an instant REST call.

**Pipeline:** `paperoffice_voice___stt`.

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `audio_file` | yes | — | Multipart audio upload. Common formats: MP3, WAV, M4A, FLAC, OGG, WebM, AAC. |
| `quality` | no | `basic` | `basic` (plain transcript), `premium` (timestamps, SRT/VTT), `ultra` (speaker diarization, RTTM). |
| `output_format` | no | `json` | `json`, `srt`, `vtt`, `rttm` — tier restrictions apply (see table below). |
| `language` | no | *(auto)* | **Optional.** ISO code (`de`, `en`, …) or **omit** — the engine auto-detects the spoken language. |
| `priority` | no | plan default | Leave **unchecked** in Postman. |

### Quality vs output_format

| output_format | basic | premium | ultra |
|---------------|-------|---------|-------|
| `json` | yes | yes | yes |
| `srt`, `vtt` | no | yes | yes |
| `rttm` (diarization) | no | no | yes |

#### Connection hold
& polling (about 5 minute limit)

Same hybrid model as TTS jobs: default wait on this request up to about 295s, then poll `GET /job/get/{job_id}` for long files.

## Start-SLA / processing_lane
(optional)

Omit `processing_lane` → workspace default / fair-use `no_sla`. Lanes: no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant.

## Related endpoints

| Use case | Postman item |
|----------|----------------|
| Text-to-speech | Generate speech / Clone / Multi-speaker |
| Voice names for TTS | List available TTS voices | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `audio_file` | string | Yes | Audio file upload (required). MP3, WAV, M4A, FLAC, OGG, WebM, AAC. |
| `quality` | string | No | Tier: basic (JSON transcript), premium (timestamps, SRT/VTT), ultra (speaker diarization, RTTM). (allowed: basic, premium, ultra) (default: "basic") |
| `output_format` | string | No | json (all tiers), srt/vtt (premium+), rttm (ultra only). Default: json. (allowed: json, srt, vtt, rttm) (default: "json") |
| `language` | string | No | Optional ISO language (de, en, …). Omit for auto-detection. |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Clone voice (TTS)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

#### Overview
Clone a **custom voice** from a short audio sample and speak new text with PaperOffice neural TTS.

Use this endpoint when you need a voice that is **not** in the catalog (`POST /voice/voices`). Upload `voice_sample` instead of setting `voice`.

**Pipeline:** `paperoffice_voice___tts` (same URL as catalog TTS — body differs).

**Tier requirement:** `quality` must be **`premium`** or **`ultra`**. `basic` is rejected for voice cloning.

## Prerequisites
1. Prepare a **clean voice sample**: **minimum 10 seconds**, recommended **15–30 seconds** of continuous single-speaker speech (max 10 MB).
2. Do **not** set catalog `voice` — clone mode is triggered by `voice_sample`.
3. Optional: `language` (`en`, `de`, …) or `auto` — omit or use `auto` for detection from the sample.
4. **Strongly recommended:** `reference_text` — transcript of what is spoken in `voice_sample` (improves clone quality).

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `text` | yes | — | Up to 50,000 characters. Emotion markers: `[chuckle]`, `[laugh]`, `[sigh]`, `[whisper]`, `[happy]`, `[excited]`. |
| `voice_sample` | yes | — | Multipart audio (min. **10 s**, recommended 15–30 s). WAV, MP3, OGG, FLAC, M4A, WebM, AAC. |
| `reference_text` | no | — | Transcript of `voice_sample` (max 2,000 chars). **Strongly recommended.** Alias: `voice_sample_text`. |
| `quality` | no | `premium` | **`premium`** or **`ultra` only**. |
| `output_format` | no | `mp3` | `mp3`, `wav`, `ogg`. |
| `output` | no | `inline` | `inline` (audio in HTTP body), `base64`, or `url`. |
| `language` | no | `auto` | Optional. Omit or `auto` to detect from the **text to speak**; or set `en`, `de`, etc. for explicit output language. |
| `priority` | no | plan default | Leave **unchecked** in Postman. |

#### Connection hold
& polling (about 5 minute limit)

- Default: wait on this request up to **about 295 seconds**, then result or **HTTP 202**.
- Poll `GET /job/get/{job_id}` after **202** until `job_status` is `completed` or `failed`.

## Start-SLA / processing_lane
(optional)

Omit `processing_lane` → workspace default / fair-use `no_sla`. Lanes: no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant.

## Related endpoints

| Use case | Postman item |
|----------|----------------|
| Catalog voice | List available TTS voices → Generate speech (single voice) |
| Multi-speaker | Generate multi-speaker TTS | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to speak (max 50,000 characters). Inline emotion markers: [chuckle] [laugh] [sigh] [breath] [whisper] [happy] [excited]. Default demo after voice_sample upload. (default: "[happy] This is your cloned voice on PaperOffice neural TTS. [breath] Support ticket TCK-88421 is now marked resolved. [excited] Record one clean sample, then narrate any new script with emotions like [sigh] or [whisper] — no extra studio session required.") |
| `voice_sample` | string | Yes | Voice sample audio file (required). Minimum 10 seconds, recommended 15–30 s, clean single-speaker speech, max 10 MB. WAV, MP3, OGG, FLAC, M4A, WebM, AAC. |
| `reference_text` | string | No | Transcript of the spoken content in voice_sample (strongly recommended for clone quality). Max 2,000 characters. Alias: voice_sample_text. (default: "Welcome to PaperOffice. This is the spoken content of my voice sample for cloning.") |
| `quality` | string | No | Quality tier: premium (balanced) or ultra (best). Basic is NOT supported for cloning. (allowed: premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3, wav, ogg. Default: mp3. (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response: inline (audio stream in HTTP body, default), base64 (JSON), or url (download link in JSON). (allowed: inline, base64, url) (default: "inline") |
| `language` | string | No | Language of the output text (optional). Omit or use auto to detect from the text to speak — not from the voice sample. (default: "auto") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Generate multi-speaker TTS (inline tags)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

#### Overview
Generate speech with **multiple catalog speakers** in one job using inline **speaker tags** (PaperOffice neural TTS).

Set `voice=Multi` and mark who speaks which line. Speaker names must exist in `POST /voice/voices` (same language buckets as in the tags).

**Pipeline:** `paperoffice_voice___tts` (same URL as single-voice TTS).

## Prerequisites
1. Call **`POST /voice/voices`** and note exact `name` values (e.g. `Abigail`, `James`).
2. Tag **every** spoken segment — untagged text fails validation in multi mode.
3. Set top-level `language` (e.g. `en`) — **required** by the API (validates the job bucket) even when tags include per-line language hints.

## Speaker tag syntax (three forms)

| Style | Example |
|-------|---------|
| Legacy XML | `<Abigail>Hello</Abigail><James>Hi there</James>` |
| Shorthand | `[en\\\|Abigail] Hello [en\\\|James] Hi there` |
| Key-Value | `[voice:Abigail lang:en] Hello [voice:James lang:en] Hi` |

Emotion markers (`[chuckle]`, `[laugh]`, …) work inside segment text and are passed through to synthesis.

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `text` | yes | — | Full script with speaker tags on every segment. Max 50,000 characters per job. |
| `voice` | yes | `Multi` | Must be `Multi` (case-insensitive). |
| `language` | yes | `en` | Top-level language code (e.g. `en`, `de`). |
| `quality` | no | `premium` | `basic`, `premium`, `ultra`. |
| `output_format` | no | `mp3` | `mp3`, `wav`, `ogg`. |
| `output` | no | `inline` | `inline` (default), `base64`, `url`. |
| `priority` | no | plan default | Leave **unchecked** in Postman. |

#### Connection hold
& polling (about 5 minute limit)

Identical to **Generate speech (single voice)**: default connection hold about 295s, then **HTTP 202** + `GET /job/get/{job_id}`.

## Start-SLA / processing_lane
(optional)

Omit `processing_lane` → workspace default / fair-use `no_sla`. Lanes: no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant.

## Related endpoints

| Use case | Postman item |
|----------|----------------|
| One speaker | Generate speech (single voice) |
| Custom voice from audio | Clone voice (TTS) |
| Voice catalog | List available TTS voices | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Script with speaker tags on every segment (max 50,000 characters). Examples: [en / Abigail] Hello [en / James] Hi. Default demo: support dialog with emotions. (default: "[en|Abigail][happy] Welcome to PaperOffice Voice AI — thanks for calling support today. [en|James][breath] Hi, I am James. Your order SO-24091 shipped this morning. [en|Abigail][excited] We can narrate up to fifty thousand characters in one job — with speaker tags, emotions, and natural handoffs. [en|James][whisper] Try quality ultra when the message must sound executive-ready.") |
| `voice` | string | Yes | Must be Multi for multi-speaker mode. (allowed: Multi) (default: "Multi") |
| `language` | string | Yes | Top-level language code (required). Use the same codes as POST /voice/voices (e.g. en, de). (default: "en") |
| `quality` | string | No | Quality tier: basic, premium (default), ultra. (allowed: basic, premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3, wav, ogg. Default: mp3. (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response delivery: inline (audio in HTTP body, default), base64, url. (allowed: inline, base64, url) (default: "inline") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### Generate speech (single voice)

`POST https://api.paperoffice.ai/latest/job/add/paperoffice_voice___tts`

#### Overview
Convert text to natural speech using a **single catalog voice** (PaperOffice neural TTS).

Use this endpoint when you need one speaker, a fixed voice from the catalog, and audio in the same response (`output=inline`) or as JSON (`base64` / `url`).

**Pipeline:** `paperoffice_voice___tts` (fixed URL path).

## Prerequisites
1. Call **`POST /voice/voices`** and pick a `name` from the language bucket you need.
2. Default demo pair: **`Abigail`** with **`language=en`** (English, female).
3. Each voice belongs to one catalog language (e.g. `Anneliese` → `de`). If `language` does not match, the API adjusts to the voice bucket and returns `warnings[]`.

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `text` | yes | *(showroom demo)* | Up to 50,000 characters. Default script uses emotion markers and a reference ID (`SO-24091`). |
| `voice` | yes | `Abigail` | Name from `POST /voice/voices` (same bucket as `language`). |
| `language` | yes | `en` | Catalog bucket code (e.g. `en`, `de`). |
| `quality` | no | `premium` | `basic` (fast), `premium` (balanced), `ultra` (best). |
| `output_format` | no | `mp3` | `mp3`, `wav`, `ogg`. |
| `output` | no | `inline` | `inline` = audio stream in HTTP body; `base64` / `url` = JSON. |
| `priority` | no | plan default | Higher = faster queue start. Leave **unchecked** in Postman for your tier default. |

**Text preparation (TTS):** When `language=de`, dates and common German business identifiers (order IDs, invoice refs) in `text` are normalized for natural speech. Other languages use standard number/date handling for the selected `language`.

#### Connection hold
& polling (about 5 minute limit)

This is separate from **queue priority** (billing/speed only).

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** for up to **about 5 minutes (about 295 seconds)** — platform connection limit — and returns the finished result when ready.
- **Hard timeout:** If the job is not done within that window → **HTTP 202** with `job_id` and `poll_url`. **Continue polling** `GET /job/get/{job_id}` every 5–10 seconds until `job_status` is `completed` or `failed`.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` in about 100ms, then poll as above.

Job processing time can exceed 5 minutes; only the **HTTP wait** is capped.

## Start-SLA / processing_lane
(optional)

- **Omitted** → workspace `default_processing_lane` (else fair-use `no_sla`).
- Lanes: `no_sla` | `sla_24h` | `sla_12h` | `sla_6h` | `sla_1h` | `instant` (job price ×1 … ×5).
- **`instant`** → interactive / sync-capable start.
- Legacy `priority` is compat only; **`processing_lane` wins** when both are sent.

See collection guide **Start-SLA (`processing_lane`) — wait-to-start** for tier tables (pricing is not duplicated in this request doc).

## Long text (automatic segmentation)

You may send up to **50,000 characters** in one job. The API accepts the full text in one request — **do not** split the text yourself unless you want separate jobs.

## Related endpoints (same pipeline URL, different body)

| Use case | Postman item |
|----------|----------------|
| Clone voice from audio sample | Clone voice (TTS) — `voice_sample`, no catalog `voice` |
| Multiple speakers in one text | Generate multi-speaker TTS — `voice=Multi` + inline tags | Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | Yes | Text to convert to speech (max 50,000 characters). Inline emotion markers: [chuckle] [laugh] [sigh] [breath] [whisper] [happy] [excited]. Default demo showcases emotions and reference IDs (e.g. SO-24091). (default: "{see_params_tab}") |
| `voice` | string | Yes | Voice name from POST /voice/voices — same language bucket as `language` (required). Default demo: Abigail (en, female). (default: "Abigail") |
| `language` | string | Yes | Language code from the voice catalog bucket (required). Default: en for Abigail. List pairs via POST /voice/voices. (default: "en") |
| `quality` | string | No | Quality tier: basic (fast), premium (balanced), ultra (best). Default: premium. (allowed: basic, premium, ultra) (default: "premium") |
| `output_format` | string | No | Audio format: mp3 (compressed), wav (lossless), ogg. Default: mp3. (allowed: mp3, wav, ogg) (default: "mp3") |
| `output` | string | No | Response delivery: inline (audio stream, default), base64 (JSON), url (download link in JSON). (allowed: inline, base64, url) (default: "inline") |
| `client_wait` | boolean | No | Connection hold: true (default) = API holds this HTTP request while the job runs, up to the dynamic pipeline timeout (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready, or HTTP 202 with job_id and poll_url if the hold is exceeded. false = immediate job_id. |
| `async_only` | boolean | No | Same as client_wait=false: immediate job_id — poll GET /job/get/{job_id} every 5–10s. (default: false) |
| `processing_lane` | string | No | Start-SLA lane (wait-to-start guarantee, not completion). Values: no_sla (fair use ×1), sla_24h (×1.5), sla_12h (×2), sla_6h (×3), sla_1h (×4), instant (×5 interactive start). Prefer this over legacy numeric priority. If omitted: workspace default_processing_lane, else no_sla. (allowed: no_sla, sla_24h, sla_12h, sla_6h, sla_1h, instant) |

**Request body:** `multipart/form-data` (or `application/x-www-form-urlencoded`) — use form fields from the parameters table; upload via `file`/`files` or pass `files` as a JSON array of HTTPS URLs. Do **not** send `application/json` unless the endpoint is listed as JSON-only.

#### Responses

Returns JSON with `status: "success"`; key fields: `job_id` (poll `GET /job/get/{job_id}`) or inline `result` when `client_wait=true`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

#### Connection hold & polling

- **Default (`client_wait` omitted or `true`):** The API holds **this HTTP connection** while the job runs, up to the **dynamic pipeline timeout** (priority, pages, pipeline type; minimum about 20s, infrastructure cap about 295s). Returns the finished result when ready.
- **Hold exceeded:** If the job is not finished in time → **HTTP 202** with `job_id`, `poll_url`, `max_wait_seconds`, and `client_wait: false`. The job **continues in the background** — poll `GET /job/get/{job_id}` every 5–10 seconds.
- **Immediate poll mode:** `client_wait=false` or `async_only=true` → `job_id` immediately (about 100ms), then poll as above.

**Response fields:** `client_wait` (boolean) — whether this response used connection hold; `max_wait_seconds` — actual hold duration attempted.

**Note:** Prefer `processing_lane` Start-SLA for wait-to-start / job price — see collection guide **Start-SLA (`processing_lane`) — wait-to-start**. Legacy `priority` is compat only.

### List available TTS voices

`POST https://api.paperoffice.ai/latest/voice/voices`

#### Overview
Return the **PaperOffice TTS voice catalog**: all neural voices grouped by **language bucket**.

Use this endpoint **before** any `POST /job/add/paperoffice_voice___tts` job to resolve valid `voice` + `language` pairs. This is a **direct REST call** (not a job) — the response is JSON immediately.

(also supports `GET` with the same parameters).

#### Request parameters
| Parameter | Required | Default | Notes |
|-----------|----------|---------|-------|
| `language` | no | *(all languages)* | Optional filter, e.g. `en`, `de`. Returns only that bucket when set. |

Send as query string, form field, or JSON body — the API reads `language` from the request.

## Using the catalog for TTS jobs

1. Call **`POST /voice/voices`** (optionally filter `language=en`).
2. Pick `name` from the returned bucket — it must match the `language` you pass to **`POST /job/add/paperoffice_voice___tts`**.
3. Run **Generate speech (single voice)** with `voice` + `language` from the same bucket.

If `language` in the TTS job does not match the voice bucket, the API may adjust the bucket and return `warnings[]`.

**API reference:** `po-tts-get-available-voices` (documentation ID; not a `/job/add/` pipeline slug)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `language` | string | No | Optional filter: return only this language bucket (e.g. en, de). Omit for the full catalog. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Pricing & Plans

### List pricing plans and tiers

`GET https://api.paperoffice.ai/latest/billing/pricing/tiers`

#### Overview

Lists all available PaperOffice pricing plans (tiers) with prices, credits, features and details. Ideal for price comparisons and recommendations.

**API reference:** `po-billing-plans` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `group` | string | No | tier group filter: app_tier, api_tier, sla_tier (optional, Default: all) (allowed: app_tier, api_tier, sla_tier) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Relations AI — CRM

### Get linked documents

`GET https://api.paperoffice.ai/latest/crm_intelligence/document_links/{crm_account_id}`

#### Overview
Documents linked to a CRM account. Link Types: - invoice - Invoices - contract - Contracts - quote - Quotes - correspondence - Correspondence - related - Other

#### Request parameters
**API reference:** `po-documents-get-linked-documents` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | string | No | Max results (default: 50, max: 200) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get account insights

`GET https://api.paperoffice.ai/latest/crm_intelligence/insights/{crm_account_id}`

#### Overview
All AI insights for a specific CRM account. Including Overall Health Score and Risk Level.

#### Request parameters
**API reference:** `po-insights-get-account-insights` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | integer | No | Optional CRM account ID for targeted insights. |
| `type` | string | No | Filter by insight type (e.g. 'churn_risk', 'sentiment'). |
| `min_score` | number | No | Minimum score value for filtering. |
| `max_score` | number | No | Maximum score threshold for filtering results. |
| `limit` | integer | No | Maximum number results. (default: 50) |
| `offset` | integer | No | Offset for pagination. (default: 0) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get all insights

`GET https://api.paperoffice.ai/latest/crm_intelligence/insights`

#### Overview
All AI Insights across accounts or filtered. Insight Types: - sentiment - communication_sentiment - health_score - relationship_health - churn_risk - attrition_risk - engagement - engagement_level - upsell_potential - upselling_potential - support_satisfaction - support_satisfaction

#### Request parameters
**API reference:** `po-insights-get-all-insights` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `account_id` | string | No | Optional: Filter by CRM account |
| `type` | string | No | Optional: sentiment, health_score, churn_risk, engagement, upsell_potential |
| `min_score` | string | No | Optional: Minimum score |
| `max_score` | string | No | Optional: Maximum score |
| `limit` | string | No | Max results (default: 50, max: 200) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get upsell opportunities

`GET https://api.paperoffice.ai/latest/crm_intelligence/opportunities`

#### Overview
Identify upselling opportunities. Accounts with high upselling potential, sorted by score.

#### Request parameters
**API reference:** `po-opportunities-get-upsell-opportunities` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `min_potential` | string | No | Minimum upsell potential (default: 0.3) |
| `limit` | string | No | Max results (default: 20, max: 100) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get at-risk accounts

`GET https://api.paperoffice.ai/latest/crm_intelligence/at_risk`

#### Overview
Accounts with high churn risk. Sorted by risk score, including factors and recommendations.

#### Request parameters
**API reference:** `po-risk-analysis-get-atrisk-accounts` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `threshold` | string | No | Churn risk threshold (default: 0.5) |
| `limit` | string | No | Max results (default: 20, max: 100) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get sentiment history

`GET https://api.paperoffice.ai/latest/crm_intelligence/sentiment/{crm_account_id}`

#### Overview
Sentiment analysis for an account over time. Shows sentiment trend from emails and notes.

#### Request parameters
**API reference:** `po-sentiment-get-sentiment-history` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `days` | string | No | History period in days (default: 90, max: 365) |

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get CRM statistics

`GET https://api.paperoffice.ai/latest/crm_intelligence/stats`

#### Overview
Global CRM Intelligence Statistics. Overview of all accounts, insights, risks, and opportunities.

#### Request parameters
**API reference:** `po-statistics-get-crm-stats` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Security AI — Fake Email

### Check email

`POST https://api.paperoffice.ai/latest/fakeemail/check`

#### Overview
Check whether an email address is disposable or fake.

**Example emails:** `user@example.com` is a generic placeholder; `test@tempmail.com` is an **intentional disposable-domain** example for fake-email detection demos.

**API reference:** `po-email-detector-check-email` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Email address to check for disposable/fake patterns. |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Check emails

`POST https://api.paperoffice.ai/latest/fakeemail/check_bulk`

#### Overview
Validate a batch of email addresses for deliverability and disposable-domain signals.

#### Request parameters
**API reference:** `po-email-detector-bulk-check-emails` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `emails` | array | Yes | List of email addresses for verification (max. 100) |

**Request body:** `Content-Type: application/json` — send parameters as a JSON object.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Security AI — Fingerprint

### Find similar devices (fingerprint)

`POST https://api.paperoffice.ai/latest/fingerprint/similar`

#### Overview
Find devices with similar fingerprint signals in your tenant. Returns ranked matches with similarity scores for fraud and duplicate-account analysis.

Optional `network_pool` requires a PaperOffice-approved add-on — default is tenant-isolated data only.

#### Request parameters
**API reference:** `po-fingerprint-find-similar-devices-v2` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Visitor-Reference device ID (32-character SHA-256 hash) |
| `threshold` | number | No | Minimum similarity threshold for filtering results (0.0–1.0). (default: 0.7) |
| `network_pool` | boolean | No | Cross-tenant Network Intelligence pool (requires PaperOffice-approved add-on; default false = tenant-isolated) (default: false) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get fingerprint device details

`POST https://api.paperoffice.ai/latest/fingerprint/device`

#### Overview
Load detailed device attributes for a known fingerprint hash — platform, browser family, first/last seen timestamps, and linked session metadata (tenant-scoped).

See the parameter table below for `fingerprint_hash` or `visitor_id`.

#### Request parameters
**API reference:** `po-fingerprint-get-device-details` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | One of (`id`, `visitorId`, `visitor_id`) | Visitor device ID (32 characters). Aliases: visitor_id, visitorId |
| `visitor_id` | string | One of (`id`, `visitorId`, `visitor_id`) | Alias for id (snake_case variant) |
| `visitorId` | string | One of (`id`, `visitorId`, `visitor_id`) | camelCase alias for id (visitorId) for SDK compatibility |

#### Required alternatives

Provide **at least one** of: `id` **or** `visitorId` **or** `visitor_id`.

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get linked devices (fingerprint)

`POST https://api.paperoffice.ai/latest/fingerprint/linked`

#### Overview
List devices linked through shared network and behavioral signals (IP clustering, visitor graph) within your tenant.

Optional `network_pool` requires a PaperOffice-approved add-on — default is tenant-isolated data only.

#### Request parameters
**API reference:** `po-fingerprint-get-linked-devices-v2` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Visitor-ID for network connection lookup (32 characters) |
| `network_pool` | boolean | No | Cross-tenant Network Intelligence pool (requires PaperOffice-approved add-on; default false = tenant-isolated) (default: false) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Identify device (fingerprint)

`POST https://api.paperoffice.ai/latest/fingerprint/identify`

#### Overview

Identify a browser or app visitor from first-party signals (fingerprint hash). Returns a stable device profile for fraud prevention and session correlation within your tenant.

Use the parameter table below for `visitor_id`, optional `network_pool` (approved add-on only), and filters. See **Introduction → Guides** for authentication.

For GDPR erasure of stored identifiers, use **Privacy Forget (Art. 17)** in this collection.

**API reference:** `po-fingerprint-identify-device-v2` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `components` | object | No | Client-side fingerprint components from the JavaScript SDK (Canvas, WebGL, Audio, Fonts, Behavioral) |
| `include` | string | No | Comma-separated Enrichment Modules (e.g., anonywithy, currency) or core for minimal Response |
| `language` | string | No | Language code for enriched data (ISO 639-1) (default: "en") |
| `visitorId` | string | No | Visitor-ID pre-calculated by the client |
| `confidence` | number | No | Client-seitig berechneter confidence-Score (0-100) (default: 0) |
| `botDetection` | object | No | Client-seitige Bot-detectionsdaten with signals-Array |
| `network_pool` | boolean | No | Cross-tenant Network Intelligence pool (requires PaperOffice-approved add-on; default false = tenant-isolated) (default: false) |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Verify fingerprint

`POST https://api.paperoffice.ai/latest/fingerprint/verify`

#### Overview
Verify whether a submitted fingerprint hash matches a known device profile in your tenant. Useful for step-up checks and login risk scoring.

See the parameter table below for required fields. For identifier erasure, use **Privacy Forget (Art. 17)**.

#### Request parameters
**API reference:** `po-fingerprint-verify-fingerprint` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 10 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `visitorId` | string | No | Expected visitor ID to verify against (default: "abc123def456...") |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Security AI — Privacy & Compliance

### Privacy Forget (Art. 17)

`POST https://api.paperoffice.ai/latest/privacy/forget`

#### Overview
Delete fingerprint records for an identifier within the authenticated tenant (Art. 17 GDPR erasure). Sets a tombstone to block re-ingestion of the same identifier.

Provide `identifier_hash` and/or `visitor_id` in the **Body** tab. Processing is limited to your tenant scope.

#### Request parameters
**API reference:** `po-privacy-forget-fingerprint` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `identifier_hash` | string | No | SHA-256 hash of visitor_id or component hash |
| `visitor_id` | string | No | Optional visitor_id to delete directly |

**Request body:** `multipart/form-data` or `application/x-www-form-urlencoded` unless noted otherwise.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Workflow AI — Job Management

### Download Job Result

`GET https://api.paperoffice.ai/latest/job/download/{download_token}`

#### Overview
Download the result file of a completed job. The download_token is returned in the job result from /job/get/{job_id} when the job status is "completed". The token is temporary and expires. Supported result types: images (PNG/JPG/WebP), PDFs, audio files (MP3/WAV), documents (DOCX/XLSX). The response Content-Type header indicates the file format.

#### Request parameters
**API reference:** `po-jobs-download-result` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `download_token` | string | Yes (path) | Temporary download token from the job result (returned by /job/get/{job_id}) |

#### Responses

Returns JSON with `status: "success"`; key fields: `job_result` or binary body for downloads. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get job status and result

`GET https://api.paperoffice.ai/latest/job/get/{job_id}`

#### Overview

Use after async submissions (**HTTP 202**, connection hold timeout, or `client_wait=false`). Returns envelope `status: "success"` on HTTP 200 and **`job_status`** (`pending`, `processing`, `completed`, `failed`), progress metadata, and **`job_result`** when finished.

**Polling:** every **5–10 seconds** until `job_status` is `completed` or `failed`. Top-level `status` is the response envelope — not the job state.

**Query `compact`:** default `true` — omits large OCR/preview blobs from `job_result`. Set `compact=false` for full output.

**API reference:** `po-jobs-get-job-status-result` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 0 credits (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `job_id` | string | Yes (path) | Opaque job ID returned by a prior async submit. |
| `compact` | boolean | No | When true (default), omit large OCR/preview blobs from job_result. Set false for full job output. (default: true) |

#### Responses

Returns JSON with envelope `status: "success"` and **`job_status`** (`pending`|`processing`|`completed`|`failed`); payload in **`job_result`**. Query `compact` (default `true`) omits large OCR/preview blobs. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Get pricelist

`GET https://api.paperoffice.ai/latest/job/pricelist`

#### Overview
Returns all available job pipelines with credit costs and billing units. Keys are pipeline names (e.g. `paperoffice_aiocr___generate`, `paperoffice_imagestudio___generate`, `paperoffice_voice___tts`). Image Studio uses one pipeline with a `model` parameter (`basic`, `premium`, `ultra`) — not separate pipeline suffixes.

#### Request parameters

Use processing_lane for Start-SLA (no_sla|sla_24h|sla_12h|sla_6h|sla_1h|instant).

**API reference:** `po-jobs-get-pricelist` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

### Health ping

`GET https://api.paperoffice.ai/latest/health`

#### Overview
API connectivity check. Returns JSON with `status: "success"` and a human-readable `message` (for example service stability inside configured limits).

**Authentication:** Callable **without** Bearer (load-balancer / connectivity ping; **no credits**). If you send a PaperOffice API Bearer (`po_sk_`, `po_ut_`, `po_pk_`, …) it **must** be valid — unknown or revoked tokens return HTTP **401** `TOKEN_NOT_FOUND`. Valid tokens may incur billing per plan (see `_billing` when present).

**Headers:** This endpoint does **not** emit `RateLimit-*` / `X-RateLimit-*` headers (product endpoints do).

**Response shape:** Both `success: true` and `status: "success"` may appear (redundant by design).

**API reference:** `po-jobs-ping` (documentation ID; not a `/job/add/` pipeline slug) • **Cost:** 1 credit (base, at Start-SLA `no_sla` / ×1; higher lanes multiply job price)

**Parameters:** None required.

#### Responses

Returns JSON with `status: "success"`; most endpoints use top-level fields, jobs use `result` or `job_result`, some account endpoints use `data`. Optional `_billing` and `processing_time`. Errors: HTTP 4xx/5xx with `status: "error"`, `code`, and `message`.

---

## Further Reading

- **Postman Collection:** https://api.paperoffice.ai/latest/docs/postman
- **Pricing:** https://app.paperoffice.ai/en/pricing/calculator
- **Pricing Tiers (API):** https://api.paperoffice.ai/latest/billing/pricing/tiers
- **Credit balance:** `GET /billing/credits/balance` · **Usage log:** `GET /billing/usage-detail`
- **MCP (DMS):** https://mcp.paperoffice.ai/dms
- **MCP (Claude):** https://mcp.paperoffice.ai/claude
- **MCP (Cursor):** https://mcp.paperoffice.ai/cursor
- **MCP (ChatGPT / OpenAI):** https://mcp.paperoffice.ai/openai
- **MCP (Document AI):** https://mcp.paperoffice.ai/mcp-document-ai
- **MCP (Workflow AI):** https://mcp.paperoffice.ai/mcp-workflow-ai
- **MCP (full, 300+):** https://mcp.paperoffice.ai/mcp-full
- **MCP (full reference):** see `llms-full.txt` → MCP Server section
- **Claude.ai allowlist:** mcp.paperoffice.ai and api.paperoffice.ai (two f's; never paperofice)
- **Get API Token:** https://paperoffice.ai

## Workspace type catalog

**107 business types** (UI/MCP parity). Required on `POST /documents/workspaces-create` as `type`. On validation errors the API returns `allowed_types_hint` with samples.

- `ablage`
- `abrechnung`
- `abteilung`
- `agentur`
- `akte`
- `angebot`
- `archiv`
- `auftrag`
- `ausschreibung`
- `bauprojekt`
- `bauvorhaben`
- `behandlung`
- `behoerde`
- `berater`
- `bewerber`
- `buchhaltung`
- `budget`
- `dienstleister`
- `dissertation`
- `dokumentation`
- `dossier`
- `eigentuemer`
- `filiale`
- `foerderprojekt`
- `forschung`
- `forschungsprojekt`
- `freelancer`
- `gewerbeeinheit`
- `grundstueck`
- `gutachten`
- `haendler`
- `handbuch`
- `hausverwaltung`
- `holding`
- `immobilie`
- `initiative`
- `institution`
- `interessent`
- `investition`
- `investor`
- `kampagne`
- `klage`
- `klient`
- `konferenz`
- `kontakt`
- `kooperationspartner`
- `kostenstelle`
- `krankenakte`
- `kredit`
- `kunde`
- `kurs`
- `leasing`
- `lieferant`
- `lizenz`
- `machbarkeitsstudie`
- `mandant`
- `mandat`
- `marke`
- `meeting`
- `messe`
- `mieter`
- `mitarbeiter`
- `niederlassung`
- `onboarding`
- `partner`
- `patent`
- `patient`
- `personalakte`
- `pflegefall`
- `pilotprojekt`
- `praktikant`
- `privat`
- `produkt`
- `produktlinie`
- `programm`
- `projekt`
- `protokoll`
- `publikation`
- `rechtsfall`
- `register`
- `reklamation`
- `sammlung`
- `schueler`
- `schulung`
- `service`
- `sonstige`
- `steuern`
- `stiftung`
- `studiengang`
- `subunternehmer`
- `supportfall`
- `team`
- `temporaer`
- `testumgebung`
- `therapie`
- `tochtergesellschaft`
- `unternehmen`
- `veranstaltung`
- `verband`
- `verfahren`
- `versicherung`
- `vertrag`
- `vertriebspartner`
- `vollmacht`
- `wartungsvertrag`
- `wohneinheit`
- `workshop`

*Generated 2026-08-17 from live API documentation (release `R20260817.0612`).*