API reference

All public endpoints are under /v1 and require Authorization: Bearer <api-key>.

Connections

Method	Path	Purpose
`GET`	`/v1/providers`	List installed and coming-soon providers
`POST`	`/v1/connect-sessions`	Create a customer provider connect session
`GET`	`/v1/connections`	List connections in the key's environment
`DELETE`	`/v1/connections/:connection_id`	Disconnect a provider connection
`POST`	`/v1/connections/:connection_id/sync`	Queue invoice or full reconciliation

Provider discovery distinguishes available adapters from coming_soon providers. A provider is accepted by connect-session creation only after its adapter is installed; catalog discovery never creates a partially supported connection.

Connect-session input includes the accounting provider, stable external_account_id, an allowlisted redirect_uri, an optional AccountingKit provider_app_id, and retention_mode (cached by default or zero). Paid contracts require an organization-owned provider app. A trial may omit it to use hosted OAuth.

Console-only provider app management

These browser-session endpoints are intentionally outside /v1; API keys cannot manage OAuth credentials.

Method	Path	Purpose
`GET`	`/accounting/provider-apps?environment=test\|live`	List apps in an organization environment
`POST`	`/accounting/provider-apps`	Create a resumable provider-app draft
`PUT`	`/accounting/provider-apps/:provider_app_id/credentials`	Encrypt or rotate the app credentials
`POST`	`/accounting/provider-apps/:provider_app_id/verify`	Check credentials, OAuth, webhook, and scopes

Draft creation takes environment, provider, name, and make_default, and immediately returns the exact callback URLs. Credentials are submitted separately so operators can configure those URLs in the provider portal before secrets are stored. Provider apps are isolated to one environment; the server derives and proves the environment's organization ownership in SQL.

Resources

Replace :resource_type with organizations, contacts, invoices, quotes, payments, purchase_orders, accounts, tax_rates, or branding_themes.

Method	Path	Behavior
`GET`	`/v1/connections/:connection_id/:resource_type`	Paginated cached list
`GET`	`/v1/connections/:connection_id/:resource_type/:resource_id`	Live provider read
`POST`	`/v1/connections/:connection_id/:resource_type`	Idempotent normalized create
`PATCH`	`/v1/connections/:connection_id/:resource_type/:resource_id`	Idempotent normalized update
`POST`	`/v1/connections/:connection_id/invoices/:resource_id/cancel`	Status-aware Xero cancellation
`POST`	`/v1/connections/:connection_id/invoices/by-provider-id/:provider_id/cancel`	Cancel from a stored Xero ID

Organizations, tax rates, and branding themes are read-only. Contacts, invoices, quotes, payments, and purchase orders accept normalized writes where Xero supports the operation. Accounts are writable only through the provider-native body; a normalized account payload is rejected with accounts is read-only in v1. Provider-native writes are documented separately and retain Xero-only fields.

List queries support page, limit, status, number, and external_reference. Pagination is returned in meta. Every JSON success response uses { success, message, data }.

Automations and operations

Method	Path	Purpose
`POST`	`/v1/automations`	Queue an idempotent recipe
`GET`	`/v1/operations/:operation_id`	Read durable execution state
`POST`	`/v1/operations/:operation_id/replay`	Replay a failed or dead-letter operation
`POST`	`/v1/webhook-deliveries/:delivery_id/replay`	Replay a failed customer webhook
`GET`	`/v1/webhook-deliveries`	List deliveries by state for recovery

Automation creation returns 202. Poll until state is succeeded, failed, or dead_letter, or consume signed webhook events.

Connection sync accepts { "scope": "invoices" } by default or { "scope": "all" }. Invoice scope is the low-cost operational safety net: it compares live provider payment state, emits payment transitions, and instructs consumers to refresh mutable invoice PDFs. Set "emit_invoice_snapshots": true on an explicit sync to emit invoice.updated for every discovered invoice. This is intended for a controlled consumer bootstrap; scheduled reconciliation keeps it disabled and emits only meaningful payment changes.

Provider actions

POST /v1/connections/:connection_id/provider-actions/:action exposes explicit Xero-only behavior:

invoice.download_pdf
quote.download_pdf
purchase_order.download_pdf
invoice.get_online_url
organization.get_deep_link

PDF actions return application/pdf. Other actions use the standard JSON envelope.

Required write headers

Resource writes, cancellation, synchronization, automations, and replay requests require an Idempotency-Key of at most 255 characters. Responses include Idempotent-Replayed: true|false.