Developer API

External integrations authenticate via x-api-key. API keys are workspace-scoped with granular permission levels per resource.

Authentication

Every request must include the x-api-key header with a valid key. Keys are generated in workspace settings and scoped to a single workspace.

curl -X GET https://app.figa.io/api/v1/expenses?year=2026&month=2 \
  -H "x-api-key: et_live_abc123..."

Permission model

Each API key has per-resource permissions. Available actions per resource:

• Workspace settings expose read and write key presets.
• write permission implies read access.
• write preset covers mutation routes, including delete and payment operations.
• Non-allowlisted routes return 403 FORBIDDEN.

Categories

Recipients

Expenses

Payments

Insights

Deterministic analytics endpoints — aggregations, trends and forecasts computed from expense data. All require expenses.read permission. See Insights reference for full query parameters, response schemas and curl examples.

Context & Notifications

Create expense — request body

POST /api/v1/expenses · Permission: expenses.write

Minimal one-time expense

curl -X POST https://app.figa.io/api/v1/expenses \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS June invoice",
    "amount": 14250,
    "categoryInput": "Cloud"
  }'

Full one-time expense

curl -X POST https://app.figa.io/api/v1/expenses \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office rent February",
    "amount": 420000,
    "categoryInput": "Housing",
    "recipientInput": "WeWork",
    "description": "Monthly office rent, invoice #2026-02",
    "expenseDate": 1739577600,
    "currency": "PLN"
  }'

Recurring expense (monthly rent)

curl -X POST https://app.figa.io/api/v1/expenses \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office rent",
    "amount": 420000,
    "categoryInput": "Housing",
    "recipientInput": "WeWork",
    "schedule": {
      "frequency": "monthly",
      "startDate": "2026-01-01",
      "dayOfMonth": 1
    }
  }'

For all schedule variants (weekly, quarterly, yearly, limited installments, etc.) see the Recurring schedule reference.

Update expense — request body

PUT /api/v1/expenses/:expenseId · Permission: expenses.write

Partial update — include only the fields you want to change.

editScope — recurring expense edits

When updating or deleting a recurring expense, editScope controls which occurrences are affected:

Update single occurrence of a recurring expense

curl -X PUT https://app.figa.io/api/v1/expenses/{expenseId} \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 450000,
    "editScope": "THIS_INSTANCE"
  }'

Update all future occurrences

curl -X PUT https://app.figa.io/api/v1/expenses/{expenseId} \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 450000,
    "editScope": "FUTURE_INSTANCES"
  }'

List expenses — query parameters

GET /api/v1/expenses · Permission: expenses.read

List unpaid expenses for February 2026

curl -X GET "https://app.figa.io/api/v1/expenses?year=2026&month=2&showUnpaidOnly=true" \
  -H "x-api-key: et_live_abc123..."

Delete expense

DELETE /api/v1/expenses/:expenseId · Permission: expenses.delete

For recurring expenses, pass editScope as a query parameter to control what gets deleted:

# Delete single occurrence
curl -X DELETE "https://app.figa.io/api/v1/expenses/{expenseId}?editScope=THIS_INSTANCE" \
  -H "x-api-key: et_live_abc123..."

# Delete entire recurring series
curl -X DELETE "https://app.figa.io/api/v1/expenses/{expenseId}?editScope=ALL_INSTANCES" \
  -H "x-api-key: et_live_abc123..."

Add payment — request body

POST /api/v1/expenses/:expenseId/payments · Permission: expenses.payments

Full payment with method

curl -X POST https://app.figa.io/api/v1/expenses/{expenseId}/payments \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14250,
    "paymentDate": 1739577600,
    "paymentMethod": "bank_transfer",
    "notes": "Invoice #2026-02 paid"
  }'

Quick payment (full amount, today)

curl -X POST https://app.figa.io/api/v1/expenses/{expenseId}/payments \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{}'

Monthly totals — query parameters

GET /api/v1/expenses/monthly-totals · Permission: expenses.read

curl -X GET "https://app.figa.io/api/v1/expenses/monthly-totals?startYear=2026&startMonth=1&months=6" \
  -H "x-api-key: et_live_abc123..."

Bulk actions — request body

POST /api/v1/expenses/bulk · Permission: expenses.write · Returns HTTP 207

Payload by action

Bulk mark as paid

curl -X POST https://app.figa.io/api/v1/expenses/bulk \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "markAsPaid",
    "ids": ["550e8400-...", "6ba7b810-..."],
    "payload": {
      "paymentDate": 1739577600,
      "paymentMethod": "bank_transfer"
    }
  }'

Bulk change category

curl -X POST https://app.figa.io/api/v1/expenses/bulk \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "updateCategory",
    "ids": ["550e8400-...", "6ba7b810-..."],
    "payload": {
      "categoryId": "a1b2c3d4-..."
    }
  }'

Skip / restore occurrence

POST /api/v1/expenses/:expenseId/skip/toggle · Permission: expenses.write

Toggle the skip status of a single recurring occurrence. Only unpaid instances can be skipped. Skipped instances remain visible but are excluded from totals.

Skip using Unix timestamp

curl -X POST https://app.figa.io/api/v1/expenses/{expenseId}/skip/toggle \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"scheduledDate": 1740787200}'

Skip using ISO date (recommended for automations)

curl -X POST https://app.figa.io/api/v1/expenses/{expenseId}/skip/toggle \
  -H "x-api-key: et_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"scheduledDate": "2026-03-30"}'

If no matching occurrence exists, API returns 404 (for both timestamp and ISO date).

Idempotency

POST mutations support the Idempotency-Key header (UUID format). If the same key is sent again within 24 hours, the server returns the cached response instead of processing the request again. This prevents duplicate creates from chatbot retries.

curl -X POST https://app.figa.io/api/v1/expenses \
  -H "x-api-key: et_live_abc123..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name":"AWS","amount":14250,"categoryInput":"Cloud"}'

Error handling