Search operations with lists

You can retrieve a list of BILL objects with list API operations. BILL provides features for paginating, sorting, and filtering your lists.

For example, retrieve a list of bills with /v2/List/Bill.json. In the request:

• Set start and max for paginating records
• Set the filters array for filtering records
• Set the sort array for sorting records
• Set nested for retrieving additional nested object data
• Set showAudit for retrieving additional details about the user that created the returned bill object

curl --request POST \
--url 'https://api-sandbox.bill.com/api/v2/List/Bill.json' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'devKey={developer_key}' \
--data 'sessionId={session_id}' \
--data 'data={
     "start":0,"max":20,
     "filters":[{"field":"createdTime","op":"<","value":"2024-12-30T07:00:00.000+0000"}],
     "sort":[{"field":"createdTime","asc":"true"},{"field":"dueAmount","asc":"true"}],
     "nested":true,
     "showAudit":true
}'

Pagination

Pagination helps with retrieving a fixed set of records in each API response. With pagination, you can improve your API request performance and also simplify your API response management.

Set start and max in your list API requests for retrieving a fixed set of records. In subsequent API requests, set start as the max value of the first API request for retrieving the next set of records. For example, after retrieving the first 20 bill records, set start as 20 in your second API request to retrieve the next set of 20 bill records.

The default start value is 0 and default max value is 999. You can retrieve a maximum of 1000 results with one list request.

Filtering

Filtering helps with narrowing down results based on fields in the API response.

Set the filters array in your list API requests for retrieving a set of records that match the filter. You can filter records based on multiple fields. There are three fields required in the filters array.

📘

NOTE

createdTime and updatedTime in API responses are in the ISO 8601 format with time offset from UTC. The format is YYYY-MM-DDThh:mm:ss.sss±hhmm.

For example, 2024-12-30T07:00:00.000+0000 is 12 AM Pacific Time (7 AM UTC) on December 30, 2022. If your API testing tool does not support URL encoding, replace ± with %2B.

Filtering operators examples

Your can filter records with a range of operators.

Sorting

Sorting helps with retrieving records in the ascending or descending order in the API response.

Set the sort array in your list API requests for retrieving a set of records in a specific order. You can sort records based on multiple fields. There are two fields required in the sort array.

Viewing nested results

Set nested as true in your list API requests for retrieving additional nested object data in the API response. For example, set nested as true in the /v2/List/Bill.json API request to retrieve billLineItems details for each bill returned in the response.

Viewing created user information

Set showAudit as true in your list API requests for retrieving additional details about the user that created the returned object in the API response.

For example, set showAudit as true in the /v2/List/Bill.json API request to retrieve additional details in the API response about the user that created each bill. For each bill in the response, createdBy is the BILL-generated ID of the user that created the bill. The value begins with 006.

📘

NOTE

Audit logs are available only for /v2/List/Bill.json and /v2/List/SentPay.json.