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

FieldTypeDescription
id requiredstring

Work item id (ASG-* assignment id or SFT-* shift id). The authenticated client must be linked to it.

Example SFT-TJRKRR.

typestring or null

Optional. Ignored if provided; server derives type from id prefix.

One of: assignment, shift. Example shift.

action requiredstring

Action to perform

One of: approve, decline. Example approve.

expenses requiredarray 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 requiredboolean

true = expense line from the catalog template, false = custom expense line.

Example true.

expenses[].id requiredinteger

Expense line id: the template line id when isDefault=true, the custom expense id when isDefault=false.

min 1. Example 253.

expenses[].service_provider_idstring 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 SPR-ABC123.

service_provider_idstring or null

Not read. The provider is taken from expenses[].service_provider_id; a top-level value is accepted and ignored.

Example SPR-ABC123.

decline_reasonstring or null

Required when action=decline

max length 2000. Example Not approved.

Example

JSON
{
  "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

Shell
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

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

Example true.

messagestring

'Expense share action completed successfully.' for a single line; 'Expense share bulk action completed.' for bulk

Example Expense share action completed successfully..

dataobject or object
401 Not signed in

Unauthorized

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

The authenticated client is not linked to the work item

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

Example false.

messagestring

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

errorsany or null

Null on this status.

codestring

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

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

Example false.

messagestring

Example service_provider_id is required when multiple providers are on this work item..

errorsobject
codestring

Example .

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

Server error

JSON
{
  "success": false,
  "message": "An unexpected error occurred — please try again.",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred — please try again..

errorsstring or null

Null in production. The exception message only when the application runs with debug on, so nothing is leaked to an integrator.

codestring

Always empty: the server-error response carries no error code.

Example .