API reference › Finance › Provider expenses
Bulk store or update provider expenses
POST /v1/finance/provider-expenses/bulk
- Scope
finance:write- Roles
- admin, service-provider, scheduler
Bulk store or update provider expenses. Template percentage rows: amount or expense as receipt (required). Non-percentage: quantity and/or expense/amount as line total. maximumReimbursementCap: receipt cap for percentage (422); line-total cap for other bases. Receipt patch: omit document to keep file. Sync: submitted list is full desired set per group.
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. |
providerExpenses required | array of object | |
providerExpenses[].entityId | string or null | Work item the expenses belong to (ASG-* or SFT-*). Defaults to the work item being saved. Example |
providerExpenses[].providerId required | string | Example |
providerExpenses[].expenses | array of object | |
providerExpenses[].expenses[].id | integer or null | Existing expense id to update; omit to create. Example |
providerExpenses[].expenses[].name required | string | Example |
providerExpenses[].expenses[].amount | number or null | min 0.01. Example |
providerExpenses[].expenses[].expense | number or null | Unit amount, multiplied by quantity. min 0.01. Example |
providerExpenses[].expenses[].quantity | number or null | min 0.01. Example |
providerExpenses[].expenses[].billTo | string or null | One of: |
providerExpenses[].expenses[].document | string (binary) or null | Receipt: pdf, jpg, jpeg or png, max 2 MB. |
providerExpenses[].expenses[].isDefault | boolean or null | |
providerExpenses[].expenses[].reimbursement_basic | string or null | Reimbursement basis of a freeform custom expense. One of: |
providerExpenses[].expenses[].expenseType | string or null | One of: |
providerExpenses[].expenses[].rate | number or null | Required when reimbursement_basic is percentage. min 0. |
providerExpenses[].expenses[].sourceReimbursableExpense | object | Catalog category a custom line is seeded from. |
providerExpenses[].expenses[].sourceReimbursableExpense.id | integer or string | Example |
providerExpenses[].expenses[].sourceReimbursableExpense.label | string or null | Example |
Example
{
"affectFinancials": true,
"providerExpenses": [
{
"entityId": "ASG-SA2IVL",
"providerId": "SPR-H6OUI3",
"expenses": [
{
"id": 42,
"name": "Parking",
"amount": 12.5,
"expense": 12.5,
"quantity": 1,
"billTo": "organization",
"document": "string",
"isDefault": true,
"reimbursement_basic": "per_unit",
"expenseType": "travel",
"rate": 0,
"sourceReimbursableExpense": {
"id": 1,
"label": "Example"
}
}
]
}
]
}Example request
curl -X POST "https://api.fetchfido.ai/v1/finance/provider-expenses/bulk" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"affectFinancials":true,"providerExpenses":[{"entityId":"ASG-SA2IVL","providerId":"SPR-H6OUI3","expenses":[{"id":42,"name":"Parking","amount":12.5,"expense":12.5,"quantity":1,"billTo":"organization","document":"string","isDefault":true,"reimbursement_basic":"per_unit","expenseType":"travel","rate":0,"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": [
{
"entityId": "ASG-12345",
"providerId": "USR-67890",
"expenses": [
{
"id": 123,
"name": "Parking",
"amount": 25.5,
"isDefault": true
}
]
}
]
}Response fields (10)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | array of object | |
data[].entityId | string | Example |
data[].providerId | string | Example |
data[].expenses | array of object | |
data[].expenses[].id | integer or null | Example |
data[].expenses[].name | string | Example |
data[].expenses[].amount | number (float) | Example |
data[].expenses[].isDefault | boolean or null | Example |
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
Forbidden
{
"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 |