Connect to the authorized record.

Authentication and scope

Use an authenticated same-origin session or a signed, short-lived user access token in the Authorization header. Set X-Workspace-ID to a workspace you can access. Never use or expose a service-role credential in a browser or customer integration. This API does not issue unrestricted machine keys.

Authorization: Bearer <short-lived-user-access-token>
X-Workspace-ID: <authorized-workspace-uuid>
Content-Type: application/json
Idempotency-Key: <stable-request-uuid>

Use your configured authentication flow to obtain/refresh user sessions. Missing authentication returns UNAUTHENTICATED; denied workspace or role returns FORBIDDEN. Delegated records require their separately granted scoped routes and cannot be accessed by copying a client workspace ID.

Endpoints

Write requests and retry

1. Generate a UUID once for the intended creation or action. Reuse the same key and exact normalized input after a network timeout. Do not blindly create a new key while the first outcome is unknown.
2. Company creation, quote creation, preview and export creation require a stable request UUID. Orders, approvals and delegation creation require Idempotency-Key as well. Import commit uses the saved import ID and recorded per-row outcomes.
3. Order review/approval requires the exact positive integer version. If the record changes, reload and obtain fresh authorization; a new key does not bypass stale approval.
4. Review, approval, delegation and export requests retain actor-bound replay records. Replayed results describe the original request. For orders, current_status and current_version disclose a later change; replay does not repeat or renew authorization.
5. Changed inputs or a different actor on the same action key return IDEMPOTENCY_CONFLICT. A repeated revoked delegation remains revoked; use a fresh, explicitly authorized grant if needed.

POST /api/v1/orders/<order-uuid>/approvals
Idempotency-Key: <stable-action-uuid>

{
  "version": 4,
  "reason": "Reviewed this exact saved scope and itemized estimate."
}

Order review creation accepts quote_id, version and an optional reason. Quotes require entity_id, coverage_id and scope. Export creation accepts an optional order_id; omit it for workspace scope. Delegation creation requires professional_id, entities, actions and expiry. A client grant alone does not activate professional access.

Pagination and evidence

Lists use offset (integer 0–100000), limit 50, total and next_offset. Use next_offset until null; do not assume one response contains the whole portfolio. Deliverables return delivery_contract and delivery_items separately from the paginated original artifact inventory. An item can be missing, unreviewed or stale even when files are present.

Exports are asynchronous. Poll the returned export ID, check ready status, expiry and checksum, then download while access remains authorized. Scope/size limits fail visibly. Preserve original artifacts and the manifest; PDF/HTML summaries do not certify fulfillment. Expiry and access revocation can prevent later download.

Errors and events

Errors contain a stable code and readable error: INVALID_INPUT, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, IDEMPOTENCY_CONFLICT, VERSION_CONFLICT, INVALID_ACTION, PAYLOAD_TOO_LARGE or UNAVAILABLE. A resource outside the authorized scope can be unavailable without exposing its existence.

Webhook receivers must validate signatures and replay windows, deduplicate event IDs and tolerate out-of-order delivery. Configure allowlisted receivers through Operations → Exports & integrations; inspect delivery history, retries and dead letters. Canonical events include entity.updated, obligation.changed, approval.required, order.submitted, order.accepted, order.rejected, notice.received, deliverable.ready and renewal.upcoming. Actual delivery requires a configured receiver and operating worker.