API reference › Assignments › Provider portal

Store or update assignment expenses

POST /v1/settings/portal/provider/assignment/provider-expenses

Scope
assignments:write
Roles
service-provider

A service provider adds or updates their own expense lines on an assignment or shift. Rows with an id update that expense; rows without one create a new line. Send multipart/form-data to attach receipts (expenses[N][uploadReceipt] or expenses[N][document]), or JSON without files. The route is open to the service-provider role only.

Parameters

None of its own.

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

Request body required

1 top-level fields; 1 hold nested fields, listed below.

FieldTypeDescription
expenses requiredarray of object (23 nested)

min items 1.

Nested fields

expenses 23 fields
FieldTypeDescription
expenses[].idinteger or null

Existing provider expense id to update; omit to create. A row with id 'reimbursable-basic' (the read-only aggregate row of the provider view) is dropped.

Example 42.

expenses[].assignmentId requiredstring

Work item id, ASG-* or SFT-*. The first row's prefix decides whether every row is checked against assignments or shifts.

Example ASG-23RT45.

expenses[].serviceProviderId requiredstring

Must be an existing service provider id. The first row's value must be the caller's own id.

Example SPR-ABC123.

expenses[].reimbursableExpenseIdinteger or null

Catalog expense id of a template line attached to the work item

Example 7.

expenses[].sourceReimbursableExpenseobject or null

Catalog category a custom line is seeded from. May also be sent as a JSON string (multipart). The legacy flat sourceReimbursableExpenseId is not accepted.

expenses[].sourceReimbursableExpense.idinteger

Example 7.

expenses[].sourceReimbursableExpense.labelstring or null

Example Mileage.

expenses[].categoryIdinteger or null

Bare alternative to sourceReimbursableExpense.id

Example 7.

expenses[].customNamestring or null

min length 1. Example Parking.

expenses[].namestring or null

Accepted in place of customName

min length 1. Example Parking.

expenses[].isDefaultboolean or null

Used with name to resolve whether a name means a template line or a custom one

Example false.

expenses[].expenseTypestring or null

Classification of a freeform custom line

One of: travel, lodging, meals, supplies, miscellaneous. Example travel.

expenses[].reimbursement_basicstring or null

Reimbursement basis of a freeform custom line; defaults to flat_amount when only expenseType is sent

One of: per_unit, per_day, flat_amount, percentage. Example flat_amount.

expenses[].ratenumber (float) or null

Rate for a freeform custom line's basis

Example 0.67.

expenses[].unitstring or null

Unit for a per_unit freeform custom line

Example mile.

expenses[].maximumReimbursementCapnumber (float) or null

Cap for a freeform custom line

Example 100.

expenses[].expensenumber (float) or null

Reimbursement payout; overrides the calculated amount

min 0.01. Example 25.5.

expenses[].amountnumber (float) or null

Submitted cost (the receipt amount), which percentage categories calculate from

min 0.01. Example 40.

expenses[].quantitynumber (float) or null

Units for per_unit / per_day lines

min 0.01. Example 12.

expenses[].billTostring or null

Who the line is billed to; an existing line keeps its own when this is omitted

One of: organization, client. Example client.

expenses[].statusstring

Only pending is accepted; omit to keep an existing line's status

One of: pending. Example pending.

expenses[].uploadReceiptstring (binary) or null

Receipt file (multipart). Some catalog categories require one.

expenses[].documentstring (binary) or null

Alternative receipt field (multipart): pdf, jpg, jpeg or png, at most 2 MB

Example

JSON
{
  "expenses": [
    {
      "id": 42,
      "assignmentId": "ASG-23RT45",
      "serviceProviderId": "SPR-ABC123",
      "reimbursableExpenseId": 7,
      "sourceReimbursableExpense": {
        "id": 7,
        "label": "Mileage"
      },
      "categoryId": 7,
      "customName": "Parking",
      "name": "Parking",
      "isDefault": false,
      "expenseType": "travel",
      "reimbursement_basic": "flat_amount",
      "rate": 0.67,
      "unit": "mile",
      "maximumReimbursementCap": 100,
      "expense": 25.5,
      "amount": 40,
      "quantity": 12,
      "billTo": "client",
      "status": "pending",
      "uploadReceipt": "string",
      "document": "string"
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/settings/portal/provider/assignment/provider-expenses" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"expenses":[{"id":42,"assignmentId":"ASG-23RT45","serviceProviderId":"SPR-ABC123","reimbursableExpenseId":7,"sourceReimbursableExpense":{"id":7,"label":"Mileage"},"categoryId":7,"customName":"Parking","name":"Parking","isDefault":false,"expenseType":"travel","reimbursement_basic":"flat_amount","rate":0.67,"unit":"mile","maximumReimbursementCap":100,"expense":25.5,"amount":40,"quantity":12,"billTo":"client","status":"pending","uploadReceipt":"string","document":"string"}]}'

Try it

Responses

200 Expenses saved

Expenses saved

JSON
{
  "success": true,
  "message": "Expenses submitted for review.",
  "data": null
}
Response fields (3)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Expenses submitted for review..

dataobject or null
400 Bad request

The caller has already completed the work item named by the first row

JSON
{
  "success": false,
  "message": "This assignment has already been completed.",
  "errors": "Action not allowed",
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example This assignment has already been completed..

errorsstring

Example Action not allowed.

codestring

Example .

401 Not signed in

Unauthorized - Authentication required

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 first row's serviceProviderId is not the caller

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'assignments: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 'assignments:write' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Two shapes. Field validation uses this endpoint's own body — status/message/errors, no success key, one message per field. A rule the save itself refuses (for example editing the amount of an approved line) comes back in the standard envelope with the same text in message and errors.

JSON
{
  "status": "error",
  "message": "Unable to save. Please check the highlighted fields.",
  "errors": {
    "expenses.0.customName": "Custom name is required when reimbursableExpenseId is not provided and must be at least 1 character."
  }
}
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

Internal Server Error. A new expense added after the work item's expense submission deadline also lands here, with the same generic message.

JSON
{
  "success": false,
  "message": "Something went wrong!",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Something went wrong!.

errorsstring or null
codestring

Example .