Search operations with lists

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

For example, retrieve a list of bills with /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":"2022-06-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.

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.

Field

Description

field

Field name. This can be any response body field, such as createdTime or updatedTime.

op

Operator symbol.
=: Equals
<: Less than
>: Greater than
<=: Less than or equal to
>=: Greater than or equal to
!=: Not equal
in: Value in list
nin: Value not in list

value

Field value

📘

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, 2022-06-30T07:00:00.000+0000 is 12 AM Pacific Time (7 AM UTC) on June 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.

Operator

Description

Example

=

Equals

"filters":[{"field":"status", "op":"=", "value":"2"}]

<

Less than

"filters":[{"field":"createdTime", "op":"<", "value":"2022-06-30T07:00:00.000+0000"}]

>

Greater than

"filters":[{"field":"updatedTime", "op":">", "value":"2022-06-30T07:00:00.000+0000"}]

<=

Less than or equal to

"filters":[{"field":"paymentStatus", "op":"<=", "value":"2"}]

>=

Greater than or equal to

"filters":[{"field":"paymentStatus", "op":">=", "value":"2"}]

!=

Not equal

"filters":[{"field":"paymentStatus", "op":"!=", "value":"0"}]

in

Value in list

"filters":[{"field":"paymentType", "op":"in", "value":"0, 1"}]

nin

Value not in list

"filters":[{"field":"paymentType", "op":"nin", "value":"0, 1, 2"}]

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.

Field

Description

field

Field name. This can be any response body field, such as createdTime or updatedTime.

asc

Sort order.
true: Ascending order
false: Descending order

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 /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 /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.com-generated ID of the user that created the bill. The value begins with 006.

📘

NOTE

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


Did this page help you?