Integration Overview

Plainterms exposes a small public API for organization-owned automations and outbound webhooks for document and landing-page events.

Use the public API when another system needs to identify the organization, list eligible Plainterms users, reserve a document upload, or confirm a document threshold acknowledgment. Use webhooks when Plainterms needs to push the result of document processing or public landing-page activity back to your system.

Integration Surfaces

Surface	Current scope	Where it is configured
Public API	API-key auth, user lookup, document upload reservation, document metadata polling, PDF download, confirmation	API keys in Settings -> API Keys
Webhooks	Seven outbound event types, signed delivery, delivery logs	Settings -> Webhooks
API keys	Organization-scoped Bearer keys for /api/v1	Settings -> API Keys
Retool	One app/workflow pattern using the public API plus return-routed webhook delivery	Retool REST resource and Workflow webhook trigger

There is no public endpoint for API-key management, webhook configuration, document listing/search, multipart document upload, bearerless rendered-PDF download, or OpenAPI discovery today.

Typical Flow

1. A Plainterms administrator creates an organization API key.
2. An integration calls GET /api/v1/users to map a downstream user to a Plainterms user_email.
3. The integration chooses or looks up a stable customer_document_id for the logical customer document when it needs downstream correlation or duplicate-safe re-uploads.
4. The integration calls POST /api/v1/documents with document metadata and that user_email.
5. Plainterms returns a reservation describing the next step on the 202: next_action "upload" comes with a signed storage PUT URL; "none" means the content is already satisfied server-side and there is no upload step (see Handling Duplicate Uploads).
6. When an upload URL was returned, the integration uploads the PDF bytes to that URL.
7. Plainterms processes the document.
8. The integration can poll GET /api/v1/documents/{documentId} or GET /api/v1/documents/custId-{customerDocumentId} for state.
9. Plainterms sends webhook events to enabled endpoints.
10. If metadata or a webhook payload includes download_url or download.url, fetch that /api/v1/documents/{documentId}.pdf resource with the same API key.

Current Contract Rules

• /api/v1 uses Authorization: Bearer <raw API key> only. Browser cookies do not authenticate these endpoints.
• API keys identify an organization, not an individual user. Endpoints that need user attribution use fields such as user_email or confirmed_by_email.
• customer_document_id is optional at the API level, but production integrations that need CRM, Retool, policy-system, webhook, or confirmation correlation should choose one stable value per logical customer document. Duplicate or retry uploads of that same logical document should reuse the same value instead of generating a fresh per-click ID.
• Webhook configuration is UI/remotes only. It is not available through /api/v1.
• Webhook signatures use Webhook-Signature: t=<timestamp>,v1=<hex_hmac>, where the signed string is <timestamp>.<raw JSON body>.
• Document metadata includes a polling object and a download object. The download URL is an API resource, not a signed bearer link.
• Webhook download_url values are absolute URLs to the /api/v1/documents/{documentId}.pdf resource and require the same API key. There is no download_url_expires_at field.

For coding agents, start with Agent Reference or /llms.txt.