API reference › Finance › Overview, clients and work items

Get finance settings by module

GET /v1/finance/settings

Scope
finance:read
Roles
admin, scheduler

Retrieves billing settings for finance modules (invoice, payables, payments, proforma). When module is omitted, returns all modules. Optional client_id scopes invoice and proforma to effective client–organization payment term and automation flags.

Parameters

Query parameters

NameTypeDescription
modulestring

Filter settings by module. Omit to return all modules.

One of: invoice, payables, payments, proforma. Example invoice.

client_idstring

When set, invoice and proforma modules include effective payment_terms and effective flags. For module=invoice, also returns slim admin_fee org defaults (method/amount only).

Example CLT-XZQLQ1.

provider_idstring

When set with module=payables, returns slim provider admin_fee defaults (method/amount only).

Example USR-ABC123.

is_org_invoiceboolean

When true with module=invoice, returns org-billed admin_fee defaults without client_id.

Example false.

workitem_idsstring

Comma-separated assignment/shift IDs (ASG-..., SHF-...). With module=invoice and client_id, returns admin_fee with organization + per-provider rows (fee_source calculated).

Example ASG-ABC123,SHF-XYZ789.

Every call also sends Authorization and X-Tenant-ID; see Getting started.

Example request

Shell
curl "https://api.fetchfido.ai/v1/finance/settings" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID"

Try it

Responses

200 Finance settings retrieved successfully

Finance settings retrieved successfully.

JSON
{
  "success": true,
  "message": "Finance settings retrieved successfully.",
  "data": {
    "payment_terms": {},
    "notes": "Added by the scheduler.",
    "summary": {
      "tax_type": {},
      "tax_amount": 10,
      "discount_type": {},
      "discount_amount": 0
    },
    "effective": {
      "auto_generate": true,
      "auto_send": true
    }
  }
}
Response fields (13)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Finance settings retrieved successfully..

dataobject
data.payment_termsobject

Default payment terms { id, label }

data.notesstring

Default notes

Example Added by the scheduler..

data.summaryobject
data.summary.tax_typeobject
data.summary.tax_amountnumber

Example 10.

data.summary.discount_typeobject
data.summary.discount_amountnumber

Example 0.

data.effectiveobject or null
data.effective.auto_generateboolean

Example true.

data.effective.auto_sendboolean

Example true.

400 Bad request

Invalid module parameter

JSON
{
  "success": false,
  "message": "Invalid module. Must be one of: invoice, payables, payments, proforma."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid module. Must be one of: invoice, payables, payments, proforma..

401 Not signed in

Missing, invalid or expired API key.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

Scope, tenant, IP allow-list or RBAC check failed.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'finance:read' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

404 Not found

Client not found (when client_id is provided)

JSON
{
  "success": false,
  "message": "Client not found."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Client not found..

429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "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)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.

500 Server error

Unexpected error

JSON
{
  "success": false,
  "message": "An unexpected error occurred."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred..