List invoices

GEThttps://api.fieldtask.example/public/v1/invoices

Permissions: customers:read, invoices:read
Pagination: Cursor, up to 100 per page
Also available as: fieldtask_list_invoices

Returns the invoices in your organization, oldest first by default, one page at a time.

You can narrow the list by customer, status and issue date. Each invoice in the list has its totals, paid amount and balance but not its line items, taxes or discount; read one invoice with Get an invoice for those. Lists show current data, so an invoice created or changed while you page through may or may not appear.

Reading invoices never changes them. There's no endpoint to send an invoice, record a payment or collect money.

Permissions

Permission	Dependency in the permission map
`customers:read`	No dependencies
`invoices:read`	Depends on `customers:read`

Invoicing must be enabled for your organization. Otherwise the response is 404 resource_not_found.

Request

Responses

Response Headers

Cache-Control

Responses must not be cached.

X-Request-ID

Server-generated request correlation ID.

Filtering

All filters are optional and can be combined:

Parameter	Returns
`customer_id`	Only invoices for this customer. The ID must be a customer in your organization; otherwise the response is `404 resource_not_found`.
`status`	Only invoices with this status: `draft`, `sent`, `paid`, `partial` or `void`, or `unpaid` for `sent` and `partial` together.
`issued_from`	Only invoices whose `issued_date` is on or after this date, such as `2026-10-01`.
`issued_to`	Only invoices whose `issued_date` is on or before this date.

status filters on the stored status, not on the balance. unpaid doesn't include drafts, paid or void invoices.
issued_from and issued_to compare the issue date, not the due date or the date the invoice was created. Both are inclusive calendar dates in YYYY-MM-DD format, with no time zone. issued_from can't be later than issued_to.
Send each parameter at most once. Any other parameter is rejected with 400 invalid_query.

Pagination

page_size sets the number of invoices per page, from 1 to 100. The default is 25.
ordering is created_at (oldest first, the default) or -created_at (newest first).
When page.has_more is true, request page.next_page_url with the same Authorization header. It keeps your page size, ordering and filters. It's null on the last page.
If you build URLs yourself, pass page.next_cursor as cursor and keep every other parameter unchanged. Cursors expire within 24 hours and only work with the query and connection that produced them.

To change a filter or the ordering, start again without a cursor. See Pagination.

Invoice fields

Field	Meaning
`invoice_number`	The number FieldTask assigned.
`name`	The invoice's label, or `null`.
`status`	`draft`, `sent`, `partial` (partly paid), `paid` or `void`. `unknown` means a status this API version doesn't recognize; handle it rather than failing.
`customer`	The customer's ID, name and email, or `null` when the customer has been removed.
`issued_date`, `due_date`	Calendar dates with no time zone. `due_date` can be `null`.
`total_tax1`, `total_tax2`	The total of each tax over the invoice's items.
`total_amount`	The total including tax, before the invoice discount.
`discounted_amount`	The final invoice total, after the discount.
`paid_amount`	The sum of payments recorded in FieldTask.
`balance`	`discounted_amount` minus `paid_amount`. It can be negative.

All amounts are decimal strings with two decimal places in currency, rounded half to even at each step. For how they're calculated, see Totals, taxes and discounts. The amounts include every item and payment stored on the invoice, matching what FieldTask shows.

paid_amount and balance reflect payments recorded in FieldTask. They aren't proof of payment in another system.

Errors

Status	`code`	Meaning	What to do
400	`invalid_query`	The query string has an unknown or repeated parameter; `status`, `ordering` or `page_size` has a value that isn't allowed; a date isn't `YYYY-MM-DD`; or `issued_from` is later than `issued_to`.	Send only the documented parameters, each once, with dates as `YYYY-MM-DD`.
400	`invalid_cursor`	The cursor is malformed, was changed, or belongs to a different query, connection or page size.	Use `next_page_url` or the cursor exactly as returned, with the same query. To change the query, start again without a cursor.
401	`invalid_token`	The bearer token is missing, malformed, expired, revoked or issued for a different resource (for example an MCP sign-in).	Send a current REST API token or REST OAuth access token as `Authorization: Bearer …`.
403	`api_access_not_enabled`	FieldTask hasn't enabled API access for this organization, or has disabled it.	An owner or admin requests access in Settings → API connections.
403	`insufficient_scope`	The connection lacks a permission this request needs. `error.code` is `missing_permission`.	Add the permission named in `error.message` to the connection.
404	`resource_not_found`	Invoicing isn't enabled for your organization, invoices aren't available in this environment, `customer_id` isn't a customer in your organization, or the URL is wrong.	Check the customer ID, that your organization can use invoices in FieldTask, and that the path has no trailing slash.
405	`method_not_allowed`	This path doesn't accept the HTTP method, or the create isn't enabled in this environment. The `Allow` header lists the methods that are.	Use a method listed in `Allow`.
429	`rate_limit_exceeded`	Too many requests in the current minute, or too many concurrent requests, for the organization or connection.	Wait for `Retry-After` seconds, then retry.
429	`daily_quota_exceeded`	The organization or connection has used its daily allowance for this kind of request. Allowances reset at 00:00 UTC.	Wait for `Retry-After` seconds, or check remaining allowance in Settings → API connections.
503	`temporarily_unavailable`	The service couldn't complete the request.	Retry with exponential backoff. Retry creates with the same key and body.

Request

# Unpaid (sent or partly paid) invoices issued in October 2026.
curl --get "$FIELDTASK_API_ORIGIN/public/v1/invoices" \
  --header "Authorization: Bearer $FIELDTASK_API_TOKEN" \
  --data-urlencode "status=unpaid" \
  --data-urlencode "issued_from=2026-10-01" \
  --data-urlencode "issued_to=2026-10-31" \
  --data-urlencode "page_size=100"

Response200 OK

Unpaid invoices issued in October

{
  "data": [
    {
      "id": "cccccccc-cccc-4ccc-8ccc-cccccccccc02",
      "invoice_number": "Ex-1038",
      "name": "Rooftop unit inspection",
      "status": "partial",
      "customer": {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "Example Property Services",
        "email": "facilities@example.com"
      },
      "issued_date": "2026-10-14",
      "due_date": "2026-11-13",
      "currency": "USD",
      "total_tax1": "19.80",
      "total_tax2": "0.00",
      "total_amount": "259.80",
      "discounted_amount": "259.80",
      "paid_amount": "100.00",
      "balance": "159.80",
      "created_at": "2026-10-14T16:05:22.904310Z",
      "updated_at": "2026-10-28T10:41:09.377260Z"
    }
  ],
  "page": {
    "has_more": false,
    "next_cursor": null,
    "next_page_url": null
  }
}

Example values. IDs and times will differ in your organization.

Try itRequest builder

1. Set the base URL to your API origin with Edit. 2. Paste your token. 3. Fill in parameters or the body. 4. Press Send API Request, or copy the request below and run it yourself. Your token is only kept on this page. Sends are real requests: a create makes a real record.

Loading the request builder…

List invoices

Permissions​

Request​

Responses​

Filtering​

Pagination​

Invoice fields​

Errors​

Permissions

Request

Responses

Filtering

Pagination

Invoice fields

Errors