API reference › Finance › Provider expenses
Approve/decline client expense share per expense line
POST /v1/portal/client/assignment/finance/expense-share
- Scope
finance:write- Roles
- client
Client approves or declines their allocated share for one or more client-billable expense lines on an assignment or shift using unified expenses[]. decline_reason is required when action=decline. Decline is final per expense line, and an approved line cannot be approved again. One distinct expense line returns the single-line object in data; two or more return data.results[] and data.errors[] with message 'Expense share bulk action completed.' — a line that fails in a bulk request lands in errors[] and does not fail the request.
Parameters
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
| Field | Type | Description |
|---|---|---|
id required | string | Work item id (ASG-* assignment id or SFT-* shift id). The authenticated client must be linked to it. Example |
type | string or null | Optional. Ignored if provided; server derives type from id prefix. One of: |
action required | string | Action to perform One of: |
expenses required | array of object | Unified payload for single and bulk actions. Duplicate lines are collapsed; a row whose id is not a positive integer is skipped. min items 1. |
expenses[].isDefault required | boolean | true = expense line from the catalog template, false = custom expense line. Example |
expenses[].id required | integer | Expense line id: the template line id when isDefault=true, the custom expense id when isDefault=false. min 1. Example |
expenses[].service_provider_id | string or null | Owning provider for a template line (isDefault=true). Required when multiple providers are on the work item; auto-inferred when only one provider is assigned. Read only from template rows, and the first non-empty value applies to every template line in the request — send one provider's lines per request. Ignored on custom rows. Example |
service_provider_id | string or null | Not read. The provider is taken from expenses[].service_provider_id; a top-level value is accepted and ignored. Example |
decline_reason | string or null | Required when action=decline max length 2000. Example |
Example
{
"id": "SFT-TJRKRR",
"type": "shift",
"action": "approve",
"expenses": [
{
"isDefault": true,
"id": 253,
"service_provider_id": "SPR-ABC123"
}
],
"service_provider_id": "SPR-ABC123",
"decline_reason": "Not approved"
}Example request
curl -X POST "https://api.fetchfido.ai/v1/portal/client/assignment/finance/expense-share" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"id":"SFT-TJRKRR","type":"shift","action":"approve","expenses":[{"isDefault":true,"id":253,"service_provider_id":"SPR-ABC123"}],"service_provider_id":"SPR-ABC123","decline_reason":"Not approved"}'Try it
Responses
200 Expense share action completed
Expense share action completed
{
"success": true,
"message": "Expense share action completed successfully.",
"data": {
"isDefault": true,
"id": 253,
"work_item_reimbursable_expense_id": 253,
"custom_expense_id": 991,
"service_provider_id": "SPR-ABC123",
"status": "approved",
"approved_at": "2026-03-02T10:00:00+00:00",
"approved_by": {
"id": "CLT-ABC123",
"name": "John Doe"
},
"approved_share_total": 10.5,
"declined_at": null,
"declined_by": {
"id": "CLT-ABC123",
"name": "John Doe"
},
"decline_reason": null
}
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | 'Expense share action completed successfully.' for a single line; 'Expense share bulk action completed.' for bulk Example |
data | object or object |
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
The authenticated client is not linked to the work item
{
"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 — a request field failed validation; a template line names no service_provider_id while several providers are on the work item, or no provider is assigned yet (single and bulk); or, for a single line, it is not in the client's share, canceled or changes_required, missing its receipt, already approved, or already declined
{
"success": false,
"message": "service_provider_id is required when multiple providers are on this work item.",
"errors": {
"service_provider_id": [
"service_provider_id is required when multiple providers are on this work item."
]
},
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | object | |
code | string | 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
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 |