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.

📘

NOTE

For filtering with createdTime and updatedTime, 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.

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 with max=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
    }
  ]
}