API reference › Finance › Provider expenses
Store or update provider expenses
POST /v1/finance/provider-expenses
- Scope
finance:write- Roles
- admin, scheduler
Allows providers or admin/scheduler to submit provider expenses for assignments or shifts. Template rows: for percentage, send amount or expense as submitted receipt (required); optional expense with amount is payout override. For per_unit/per_day/flat, send quantity and/or expense (line total override). maximumReimbursementCap: percentage caps receipt (422 if over); other bases cap line total (422 on explicit override, clamp on calculated). Custom rows (customName): expense amount required.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
| Field | Type | Description |
|---|---|---|
affectFinancials | boolean or null | Required when the change moves money on a work item whose linked finance document is Sent or Approved; without it the call returns 422 FINANCIAL_CONSENT_REQUIRED. true applies the change to those documents; false saves it and marks them out of sync. |
expenses required | array of object | |
expenses[].expense | number (float) | Non-percentage: reimbursement line total or override. Percentage: receipt when amount omitted, or payout override when amount is also sent. Example |
expenses[].amount | number (float) or null | Percentage: submitted receipt/cost. Non-percentage: optional explicit line total. Example |
expenses[].quantity | number (float) or null | Miles, days, uses, sessions for template categories Example |
expenses[].reimbursableExpenseId | integer or null | Example |
expenses[].customName | string or null | Example |
expenses[].status | string or null | One of: |
expenses[].id | string or null | Existing provider expense id when updating Example |
expenses[].assignmentId required | string | Example |
expenses[].serviceProviderId required | string | Example |
expenses[].uploadReceipt | string (binary) or null | Receipt file (PDF, JPG, JPEG, max 2MB) |
expenses[].isDefault | boolean or null | |
expenses[].billTo | string or null | Who the expense is billed to; defaults to organization. One of: |
expenses[].sourceReimbursableExpense | object | Catalog category a custom line is seeded from. |
expenses[].sourceReimbursableExpense.id | integer or string | Example |
expenses[].sourceReimbursableExpense.label | string or null | Example |
Example
{
"affectFinancials": true,
"expenses": [
{
"expense": 25.5,
"amount": 120,
"quantity": 50,
"reimbursableExpenseId": 10,
"customName": "Parking",
"status": "pending",
"id": "123",
"assignmentId": "ASG-12345",
"serviceProviderId": "USR-67890",
"uploadReceipt": "string",
"isDefault": true,
"billTo": "organization",
"sourceReimbursableExpense": {
"id": 1,
"label": "Example"
}
}
]
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/provider-expenses" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"affectFinancials":true,"expenses":[{"expense":25.5,"amount":120,"quantity":50,"reimbursableExpenseId":10,"customName":"Parking","status":"pending","id":"123","assignmentId":"ASG-12345","serviceProviderId":"USR-67890","uploadReceipt":"string","isDefault":true,"billTo":"organization","sourceReimbursableExpense":{"id":1,"label":"Example"}}]}'Try it
Responses
200 Expenses submitted for review
Expenses submitted for review.
{
"success": true,
"message": "Expenses submitted for review.",
"data": {}
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object or null |
401 Not signed in
Unauthorized
{
"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:write' 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 |
422 Validation failed
Validation error
{
"status": "error",
"message": "Unable to save. Please check the highlighted fields",
"errors": {
"name": [
"Please enter a name."
],
"email": [
"The email has already been taken."
]
}
}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
Internal Server Error
{
"success": false,
"message": "An unexpected error occurred — please try again.",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | string or null | Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator. |
code | string | Always empty: the server-error response carries no error code. Example |