Accounts & API Keys Overview

Agile Receivables exposes a REST API for syncing customers, accounts (invoices), ledgers, statements, campaigns, payments, and disputes from your own systems into the platform.

This section focuses on how accounts fit into the overall system, and how API keys and workspaces control access.

How accounts fit into Agile Receivables

• Customers represent people or businesses you bill.
• Accounts represent invoices or receivables associated with a customer.
• Ledgers are raw transaction records (charges, payments, adjustments) pushed by third-party source systems. Ledger entries are upserted by external_id.
• Statements are monthly invoices aggregated server-side from ledger entries. One statement is materialized per (customer, calendar month) with positive net charges.
• Campaigns orchestrate outreach and collection flows for overdue accounts. Statements are enrolled into a special Statement-Acknowledgement campaign category.
• Payments record money applied against an account.
• Disputes capture customer challenges or questions raised during collections.

Accounts are always scoped to your company and workspace. The same external system can sync multiple workspaces by using different API keys.

Workspaces, organizations, and API keys

In the Agile Receivables app, admins manage API keys from the Integrations / API Keys area. Keys can be:

• Live keys – used against production data.
• Test keys – used against sandbox data.
• Scoped at either:
  • a single workspace, or
  • an organization with access to multiple workspaces.

When working with accounts and related resources:

• Every request must include an API key in the X-Api-Key header.
• The key’s scopes determine which endpoints and operations are allowed (for example, accounts:read, accounts:write, ledgers:write, statements:read, statements:write).
• For organization-scoped keys, optional workspace filters (such as workspace IDs) may further restrict which accounts are visible or writeable.
• API keys are permanently bound to one workspace/company context and cannot switch workspaces dynamically.
• Data access is implicitly filtered by company_id.

Workspace model

• Company is the workspace unit used for API data scoping.
• Users can belong to multiple workspaces with different membership roles.
• Scopes are configured per API key, not per tenant.

Where to go next

• Architecture – high-level system design, data model, and validation flows.
• Core Concepts – authentication, response envelopes, errors, pagination, and rate limits.
• API Reference – endpoint-level details for customers, accounts, campaigns, payments, and disputes.