Search operations with lists
When you request a list of objects with the BILL API, you can perform a range of operations in your requests. This includes filtering, sorting, and pagination. In your GET request, add all search operations as query parameters.
Filtering
Set the field name, operator, and value in your list filters as query parameters. Both simple and compound filtering is available.
The format is filters={field_01}:{op}:{value},{field_02}:{op}:{value}
.
Operators
A range of operators are available for you to filter with. See Filterable fields for information about available fields and related operators.
Operator value | Name | Example |
---|---|---|
eq | Equal | filters=accountType:eq:BUSINESS |
ne | Not equal | filters=billCurrency:ne:USD |
gt | Greater than | filters=createdTime:gt:"2024-12-30T00:00:00.000Z" |
gte | Greater than or equal | filters=updatedTime:gte:"2024-12-30T00:00:00.000Z" |
lt | Less than | filters=createdTime:lt:"2024-12-30T00:00:00.000Z" |
lte | Less than or equal | filters=updatedTime:lte:"2024-12-30T00:00:00.000Z" |
in | In | filters=invoiceCurrency:in:"USD,CAD" |
nin | Not in | filters=accountType:nin:"NONE,PERSON" |
sw | Starts with | filters=name:sw:"Hap" |
NOTE
For filtering with
createdTime
andupdatedTime
, you can set a range of ISO 8601 date-time values.
yyyy-MM-dd'T'HH:mm:ss.SSSX
yyyy-MM-dd'T'HH:mm:ss.SSS
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd'T'HH:mm
yyyy-MM-dd
Sample request
In this cURL example, the filter is set for all vendors created in September 2024. A compound filter is set with filters=createdTime:gte:"2024-09-01T00:00:00.000Z",createdTime:lt:"2024-10-01T00:00:00.000Z"
.
curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/vendors?filters=createdTime:gte:"2024-09-01T00:00:00.000Z",createdTime:lt:"2024-10-01T00:00:00.000Z"' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'
Sorting
Set the field name and sort order as query parameters. You can sort in the ascending (asc
) or descending (desc
) order. The default sorting order is ascending. Both simple and compound sorting is available.
The format is sort={field_01}:{sort_order},{field_02}:{sort_order}
.
NOTE
Sorting occurs in the specified order.
Sorting examples | Description |
---|---|
sort=dueDate:asc | Sort by dueDate in the ascending order |
sort=dueDate:desc | Sort by dueDate in the descending order |
sort=dueDate,fundingAmount:desc | Sort by dueDate in the ascending order and fundingAmount in the descending order |
See Sortable fields for information about fields you can sort with.
Sample request
In this cURL example, vendors are sorted by createdTime
in the descending order.
curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/vendors?sort=createdTime:desc' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'
Pagination
When you perform a search, you get a maximum of 100 results with one API request. For example, you get a maximum of 100 bills with one GET /v3/bills
request.
When your search response has over 100 results, the results are paginated. In this case, the response includes nextPage
and prevPage
values for you to navigate between the pages of results. The nextPage
and prevPage
values uniquely represent each page of results based on your search.
Sample request 01: Get first page of 5 results
In this cURL example, vendors are filtered by billCurrency
and also sorted by createdTime
in the descending order. In addition, the max
query parameter is set as 5
to get 5 results per page.
The query parameters are set as filters=billCurrency:eq:USD&sort=createdTime:desc&max=5
.
curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/vendors?filters=billCurrency:eq:USD&sort=createdTime:desc&max=5' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'
Response 01
In the response, the first 5 results are available. A nextPage
value is available for you to get the next page of results in a subsequent request.
{
"nextPage": "{nextPage_value}",
"results": [
{
// result 01
},
...
{
// result 05
}
]
}
Sample request 02: Get next page of 5 results
In this cURL example, the next page of 5 results are requested. The page
query parameter is set as the nextPage
value from the previous response. Since nextPage
value uniquely represents a page of results based on the search, do not set any filters
and sort
parameters.
NOTE
You can change the
max
value in your subsequent request. For example, you can request a next page of 15 results withmax=15
.
The query parameters are set as ?page={nextPage_value}&max=5
.
curl --request GET \
--url 'https://gateway.stage.bill.com/connect/v3/vendors?page={nextPage_value}&max=5' \
--header 'content-type: application/json' \
--header 'devKey: {developer_key}' \
--header 'sessionId: {session_id}'
Response 02
In the response, the next 5 results are available. Both nextPage
and prevPage
values are available for you to navigate between pages of results in a subsequent request.
{
"nextPage": "{nextPage_value}",
"prevPage": "{prevPage_value}",
"results": [
{
// result 06
},
...
{
// result 10
}
]
}
Updated 4 months ago