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.
| Field | Type | Description |
|---|---|---|
expenses required | array of object (23 nested) | min items 1. |
Nested fields
expenses 23 fields
| Field | Type | Description |
|---|---|---|
expenses[].id | integer 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 |
expenses[].assignmentId required | string | Work item id, ASG-* or SFT-*. The first row's prefix decides whether every row is checked against assignments or shifts. Example |
expenses[].serviceProviderId required | string | Must be an existing service provider id. The first row's value must be the caller's own id. Example |
expenses[].reimbursableExpenseId | integer or null | Catalog expense id of a template line attached to the work item Example |
expenses[].sourceReimbursableExpense | object 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.id | integer | Example |
expenses[].sourceReimbursableExpense.label | string or null | Example |
expenses[].categoryId | integer or null | Bare alternative to sourceReimbursableExpense.id Example |
expenses[].customName | string or null | min length 1. Example |
expenses[].name | string or null | Accepted in place of customName min length 1. Example |
expenses[].isDefault | boolean or null | Used with name to resolve whether a name means a template line or a custom one Example |
expenses[].expenseType | string or null | Classification of a freeform custom line One of: |
expenses[].reimbursement_basic | string or null | Reimbursement basis of a freeform custom line; defaults to flat_amount when only expenseType is sent One of: |
expenses[].rate | number (float) or null | Rate for a freeform custom line's basis Example |
expenses[].unit | string or null | Unit for a per_unit freeform custom line Example |
expenses[].maximumReimbursementCap | number (float) or null | Cap for a freeform custom line Example |
expenses[].expense | number (float) or null | Reimbursement payout; overrides the calculated amount min 0.01. Example |
expenses[].amount | number (float) or null | Submitted cost (the receipt amount), which percentage categories calculate from min 0.01. Example |
expenses[].quantity | number (float) or null | Units for per_unit / per_day lines min 0.01. Example |
expenses[].billTo | string or null | Who the line is billed to; an existing line keeps its own when this is omitted One of: |
expenses[].status | string | Only pending is accepted; omit to keep an existing line's status One of: |
expenses[].uploadReceipt | string (binary) or null | Receipt file (multipart). Some catalog categories require one. |
expenses[].document | string (binary) or null | Alternative receipt field (multipart): pdf, jpg, jpeg or png, at most 2 MB |
Example
{
"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
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
{
"success": true,
"message": "Expenses submitted for review.",
"data": null
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object or null |
400 Bad request
The caller has already completed the work item named by the first row
{
"success": false,
"message": "This assignment has already been completed.",
"errors": "Action not allowed",
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | string | Example |
code | string | Example |
401 Not signed in
Unauthorized - Authentication required
{
"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 first row's serviceProviderId is not the caller
{
"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)
| 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
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.
{
"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.
{
"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. A new expense added after the work item's expense submission deadline also lands here, with the same generic message.
{
"success": false,
"message": "Something went wrong!",
"errors": null,
"code": ""
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | string or null | |
code | string | Example |