Opens a new batch, optionally closing existing open batches for the current user
Use this endpoint to create and open a new bill batch. If CloseExistingBatch is true and the user
has other open batches, those batches will be closed before creating the new one. Optionally associates
the batch with an accounting period by period number. The batch code must be unique.
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
BatchCreate
| Property | Description | Type |
|---|---|---|
| accountPeriodNumber | Account period number for batch - will get applied as default to any bill added to this batch | integer (int32) |
| accountPeriodYear | Accountperiod year for batch - will get applied as default to any bill added to this batch Must be between 1900 and 2099 | integer (int32) |
| batchCode | The batch code Required Must be between 0 and 255 characters | string |
| closeExistingBatch | If user has other batches open, should they be closed? | boolean |
| controlCode | Control code for batch - will get applied as default to any bill added to this batch Must be between 0 and 255 characters | string |
| dueDate | Due date for batch - will get applied as default to any bill added to this batch | string (date-time) |
| invoiceNumber | Invoice number for batch - will get applied as default to any bill added to this batch Must be between 0 and 255 characters | string |
| nextReading | Next reading date for batch - will get applied as default to any bill added to this batch | string (date-time) |
| note | Note/comment for batch Must be between 0 and 255 characters | string |
| statementDate | Statement date for batch - will get applied as default to any bill added to this batch | string (date-time) |
Example Request Body
{ "accountPeriodNumber": 1, "accountPeriodYear": 1, "batchCode": "string", "closeExistingBatch": false, "controlCode": "string", "dueDate": "2026-06-29", "invoiceNumber": "string", "nextReading": "2026-06-29", "note": "string", "statementDate": "2026-06-29"
}Responses
200
OK
The request succeeded and the response body contains the requested data.
Response Body Parameters
BatchResponse
| Property | Description | Type | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| accountPeriodName | Account period name batch setting | string | ||||||||||||
| accountPeriodNumber | Account period number batch setting | integer (int32) | ||||||||||||
| accountPeriodYear | Account period year batch setting | integer (int32) | ||||||||||||
| analyzingCount | Number of bills contained in this batch that are currently being analyzed | integer (int32) | ||||||||||||
| batchCode | The batch code | string | ||||||||||||
| batchId | The batch identifier | integer (int32) | ||||||||||||
| batchStatus | The status of the batch (open, pending, closed) | string | ||||||||||||
| billCount | The number of bills in this batch | integer (int32) | ||||||||||||
| controlCode | Control code batch setting | string | ||||||||||||
| createdBy | UserChild | |||||||||||||
|
UserChild properties
|
||||||||||||||
| dueDate | Due date batch setting | string | ||||||||||||
| endDate | The date when the batch was closed | string (date-time) | ||||||||||||
| flagCount | Number of unresolved flags on bills contained in this batch | integer (int32) | ||||||||||||
| hasImportedBills | Denotes if the Batch has any imported bills associated with it | boolean | ||||||||||||
| hasImportsWithKickout | Denotes if the Batch has any import task with Status = “Completed with kickouts” | boolean | ||||||||||||
| hasLogs | Denotes if the Batch has any move log events associated with it | boolean | ||||||||||||
| invoiceNumber | Invoice number batch setting | string | ||||||||||||
| isOpen | Is the batch open | boolean | ||||||||||||
| nextReading | Next reading date batch setting | string | ||||||||||||
| note | Note/comment for the batch | string | ||||||||||||
| runningTotal | The cost of all bills in this batch | number (double) | ||||||||||||
| startDate | The date when the batch was created | string (date-time) | ||||||||||||
| statementDate | Statement date batch setting | string | ||||||||||||
Example Response
{ "accountPeriodName": "string", "accountPeriodNumber": 1, "accountPeriodYear": 1, "analyzingCount": 1, "batchCode": "string", "batchId": 1, "batchStatus": "string", "billCount": 1, "controlCode": "string", "createdBy": { "fullName": "string", "userCode": "string", "userId": 1
}, "dueDate": "string", "endDate": "2026-06-29", "flagCount": 1, "hasImportedBills": false, "hasImportsWithKickout": false, "hasLogs": false, "invoiceNumber": "string", "isOpen": false, "nextReading": "string", "note": "string", "runningTotal": 1.0, "startDate": "2026-06-29", "statementDate": "string"
}