Payment ReconcilerDocumentation
QFind anything/
API Reference

Tenants

Multi-tenancy model—tenants, environments, settings, and data isolation.

What are tenants

A tenant is an isolated workspace. All data—expected transactions, incoming transactions, matches, data sources, webhooks, jobs—belongs to a tenant. Tenants are identified by UUID and have a human-readable name, slug, and abbreviation. Use tenants to separate customers, brands, or business units.

Multi-tenancy model

ConceptDescription
TenantTop-level isolation. Each tenant has its own environments, settings, and data.
EnvironmentPer-tenant: development, staging, production, test. Data is isolated per environment.
SettingsPer tenant and environment. Matching threshold, locale, job schedules, LedgerMatch preferences, cache.
TenantUserUser–tenant assignment. Users are assigned to tenants with a role (admin, viewer) per environment.

Every API request includes X-Tenant-Id and X-Environment. The API enforces that the authenticated user or API key is allowed for that tenant and environment. For API keys, both headers are required and must exactly match the tenant and environment the key was issued for.

Environments

Each tenant has one or more environments. Typical setup:

  • development — Local or dev testing
  • staging — Pre-production
  • production — Live data
  • test — Automated tests (E2E, integration)

Data in production is separate from staging. Create environments as needed. See Environments.

Settings

Settings are stored per tenant and environment. They control:

  • Matching — Confidence threshold, auto-match, matching mode
  • Locale — Timezone, currency, date/number format (used by field mappings)
  • Jobs — Stripe sync schedule, matching schedule, retention
  • LedgerMatch — REST vs gRPC, timeout, retries
  • Cache — Enable/disable match and expected caches

Update via PATCH /tenants/:id/settings with X-Environment. See Settings and Configuration Reference.

Tenant lifecycle

  1. Create — POST /tenants with name, optional slug, abbreviation. See Managing Tenants.
  2. Add environments — POST /tenants/:id/environments for each environment you need.
  3. Configure settings — PATCH /tenants/:id/settings per environment.
  4. Assign users — Grant users access via Users. Invite emails are sent by default.
  5. Configure org branding (optional) — PATCH /tenants/:id/branding for display name and logo. See Branding.
  6. Configure email notifications (optional) — PATCH /tenants/:id/email-settings. See Email Settings.
  7. Configure email transport (optional) — PATCH /tenants/:id/email-settings/transport for custom SMTP. See Email Transport.
  8. Update or delete — PATCH or DELETE tenants as needed. Deleting a tenant cascades to all related data.

Next steps