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
andmax
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-stage.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.
Field | Description |
---|---|
field | Field name. See the response body documentation in the API reference to learn about fields that you can filter with. Filterable fields are marked with You can filter with this field . |
op | Operator symbol.= : Equals< : Less than> : Greater than<= : Less than or equal to>= : Greater than or equal to!= : Not equalin : Value in listnin : Value not in listsw : Starts with |
value | Field value |
NOTE
createdTime
andupdatedTime
in API responses are in the ISO 8601 format with time offset from UTC. The format isYYYY-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.
Operator | Description | Example |
---|---|---|
= | Equals | "filters":[{"field":"status", "op":"=", "value":"2"}] |
< | Less than | "filters":[{"field":"createdTime", "op":"<", "value":"2024-12-30T07:00:00.000+0000"}] |
> | Greater than | "filters":[{"field":"updatedTime", "op":">", "value":"2024-12-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"}] |
sw | Starts with | "filters":[{"field":"name", "op":"sw", "value":"COM"}] |
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 |
asc | Sort order.true : Ascending orderfalse : 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 /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
.
Updated 4 months ago