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

NameTypeDescription
ids requiredstring

Comma-separated list of Assignment or Shift IDs to get details for

Example ASG-12345,SFT-67890.

typestring

View type: 'AR' for Accounts Receivable (client billing rates) or 'AP' for Accounts Payable (provider compensation rates). Defaults to 'AR'.

One of: AR, AP. Example AR.

provider_idstring

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 SPR-12345.

client_idstring

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 USR-12345.

is_org_invoiceboolean

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 true.

invoice_idstring

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 INV-TOHWMO.

payable_idstring

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 PAYB-ABC123.

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

Example request

Shell
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

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

FieldTypeDescription
successboolean

Example true.

messagestring

Example Work item details retrieved successfully.

dataarray of object (63 nested)

Nested fields

data 63 fields
FieldTypeDescription
data[].idstring

Example ASG-12345.

data[].typestring

One of: assignment, shift. Example assignment.

data[].titlestring

Example Assignment Title.

data[].total_estimated_costnumber (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 500.

data[].total_cost_with_expensenumber (float)

total_estimated_cost + expenses.total (admin fees excluded), for both AR and AP.

Example 575.

data[].estimated_subtotalnumber (float)

total_estimated_cost + expenses.total + organization_admin_fee + provider_admin_fee, for both AR and AP.

Example 590.

data[].organization_admin_feenumber (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 25.

data[].provider_admin_feenumber (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 15.

data[].total_admin_feenumber (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 40.

data[].locationstring

Location type label

Example Onsite.

data[].timezonestring

Example America/New_York.

data[].start_datestring

Example 2025-04-21.

data[].end_datestring

Example 2025-04-21.

data[].start_timestring

Example 09:00 AM.

data[].end_timestring

Example 05:00 PM.

data[].clientobject
data[].client.idstring

Example CLT-12345.

data[].client.namestring

Example John Doe.

data[].client.emailstring

Example user@example.com.

data[].client.phonestring

Example +1234567890.

data[].client.logostring or null
data[].consumerobject or null
data[].consumer.idstring

Example CON-67890.

data[].consumer.namestring

Example Jane Smith.

data[].consumer.emailstring

Example user@example.com.

data[].consumer.phonestring

Example +1234567891.

data[].consumer.logostring or null
data[].assignedProvidersarray of object
data[].assignedProviders[].locationTypestring

Example onsite.

data[].assignedProviders[].assignServiceTypeInfoarray of object
data[].assignedProviders[].assignServiceTypeInfo[].serviceTypestring

Example Personal Care.

data[].assignedProviders[].assignServiceTypeInfo[].assignedinteger

Example 2.

data[].assignedProviders[].assignServiceTypeInfo[].totalinteger

Example 3.

data[].assignedProviders[].assignServiceTypeInfo[].providersarray of object
data[].paid_labelstring 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 Paid in invoice.

data[].paid_invoice_idsarray 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_idsarray 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_entityboolean

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 true.

data[].linked_documentsarray 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[].idstring

Example INV-TOHWMO.

data[].linked_documents[].typestring

One of: invoice, payable. Example invoice.

data[].linked_documents[].statusstring

Example Paid.

data[].linked_documents[].status_codestring

Example INVOICE_PAID.

data[].cancel_breakdownobject or null

Present only for canceled work items. Mirrors the cancellation section from /{module}/{id}/cancellation-setup (clients + providerPolicy + providers). Returns null for non-canceled items, canceled items with no estimated rows, or per-item breakdown computation failures.

data[].no_show_breakdownobject or null

Present only for no-show work items that are not canceled. Mirrors the noShow section from /{module}/{id}/cancellation-setup (clients + providers + totals + no-show flags). Returns null for canceled, non-no-show, missing-row, or per-item breakdown computation failure cases.

data[].expensesobject
data[].expenses.itemsarray of object
data[].expenses.items[].idinteger

Example 1.

data[].expenses.items[].namestring

Example Mileage.

data[].expenses.items[].ratenumber (float)

Example 50.

data[].expenses.items[].unitstring

Example mile.

data[].expenses.items[].reimbursementBasisstring or null

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

data[].expenses.items[].quantitynumber (float) or null

Expense quantity; null for flat_amount and percentage bases

Example 24.5.

data[].expenses.items[].quantityReasonstring or null

How quantity was resolved: db, preview, catalog_preview, fallback_one, not_applicable, unknown_basis

Example preview.

data[].expenses.totalnumber (float)

Example 50.

data[].serviceRateBreakdownarray 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[].labelstring

Rate type or service type label. For type=AR: from rate_type. For type=AP: from rateType name or serviceType name.

Example Standard Rate.

data[].serviceRateBreakdown[].ratenumber (float)

Rate per hour. For type=AR: client billing rate. For type=AP: provider compensation rate (estimated_pay).

Example 25.

data[].serviceRateBreakdown[].hoursnumber (float)

Hours worked. For type=AR: from hours field. For type=AP: from duration field.

Example 8.

data[].serviceRateBreakdown[].costnumber (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 200.

data[].serviceRateBreakdown[].billable_amountnumber (float)

What this row actually bills/pays. Equals cost normally; on a canceled AR row it is that row's share of the client cancellation fee (0 when the client is not billed for cancellation), since a flat/prorated fee does not derive from rate × duration. Use this — not cost — to total a canceled item.

Example 25.

data[].serviceRateBreakdown[].time_slotstring

Time slot (for AR type only, empty string for AP type)

Example 09:00 AM - 05:00 PM.

data[].serviceRateBreakdown[].unitstring

Billing unit: 'hour' or 'minute'

Example hour.

400 Bad request

Missing required parameter

JSON
{
  "success": false,
  "message": "Missing required parameter: ids"
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Missing required parameter: ids.

401 Not signed in

Missing, invalid or expired API key.

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

Portal client or service-provider cannot access these work items or attempted to use another party's ID

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

Example false.

messagestring

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

errorsany or null

Null on this status.

codestring

Always empty on this status.

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

Internal server error

JSON
{
  "success": false,
  "message": "An unexpected error occurred"
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred.