API overview
Base URL, JSON conventions, pagination, and error shape.
The SaaSFlow API is HTTPS-only and uses JSON for both requests and responses. Almost
every resource lives under /companies/{companyId}/….
Base URLs
| Environment | URL |
|---|---|
| Production | https://api.saasflow.com |
| Staging | https://staging-api.saasflow.com |
| Local dev (sfdev) | https://{handle}-api.saasflowdev.com |
Resource structure
/companies Companies you have access to
/companies/{companyId} One company
/companies/{companyId}/accounts Bank/cash accounts
/companies/{companyId}/account_groups Saved sets of accounts
/companies/{companyId}/customers
/companies/{companyId}/vendors
/companies/{companyId}/counterparties Counterparty search
/companies/{companyId}/transactions
/companies/{companyId}/subscriptions
/companies/{companyId}/subscription_events The events behind every subscription
/companies/{companyId}/categories
/companies/{companyId}/products
/companies/{companyId}/plan_items P&L planning values
/companies/{companyId}/planned_transactions
/companies/{companyId}/planned_transaction_occurrences
/companies/{companyId}/comments Transaction comments
/companies/{companyId}/files
/companies/{companyId}/notifications
/companies/{companyId}/integrations
/companies/{companyId}/users Team members
/companies/{companyId}/background_tasks Long-running imports/jobs
/companies/{companyId}/agent_definitions Available AI agents
/companies/{companyId}/agent_runs AI agent runs
/companies/{companyId}/categorization_suggestions
/companies/{companyId}/data/{slice} Analytics slices (MRR, P&L, etc.)
/companies/{companyId}/search?q=… Free-text searchSee API reference for every endpoint with parameters, responses, and code samples, and Data slices for the analytics endpoints.
Pagination
List endpoints accept limit and offset query params. When limit is set, the
response is wrapped:
{
"items": [...],
"totalCount": 1432
}Without limit, some list endpoints return a bare array. Always pass limit if you
want pagination metadata.
Filtering by integration
The customers, vendors and products list endpoints accept a linkedTo query param:
- an integration name (
stripe,hubspot,digistore24,finway, …) keeps the rows carrying an external id from that integration, anykeeps rows linked to at least one integration,nonekeeps rows linked to no integration.
GET /companies/{companyId}/customers?linkedTo=digistore24&limit=100GET /companies/{companyId}/customers/linked_systems (and the same under vendors and
products) returns the integration names at least one row is linked to, which is what
a filter menu should offer.
Errors
Errors are JSON with a non-2xx status code:
{
"error": "Invalid request",
"code": "validation_failed"
}code is optional; error is always present. A request that fails validation also
lists every problem under issues, each with the path of the field it concerns:
{
"error": "Invalid input: expected string, received undefined",
"issues": [
{
"path": "categorizations.0190a1b2-0000-7000-8000-000000000001.categoryId",
"message": "Invalid input: expected string, received undefined"
}
]
}Ids in paths are UUIDs in their canonical form (8-4-4-4-12 hex digits). Anything else gets a
400 that names the parameter.
The HTTP status code is the source of truth:
| Status | Meaning |
|---|---|
400 | Bad request, usually validation. |
401 | Missing or invalid credentials. |
403 | Authenticated but lacking permission (see Team & permissions). Code COMPANY_INACTIVE means the company has no active plan: every /companies/{companyId} route answers this until an admin subscribes in the web app. |
404 | Resource not found (or hidden by your permissions). |
409 | Conflict — e.g. trying to create a duplicate. |
429 | Rate-limited (rare). |
5xx | Server error — safe to retry. |
Content types
- Requests with a body:
Content-Type: application/json. - Responses:
Content-Type: application/jsonfor data,Content-Type: application/pdfor similar for file downloads under/files.
OpenAPI spec
The full OpenAPI 3.1 document is served unauthenticated at
https://api.saasflow.com/openapi.json
(/openapi still works) and from these docs at /openapi.json. Every
operation carries security (bearer API key, or OAuth with saasflow:read /
saasflow:write) and x-saasflow-permissions, the permission an API key needs for it.
Point a code generator at either URL to get a typed client:
npx openapi-typescript https://api.saasflow.com/openapi.json -o saasflow.d.tsThe API reference is generated from the same document.