API reference › Finance › Overview, clients and work items
Get financial overview data
GET /v1/finance/overview
- Scope
finance:read
Retrieves financial overview data including chart time-series data and summary cards. The response adapts based on the authenticated user's role: Admin/Scheduler see organization-level data (all invoices + payables), Providers see provider-specific payables data, and Clients see client-specific invoices data. Supports filtering by time period and date range. Returns two types of summaries: 'summary' (overall all-time totals) and 'periodSummary' (totals filtered by selected period/date range). A Scheduler without Finances Read gets an empty result (200, empty data, meta.total 0, the reason in message) rather than 403, since the dashboard shows it to every Scheduler.
Parameters
Query parameters
| Name | Type | Description |
|---|---|---|
period | string | Time period for grouping data. all=last 10 years by month; today=hourly buckets for current day; this_week/this_month=single week/month by day; daily=last 30 days; weekly=last 12 weeks; monthly=last 12 months. One of: |
startDate | string (date) | Start date for filtering (YYYY-MM-DD format) Example |
endDate | string (date) | End date for filtering (YYYY-MM-DD format) Example |
type | string | Filter by type. For Admin/Scheduler: invoicing or payments (if not specified, returns all available overview types). For Clients: invoicing (Invoice tab, default) or proforma (Pro Forma tab). For Providers: payables (Payables tab, default) or payment_statement (Payment Statements tab). One of: |
status | array of string | Additional financial_statuses.code / snapshot codes to include in 'summary' on top of the always-on default cards (Outstanding, Overdue, Partially Paid, Paid, Pro Forma Outstanding, Pro Forma Overdue for invoicing; Pending Payables, Approved, Payment Issued, Partially Paid, Paid, Payment Statement Outstanding for payments). Only 'summary' (all-time) is affected — 'periodSummary' and the chart series always stay the fixed default set. For type=invoicing, also accepts every individual invoice status (INVOICE_PREPARED, INVOICE_SENT, INVOICE_VIEWED, INVOICE_REFUNDED, INVOICE_CANCELED, INVOICE_VOID) and pro forma status (PROFORMA_PREPARED, PROFORMA_SENT, PROFORMA_VIEWED, PROFORMA_REJECTED) plus snapshot card PROFORMA_PAID (payment_rollup Paid amount bucket, not a lifecycle status), Mka note pro forma statuses are always their own separate cards on the invoicing tab (e.g. 'Prepared' and 'Pro Forma Prepared' never combine into one number), and PROFORMA_ACCEPTED is not available here at all since Pro Forma Accepted only exists on the dedicated type=proforma tab. For type=payments, also accepts every individual payable status (PAYABLE_PREPARED, PAYABLE_REVIEWED, PAYABLE_CANCELED, PAYABLE_VOID) and payment statement status (PAYMENT_STATEMENT_PREPARED, PAYMENT_STATEMENT_SENT, PAYMENT_STATEMENT_VIEWED, PAYMENT_STATEMENT_CANCELED, PAYMENT_STATEMENT_VOID) plus snapshot cards PAYMENT_STATEMENT_PAID / PAYMENT_STATEMENT_PARTIALLY_PAID (payment_rollup amount buckets, not lifecycle statuses). Pass repeated as status[]=CODE or as a single comma-separated value. Alternatively pass status=ALL (or status[]=ALL) to back the 'View all' button — returns every card for the active tab instead of enumerating individual codes. |
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Example request
curl "https://api.fetchfido.ai/v1/finance/overview" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID"Try it
Responses
200 Financial overview retrieved successfully
Financial overview retrieved successfully. Response structure varies by role: Admin/Scheduler returns invoicing + payables + proforma data (or selected type), Provider returns payables only, Client returns invoices only. The 'summary' field contains overall totals (all-time, not filtered by date range), while 'periodSummary' contains totals for the selected period/date range (calculated from chart series data). Both only include default cards unless additional codes are requested via 'statuses'.
{
"success": true,
"message": "Financial overview retrieved successfully",
"data": {
"chart": {
"series": [
{
"name": "Outstanding",
"data": [
137,
210,
160
],
"total": 507
}
],
"categories": [
"Jan 1",
"Jan 2",
"Jan 3"
]
},
"summary": [
{
"id": 1,
"code": "INVOICE_OUTSTANDING",
"amount": "$400",
"label": "Outstanding",
"isDefault": true,
"group": "invoice",
"bgClass": "bg-[var(--mui-palette-primary-main)]",
"color": "var(--mui-palette-primary-main)"
}
],
"periodSummary": [
{
"id": 1,
"code": "INVOICE_OUTSTANDING",
"amount": "$200",
"label": "Outstanding",
"isDefault": true,
"group": "invoice",
"bgClass": "bg-[var(--mui-palette-primary-main)]",
"color": "var(--mui-palette-primary-main)"
}
]
}
}Response fields (27)
3 top-level fields; 1 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object (24 nested) |
Nested fields
data 24 fields
| Field | Type | Description |
|---|---|---|
data.chart | object | |
data.chart.series | array of object | |
data.chart.series[].name | string | Example |
data.chart.series[].data | array of number | |
data.chart.series[].total | number | Sum of 'data' across all categories for this series. Example |
data.chart.categories | array of string | |
data.summary | array of object | Overall totals (all-time current state, not filtered by date range). Represents the Financial Snapshot section. Scoped to the active tab: type=invoicing returns Invoice + Pro Forma cards, type=payments returns Payable + Payment Statement cards. Includes every status for the tab (isDefault=true are the always-visible cards; isDefault=false are the extra cards surfaced by the 'view all statuses' checkboxes). |
data.summary[].id | integer | Example |
data.summary[].code | string | Stable identifier for the card; matches the underlying financial_statuses.code where one exists, otherwise a synthetic rollup code. Example |
data.summary[].amount | string | Example |
data.summary[].label | string | Example |
data.summary[].isDefault | boolean | True for the always-visible snapshot cards; false for cards only shown once the user checks 'view all statuses'. Example |
data.summary[].group | string | Document type the card belongs to: invoice, proforma, payable, or payment_statement. Example |
data.summary[].bgClass | string | Example |
data.summary[].color | string | Example |
data.periodSummary | array of object | Same card set as 'summary', but each amount is scoped to the selected period/date range (by issue_date) instead of all-time. |
data.periodSummary[].id | integer | Example |
data.periodSummary[].code | string | Example |
data.periodSummary[].amount | string | Example |
data.periodSummary[].label | string | Example |
data.periodSummary[].isDefault | boolean | Example |
data.periodSummary[].group | string | Example |
data.periodSummary[].bgClass | string | Example |
data.periodSummary[].color | string | Example |
401 Not signed in
Missing, invalid or expired API key.
{
"success": false,
"message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
"errors": null,
"code": "API_KEY_MISSING"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
403 Not allowed
Scope, tenant, IP allow-list or RBAC check failed.
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope.",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Always empty on this status. Example |
429 Too many requests
Rate limit exceeded. See Retry-After.
{
"success": false,
"message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
"errors": null,
"code": "RATE_LIMITED"
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
500 Server error
Unexpected error
{
"success": false,
"message": "An unexpected error occurred."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |