GET /api/v3/bill

Retrieves an array of bills. The array of bills can be filtered by a number of criteria. See the filter property for more details

GetBillsV3 Permissions: BillsAndBatches (View)
Paginated endpoint — This API returns paginated results. Use the pageNumber and pageSize query parameters to control which page of results is returned. The response includes pagination metadata in the response headers. See the Pagination guide for details.

Request Headers

Header Value Required Description
ECI-ApiKey string Yes Your API key. See Authentication.
Content-Type application/json Yes All requests must specify JSON content type.

Query Parameters

Name Description Type Required
filter string (string) Optional
pageSize The number of elements to return in a page integer (int32) Optional
pageNumber The current page number integer (int32) Optional

Filters

Filter Description Type Operators
accountCode Account Number String equals not equals one of like not like not one of
accountId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
accountInfo Account Name String equals not equals one of like not like not one of
accountPeriod AccountPeriod equals not equals less than between greater than less than equal greater than equal
accrual Boolean equals
accrualReversed Boolean equals
active Active (0/1 = F/T) Boolean equals
approved Approval Flag (0/1 = N/Y) Boolean equals
approveDate Bill Approval Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
approvedBy Integer equals not equals less than between one of greater than less than equal greater than equal not one of
batchCloseDate Batch Close Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
batchCode Batch Number String equals not equals one of like not like not one of
batchId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
batchIsOpen Boolean equals
beginDate Bill Begin Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
billID Integer equals not equals less than between one of greater than less than equal greater than equal not one of
billingPeriod Billing Period DatePeriod equals not equals less than between greater than less than equal greater than equal current month prior month prior year prior fiscal year prior 12 months* prior 12 months** year-to-date* year-to-date** fiscal year-to-date* fiscal year-to-date**
checkDate DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
checkNumber String equals
clearedDate DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
commodityCode Commodity Code String equals not equals one of like not like not one of
commodityId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
commodityInfo Commodity Name String equals not equals one of like not like not one of
controlCode Bill Control Code String equals not equals one of like not like not one of
costCenterCode Cost Center Code String equals not equals one of like not like not one of
costCenterId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
costCenterInfo Cost Center Name String equals not equals one of like not like not one of
createdBy Integer equals not equals less than between one of greater than less than equal greater than equal not one of
createdDate Bill Creation Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
dueDate Bill Due Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
endDate Bill End Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
estimated Estimate Flag (0/1 = N/Y) Boolean equals
exported Export Flag (0/1 = N/Y) Boolean equals
exportedby Exported By ID Integer equals not equals less than between one of greater than less than equal greater than equal not one of
exportedDate Bill Export Date DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
exportHold Boolean equals
fromVendor Boolean equals
glExportDate DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
glExported Boolean equals
glexportedby GL Exported By ID Integer equals not equals less than between one of greater than less than equal greater than equal not one of
hasBeenSplit Boolean equals
importVerified Boolean equals
invoiceNumber Invoice Number String equals not equals one of like not like not one of
lastNYears Integer equals
meterCode Logical Device Code String equals not equals one of like not like not one of
meterGroupCode Meter Group Code String equals
meterGroupId Integer equals
meterGroupInfo Meter Group Display String equals
meterId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
meterInfo Logical Device Name String equals not equals one of like not like not one of
mostRecentOnAccount Most Recent Bill On Account Boolean equals
observationMethodCode Measurement Source Code String equals not equals one of like not like not one of
observationMethodId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
organizationInfo Place Group Name String equals
payStatus String equals not equals one of like not like not one of
placeCode Place Code String equals not equals one of like not like not one of
placeGroupCode Place Group Code String equals
placeGroupId Integer equals
placeId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
placeInfo Place Name String equals not equals one of like not like not one of
rateCode Tariff Name String equals not equals one of like not like not one of
rateId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
serialNumber Device Specific Property Value String equals not equals one of like not like not one of
topmostCostCenterCode Topmost Cost Center Code String equals
topmostCostCenterInfo Topmost Cost Center Name String equals
topmostPlaceCode Topmost Place Code String equals
topmostPlaceInfo Topmost Place Name String equals
totalCost Bill Total Cost Double equals not equals less than between greater than less than equal greater than equal
vendorCode Vendor Code String equals not equals one of like not like not one of
vendorID Integer equals not equals less than between one of greater than less than equal greater than equal not one of
vendorInfo Vendor Name String equals not equals one of like not like not one of
void Void Flag (0/1 = N/Y) Boolean equals
wasSplitDate DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days

Response Headers

This endpoint returns pagination metadata in the response headers.

Header Type Description
PageNumber integer The current page number (1-based).
PageSize integer The maximum number of items per page.
TotalNumberOfRecords integer The total number of records matching the query across all pages.
TotalPages integer The total number of pages. Increment pageNumber until it equals this value to retrieve all results.

See the Pagination guide for iteration examples and best practices.

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

Array of:

BillResponse
Property Description Type
account AccountChild
AccountChild properties
Property Description Type
accountCode string
accountId integer (int32)
accountInfo string
active boolean
hasCalculatedMeter boolean
hasSplitChildMeter boolean
hasSplitParentMeter boolean
hasSubAccount boolean
isSubAccount boolean
vendor VendorChild
VendorChild properties
Property Description Type
vendorCode The vendor code string
vendorId The vendor identifier integer (int32)
vendorInfo The vendor info string
accountPeriod The bill’s accounting period integer (int32)
accrual Indicates if the bill is an accrual boolean
accrualReversed Indicates if the bill is a reversed accrual boolean
accrualReversedDate The date and time the accrual was reversed string (date-time)
actualAmountPaid The actual amount paid number (double)
analyzing Indicates whether this bill is currently being analyzed boolean
approveDate The date and time the bill was approved string (date-time)
approved Indicates if the bill has been approved boolean
approvedBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
assignedDate The date and time the bill was assigned to a user string (date-time)
assignedTo UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
balanceForward The amount of balance that was forwarded number (double)
batch BatchChild
BatchChild properties
Property Description Type
batchCode The batch code. string
batchId The batch id. integer (int32)
beginDate The bill’s begin date string (date-time)
billId The bill identifier integer (int32)
billNote Bill note for this bill string
billingPeriod The bill’s billing period integer (int32)
checkDate The date and time of the check string (date-time)
checkImage The API URL that can be used to download the file of the check image string
checkNumber The check number string
clearedDate The cleared date string (date-time)
controlCode The bill’s control code string
costConversion CostConversion
CostConversion properties
Property Description Type
conversionDate The date used to look up the currency conversion string (date-time)
sourceToSystemConversionValue The conversion factor used to convert from the source cost unit to the system cost unit number (double)
sourceUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
systemUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
createdBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
createdDate The date and time the bill was created string (date-time)
currentCharges The current charges number (double)
dirty Indicates if the bill record has been cleaned. Cleaning is an internal EnergyCAP process boolean
dueDate The date and time the bill is due string (date-time)
endDate The bill’s end date string (date-time)
estimated Indicates if the bill is estimated boolean
excludedFromAccruals Indicates whether this bill is excluded from accruals or not boolean
exportDate The date and time the bill was exported string (date-time)
exportHold Indicates if the bill is held for export boolean
exported Indicates if the bill has been exported boolean
exportedBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
fromVendor Indicates if the bill is from a vendor boolean
fundsWithdrawnDate The date when funds were withdrawn string (date-time)
glExportDate The date and time the bill was exported to gl string (date-time)
glExported Indicates if the bill has been gl exported boolean
glExportedBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
hasBeenSplit Indicates if the bill has been split boolean
importVerified Indicates if the import has been verified boolean
invoiceNumber The bill’s invoice number string
invoicePages The number of pages on the invoice integer (int32)
modifiedBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
modifiedDate The date and time of the most recent modification string (date-time)
nextReading The date and time of the next reading string (date-time)
observationMethod ObservationMethodChild
ObservationMethodChild properties
Property Description Type
observationMethodCode Observation method code string
observationMethodId Observation method identifier integer (int32)
observationMethodInfo Observation method name: Automatic, Manual, Estimated, Simulated, Accrual, or Adjustment string
paySource The bill’s pay source string
payStatus The pay status of the bill string
payTo Indicates whom the bill paid string
paymentAmount The net amount of the payment event of the bill number (double)
paymentExportDate The date and time the bill was exported to bill payment string (date-time)
paymentExported Indicates if the bill has been bill payment exported boolean
paymentExportedBy UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
paymentType The payment type of the bill. For example, Check, VCard, and ACH. string
paymentVoucher The API URL that can be used to download the file of the payment voucher string
previousBalance The balance of the previous bill number (double)
reversalDetails BillReversal
BillReversal properties
Property Description Type
description Description of the reversal pair string
referenceBillId Identifier of the other bill in the reversal pair integer (int32)
referenceType Indicates whether the reference bill is a reversal or source of a reversal. It is “Source” if the reference bill is the source bill and “Reversal” if the reference bill is the reversal bill string
statementDate The date and time of the bill statement string (date-time)
totalCost The bill’s total cost in the system currency. The system currency is the reporting/global currency unit. number (double)
totalSourceCost The bill’s total cost in the source currency. The source currency is the native currency unit. number (double)
transRefNum The transaction reference number of the bill string
void Indicates if the bill has been voided boolean
wasSplitDate The date and time the bill was split string (date-time)
Example Response application/json 
[
  {    "account": {      "accountCode": "string",      "accountId": 1,      "accountInfo": "string",      "active": false,      "hasCalculatedMeter": false,      "hasSplitChildMeter": false,      "hasSplitParentMeter": false,      "hasSubAccount": false,      "isSubAccount": false,      "vendor": {}
    },    "accountPeriod": 1,    "accrual": false,    "accrualReversed": false,    "accrualReversedDate": "2026-03-30",    "actualAmountPaid": 1.0,    "analyzing": false,    "approveDate": "2026-03-30",    "approved": false,    "approvedBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "assignedDate": "2026-03-30",    "assignedTo": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "balanceForward": 1.0,    "batch": {      "batchCode": "string",      "batchId": 1
    },    "beginDate": "2026-03-30",    "billId": 1,    "billNote": "string",    "billingPeriod": 1,    "checkDate": "2026-03-30",    "checkImage": "string",    "checkNumber": "string",    "clearedDate": "2026-03-30",    "controlCode": "string",    "costConversion": {      "conversionDate": "2026-03-30",      "sourceToSystemConversionValue": 1.0,      "sourceUnit": {},      "systemUnit": {}
    },    "createdBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "createdDate": "2026-03-30",    "currentCharges": 1.0,    "dirty": false,    "dueDate": "2026-03-30",    "endDate": "2026-03-30",    "estimated": false,    "excludedFromAccruals": false,    "exportDate": "2026-03-30",    "exportHold": false,    "exported": false,    "exportedBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "fromVendor": false,    "fundsWithdrawnDate": "2026-03-30",    "glExportDate": "2026-03-30",    "glExported": false,    "glExportedBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "hasBeenSplit": false,    "importVerified": false,    "invoiceNumber": "string",    "invoicePages": 1,    "modifiedBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "modifiedDate": "2026-03-30",    "nextReading": "2026-03-30",    "observationMethod": {      "observationMethodCode": "string",      "observationMethodId": 1,      "observationMethodInfo": "string"
    },    "paySource": "string",    "payStatus": "string",    "payTo": "string",    "paymentAmount": 1.0,    "paymentExportDate": "2026-03-30",    "paymentExported": false,    "paymentExportedBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "paymentType": "string",    "paymentVoucher": "string",    "previousBalance": 1.0,    "reversalDetails": {      "description": "string",      "referenceBillId": 1,      "referenceType": "string"
    },    "statementDate": "2026-03-30",    "totalCost": 1.0,    "totalSourceCost": 1.0,    "transRefNum": "string",    "void": false,    "wasSplitDate": "2026-03-30"
  }
]