API reference › Finance › Overview, clients and work items
Get detailed information for multiple assignments or shifts
GET /v1/finance/work-items
- Scope
finance:read- Roles
- admin, client, scheduler
Retrieves comprehensive details for multiple assignments or shifts including client, consumer, providers, expenses, and service rate breakdown. Supports two view types: AR (Accounts Receivable - client billing rates) and AP (Accounts Payable - provider compensation rates).
Parameters
Query parameters
| Name | Type | Description |
|---|---|---|
ids required | string | Comma-separated list of Assignment or Shift IDs to get details for Example |
type | string | View type: 'AR' for Accounts Receivable (client billing rates) or 'AP' for Accounts Payable (provider compensation rates). Defaults to 'AR'. One of: |
provider_id | string | Provider ID as string (optional). When type=AP, filters results and used to determine if each work item is already paid for this provider. If not provided and type=AP, tenant users receive data aggregated for all providers on the work item; portal service-provider users have this defaulted to their own ID when they are assigned to every requested work item (otherwise 403). Example |
client_id | string | Client (billing) user ID as string (optional). For type=AR on client-billed work items, this must match the invoice billing client so the expenses object uses client expense share plus client-approved lines—the same behavior as tenant finance. When set, paid_label and paid_invoice_ids reflect this client. Tenant users may omit this for draft-style AR views. Portal client users: omitting client_id defaults to the authenticated client when they are linked to every requested work item; otherwise 403. Passing another client's ID returns 403. Example |
is_org_invoice | boolean | When type=AR and true, scopes linked_documents to active organization summary invoices (is_org_invoice=true, no client_id). Use for org-billed invoice picker context. Example |
invoice_id | string | When editing an invoice (type=AR): exclude this document from linked_documents. If the invoice is Canceled/Void, linked_documents is returned empty. Does not change is_included_in_billable_entity (still reflects any active link including this invoice). Example |
payable_id | string | When editing a payable (type=AP): exclude this document from linked_documents. If the payable is Canceled/Void, linked_documents is returned empty. Does not change is_included_in_billable_entity (still reflects any active link including this payable). Example |
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Example request
curl "https://api.fetchfido.ai/v1/finance/work-items?ids=ASG-12345,SFT-67890" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID"Try it
Responses
200 Work item details retrieved successfully
Work item details retrieved successfully
{
"success": true,
"message": "Work item details retrieved successfully",
"data": [
{
"id": "ASG-12345",
"type": "assignment",
"title": "Assignment Title",
"total_estimated_cost": 500,
"total_cost_with_expense": 575,
"estimated_subtotal": 590,
"organization_admin_fee": 25,
"provider_admin_fee": 15,
"total_admin_fee": 40,
"location": "Onsite",
"timezone": "America/New_York",
"start_date": "2025-04-21",
"end_date": "2025-04-21",
"start_time": "09:00 AM",
"end_time": "05:00 PM",
"client": {
"id": "CLT-12345",
"name": "John Doe",
"email": "user@example.com",
"phone": "+1234567890",
"logo": null
},
"consumer": {
"id": "CON-67890",
"name": "Jane Smith",
"email": "user@example.com",
"phone": "+1234567891",
"logo": null
},
"assignedProviders": [
{
"locationType": "onsite",
"assignServiceTypeInfo": [
null
]
}
],
"paid_label": "Paid in invoice",
"paid_invoice_ids": [
"INV-12345"
],
"paid_payable_ids": [
"PAY-67890"
],
"is_included_in_billable_entity": true,
"linked_documents": [
{
"id": "INV-TOHWMO",
"type": "invoice",
"status": "Paid",
"status_code": "INVOICE_PAID"
}
],
"cancel_breakdown": {},
"no_show_breakdown": {},
"expenses": {
"items": [
{
"id": 1,
"name": "Mileage",
"rate": 50,
"unit": "mile",
"reimbursementBasis": "per_unit",
"quantity": 24.5,
"quantityReason": "preview"
}
],
"total": 50
},
"serviceRateBreakdown": [
{
"label": "Standard Rate",
"rate": 25,
"hours": 8,
"cost": 200,
"billable_amount": 25,
"time_slot": "09:00 AM - 05:00 PM",
"unit": "hour"
}
]
}
]
}Response fields (66)
3 top-level fields; 1 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | array of object (63 nested) |
Nested fields
data 63 fields
| Field | Type | Description |
|---|---|---|
data[].id | string | Example |
data[].type | string | One of: |
data[].title | string | Example |
data[].total_estimated_cost | number (float) | Total estimated cost. For type=AR: sum of client billing rates (estimated_cost, using billable duration = max(actual, minimum billing duration)). For type=AP: sum of provider compensation rates (estimated_pay × billable duration = max(actual, minimum pay duration)). Example |
data[].total_cost_with_expense | number (float) | total_estimated_cost + expenses.total (admin fees excluded), for both AR and AP. Example |
data[].estimated_subtotal | number (float) | total_estimated_cost + expenses.total + organization_admin_fee + provider_admin_fee, for both AR and AP. Example |
data[].organization_admin_fee | number (float) | Organization/scheduler admin fee for this work item. When client_id is provided and the work item is linked to an invoice, reflects the allocated invoice document org admin fee. Example |
data[].provider_admin_fee | number (float) | Sum of provider admin fees for this work item. When client_id is provided and the work item is linked to an invoice, reflects the allocated invoice document provider admin fee. Example |
data[].total_admin_fee | number (float) | organization_admin_fee + provider_admin_fee. When client_id is provided and the work item is linked to an invoice, these fields reflect allocated invoice document admin fees. Example |
data[].location | string | Location type label Example |
data[].timezone | string | Example |
data[].start_date | string | Example |
data[].end_date | string | Example |
data[].start_time | string | Example |
data[].end_time | string | Example |
data[].client | object | |
data[].client.id | string | Example |
data[].client.name | string | Example |
data[].client.email | string | Example |
data[].client.phone | string | Example |
data[].client.logo | string or null | |
data[].consumer | object or null | |
data[].consumer.id | string | Example |
data[].consumer.name | string | Example |
data[].consumer.email | string | Example |
data[].consumer.phone | string | Example |
data[].consumer.logo | string or null | |
data[].assignedProviders | array of object | |
data[].assignedProviders[].locationType | string | Example |
data[].assignedProviders[].assignServiceTypeInfo | array of object | |
data[].assignedProviders[].assignServiceTypeInfo[].serviceType | string | Example |
data[].assignedProviders[].assignServiceTypeInfo[].assigned | integer | Example |
data[].assignedProviders[].assignServiceTypeInfo[].total | integer | Example |
data[].assignedProviders[].assignServiceTypeInfo[].providers | array of object | |
data[].paid_label | string or null | When client_id (AR) or provider_id (AP) is provided: 'Paid in invoice' or 'Paid in payable' if this work item is already on a paid document for that client/provider; null otherwise. Example |
data[].paid_invoice_ids | array of string | When type=AR and client_id provided: ids of all paid invoices this work item is on; empty array otherwise. |
data[].paid_payable_ids | array of string | When type=AP and provider_id provided: ids of all paid payables this work item is on; empty array otherwise. |
data[].is_included_in_billable_entity | boolean | True when the work item has any active (non-terminal) invoice/payable link for the scoped client/provider, including the document identified by invoice_id/payable_id when editing. Example |
data[].linked_documents | array of object | Active non-terminal finance documents that currently bill this work item for the scoped party. When invoice_id/payable_id is set for edit, that document is omitted; when that context document is Canceled/Void, this array is empty. |
data[].linked_documents[].id | string | Example |
data[].linked_documents[].type | string | One of: |
data[].linked_documents[].status | string | Example |
data[].linked_documents[].status_code | string | Example |
data[].cancel_breakdown | object or null | Present only for canceled work items. Mirrors the |
data[].no_show_breakdown | object or null | Present only for no-show work items that are not canceled. Mirrors the |
data[].expenses | object | |
data[].expenses.items | array of object | |
data[].expenses.items[].id | integer | Example |
data[].expenses.items[].name | string | Example |
data[].expenses.items[].rate | number (float) | Example |
data[].expenses.items[].unit | string | Example |
data[].expenses.items[].reimbursementBasis | string or null | One of: |
data[].expenses.items[].quantity | number (float) or null | Expense quantity; null for flat_amount and percentage bases Example |
data[].expenses.items[].quantityReason | string or null | How quantity was resolved: db, preview, catalog_preview, fallback_one, not_applicable, unknown_basis Example |
data[].expenses.total | number (float) | Example |
data[].serviceRateBreakdown | array of object | Service rate breakdown. For type=AR: shows client billing rates from AssignmentEstimatedCost/ShiftEstimatedCost tables. For type=AP: shows provider compensation rates from AssignmentProviderEstimatedPayRate/ShiftProviderEstimatedPayRate tables. If provider_id is provided with type=AP, only shows rates for that provider. |
data[].serviceRateBreakdown[].label | string | Rate type or service type label. For type=AR: from rate_type. For type=AP: from rateType name or serviceType name. Example |
data[].serviceRateBreakdown[].rate | number (float) | Rate per hour. For type=AR: client billing rate. For type=AP: provider compensation rate (estimated_pay). Example |
data[].serviceRateBreakdown[].hours | number (float) | Hours worked. For type=AR: from hours field. For type=AP: from duration field. Example |
data[].serviceRateBreakdown[].cost | number (float) | Total cost (rate × billable hours, where billable = max(actual, minimum duration)). For type=AR: from estimated_cost. For type=AP: estimated_pay × billable duration. Rows also expose actual_hours/billable_hours/minimum_hours/minimum_applied. Describes the service as scheduled and is NOT replaced when the work item is canceled. Example |
data[].serviceRateBreakdown[].billable_amount | number (float) | What this row actually bills/pays. Equals Example |
data[].serviceRateBreakdown[].time_slot | string | Time slot (for AR type only, empty string for AP type) Example |
data[].serviceRateBreakdown[].unit | string | Billing unit: 'hour' or 'minute' Example |
400 Bad request
Missing required parameter
{
"success": false,
"message": "Missing required parameter: ids"
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
401 Not signed in
Missing, invalid or expired API key.
{
"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
Portal client or service-provider cannot access these work items or attempted to use another party's ID
{
"success": false,
"message": "You don't have permission to access this endpoint. This API key is missing the 'finance:read' 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 |
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"
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |