POST /api/v3/import/bill

Imports bills from a base64-encoded file in EnergyCAP Advanced or profile-mapped format

BillImportV3 Permissions: BillsAndBatches (Create)
Use this endpoint to bulk-import utility bills. The file can be CSV, DAT, TXT, XLSX, or a ZIP containing multiple files. The file content must be base64-encoded with UTF8 character set. Optionally specify a profileCode to map a custom file layout to the Advanced format. The import runs asynchronously — use GET /task/{guid} to check progress and results. Requires Bills and Batches Create permission.

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, including the request body.

Request Body

BillImportRequest
Property Description Type
batchSettings BatchSettings
BatchSettings properties
Property Description Type
batchMode needs to be one of - “use existing batch”, “new batch”, “new self-contained batch”, “use pending batch”, “smart batch” if “use existing batch” - we will use an existing open batch and leave it open. Used with ExistingOpenBatchId property. if “new batch” - make a new batch. LeaveExistingBatchesOpen set to true will leave other batches open. If false or not provided, we close the open batch for this user. If more than one batch is open it fails. if “new self-contained batch” - make a new batch and add bills to it and close it. Any open batch will be left open if “use pending batch” - PendingBatchId is required. We will use the pending batch and leave it pending if “smart batch” - NewBatchCode is required. Uses NewBatchCode to determine which batch mode path it should follow. BatchMode is then modified so error message may reflect this new BatchMode. — if newBatchCode already exists in the database and it is a closed batch, create a new batch with a GUID appended to the newBatchCode to make it unique. Any open batch will be left open. BatchMode modified to “new batch” and LeaveExistingBatchesOpen set to true. This scenario can occur if BC is in the middle of processing micro batches and a user closes the original batch that was being used by BC. — if there is a open batch with the newBatchCode and it belongs to the current user, use it. BatchMode modified to “use existing batch” — if there is a open batch with the newBatchCode and it belongs to the another user, use it if the current user has Bills and Batches:Manage.Otherwise, error. BatchMode modified to “use existing batch” — if no open batches, check if there is a pending batch with newBatchCode, if so use it and get bills imported into the pending batch. BatchMode modified to “use pending batch” — if a batch with newBatchCode does not exist, create it and add bills to it, any open batch will be left open. BatchMode modified to “new batch” and LeaveExistingBatchesOpen set to true One of ‘use existing batch’, ’new batch’, ’new self-contained batch’, ‘use pending batch’, ‘smart batch’ string
existingOpenBatchId optional - ID of an existing open batch to use. Only applies when BatchMode is “use existing batch”. If not provided, the current user must have exactly one open batch, otherwise an error occurs. Must reference an open batch belonging to the current user, or if the user has “Bills and Batch: Manage” permission, any user’s open batch. integer (int32)
leaveExistingBatchesOpen optional - Only applies when BatchMode is “new batch”. When true it will leave any existing batches open boolean
newBatchCode required - if batch mode is “smart batch” optional for batch modes “new batch”, “new self-contained batch” - if not provided, we will autocreate the batch code. Ignored for all other batch modes Must be between 0 and 255 characters Required when BatchMode is set to smart batch string
pendingBatchId Pending batchId to import the bills into. Only applies when BatchMode is “use pending batch”. Required when BatchMode is set to use pending batch integer (int32)
comment Optional comment to explain why the audit is being auto resolved string
data The base64 encoded file. Required string
fileName FileName for the import file. Should include extension. Example: fileABC.csv Data contains the contents. The importer will save the under this file name. The extension allows the importer to read the data in the proper format (csv,xlsx,zip) Required string
importNote Optional note/comment. string
profileCode optional - if not provided, we assume the data is in Advanced format A bill import profile code. Maps given data to Advanced format using the mappings defined by this profile string
saveAsResolved Optional property to indicate if failed audits automatically get marked as resolved boolean
suppressBillCaptureNotification Optional property to indicate whether or not to suppress the Bill Capture Automation notification that would normally be sent after a successful import. This is used for microbatches to avoid sending a notification for each microbatch that is imported. Instead, the notification will be sent after all microbatches have been imported from the BillCapture process. Assumes false if not provided. boolean
Example Request Body application/json 
{  "batchSettings": {    "batchMode": "string",    "existingOpenBatchId": 1,    "leaveExistingBatchesOpen": false,    "newBatchCode": "string",    "pendingBatchId": 1
  },  "comment": "string",  "data": "string",  "fileName": "string",  "importNote": "string",  "profileCode": "string",  "saveAsResolved": false,  "suppressBillCaptureNotification": false
}

Responses

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

Response Body Parameters

GuidResponse
Property Description Type
taskGUId A guid that identifies the current task string (uuid)
Example Response application/json 
{  "taskGUId": "string"
}