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-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":"2025-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 999 results with one list request.

Filter

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.

👍

ISO 8601 time format with time offset from UTC

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, 2025-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.

Filter operators examples

Your can filter records with a range of operators.

Sort

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.

Get related information

Set related in your list and read API requests for retrieving additional information that is read to the current object. For example, in your list bills API request, add "related": ["Vendor"] in the request body to get the vendor name for each bills in the API response.

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,
     "related": ["Vendor"]
}'

{
    "response_status": 0,
    "response_message": "Success",
    "response_data": [
        {
            "entity": "Bill",
            "id": "{bill_id}",
          
            // Other bill fields
          
            "related": {
                "vendorId": {
                    "name": "{vendor_name}"
                }
            },
          
            // Other bill fields

        },
      
        // Other bills
      
    ]
}

BILL objects and related fields you can set

View 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.

View 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.

❗️

Audit log limitations

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