Collective identifiers
A collective identifier (Identyfikator Zbiorczy, IZ) is a single number that groups several invoices in KSeF. A buyer who pays several invoices with one transfer quotes the collective identifier in the payment title, instead of the KSeF number of each invoice.
From 1 January 2027, active Polish VAT taxpayers paying each other by bank transfer must quote in the payment title the KSeF number of the invoice, or the collective identifier when the transfer pays more than one invoice. See KSeF number and collective identifier on the Polish government site.
The list of collective identifiers returned by the API comes from KSeF and can contain data created by third party systems.
A collective identifier:
- groups from 2 to 500 invoices, all issued by the same seller;
- can be created by the seller or by another party, such as the buyer;
- is 35 characters long, for example
1111111111-IZ202607-65ED02180000-E7: a NIP,IZ, the year and month of creation, a unique code, and a checksum.
The collective identifiers API is in preview and may change.
The Legal Entity must be onboarded in A-Cube, with the active status.
Every call except the validation is sent to KSeF, and the API returns 429 Too Many Requests when the KSeF rate limit is exceeded.
Validate a collective identifier
POST /collective-identifiers/validate checks the format and the CRC-8 checksum of collective identifiers locally, without contacting KSeF,
for example, to check the one in a payment title before decoding it:
curl -i -X POST \
'https://pl-sandbox.api.acubeapi.com/collective-identifiers/validate' \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "collectiveIdentifiers": ["1111111111-IZ202607-65ED02180000-E7"] }'
The API returns isValid for each identifier and, when it is valid, the seller NIP and the year and month of creation; otherwise they are null:
{
"collectiveIdentifiers": [
{
"collectiveIdentifierNumber": "1111111111-IZ202607-65ED02180000-E7",
"isValid": true,
"nip": "1111111111",
"year": 2026,
"month": 7
}
]
}
Create a collective identifier
Send the invoices to POST /legal-entities/{legalEntityUuid}/collective-identifiers.
Reference each invoice by its A-Cube uuid or by its ksefNumber, and optionally add the amount paid and a description of up to 512 characters:
curl -i -X POST \
'https://pl-sandbox.api.acubeapi.com/legal-entities/{legalEntityUuid}/collective-identifiers' \
-H 'Authorization: Bearer TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"invoices": [
{
"uuid": "a85fc754-5367-11ed-bdc3-0242ac120002",
"payment": { "amount": 100.50, "currency": "PLN" },
"description": "Invoice FV/1/2026"
},
{
"ksefNumber": "1111111111-20260612-6310EC800000-DA",
"payment": { "amount": 45, "currency": "PLN" },
"description": "Invoice FV/2/2026"
}
]
}'
The API returns 201 Created with the collective identifier:
{
"collectiveIdentifierNumber": "1111111111-IZ202607-65ED02180000-E7"
}
The API returns 422 Unprocessable Entity when the request is not valid, for example with fewer than 2 or more than 500 invoices,
or with an invoice that has neither uuid nor ksefNumber.
Decode a collective identifier
To get the invoices grouped by a collective identifier, for example, the one quoted in a payment you received, call
GET /legal-entities/{legalEntityUuid}/collective-identifiers/{collectiveIdentifierNumber}:
curl -i -X GET \
'https://pl-sandbox.api.acubeapi.com/legal-entities/{legalEntityUuid}/collective-identifiers/1111111111-IZ202607-65ED02180000-E7' \
-H 'Authorization: Bearer TOKEN'
{
"invoices": [
{
"ksefNumber": "1111111111-20260612-6310EC800000-DA",
"invoiceUuid": null,
"payment": { "amount": 45, "currency": "PLN" },
"description": "Invoice FV/2/2026",
"detailsHidden": false
},
{
"ksefNumber": "1111111111-20260612-62EAFD400000-B3",
"invoiceUuid": "a85fc754-5367-11ed-bdc3-0242ac120002",
"payment": null,
"description": null,
"detailsHidden": false
}
],
"continuationToken": null
}
invoiceUuidis the invoice in A-Cube,nullwhen the invoice is not stored for this Legal Entity.paymentis the payment details provided when creating the collective identifier,nullif it was not provided.descriptionis the description provided when creating the collective identifier,nullif it was not provided.detailsHiddenistruewhen KSeF hides the payment details because the Legal Entity has no access to the invoice.
List collective identifiers
To list the collective identifiers created by the Legal Entity, or including invoices it issued as seller, call
GET /legal-entities/{legalEntityUuid}/collective-identifiers.
dateCreatedFrom and dateCreatedTo are required, with a maximum range of 100 days:
curl -i -X GET \
'https://pl-sandbox.api.acubeapi.com/legal-entities/{legalEntityUuid}/collective-identifiers?dateCreatedFrom=2026-07-01T00:00:00%2B00:00&dateCreatedTo=2026-07-31T23:59:59%2B00:00' \
-H 'Authorization: Bearer TOKEN'
{
"collectiveIdentifiers": [
{
"collectiveIdentifierNumber": "1111111111-IZ202607-65ED02180000-E7",
"dateCreated": "2026-07-10T10:00:00+00:00",
"createdInCurrentContext": true,
"invoiceCount": 2
}
],
"continuationToken": null
}
You can also filter by collectiveIdentifierNumber, by number of invoices with invoiceCountFrom and invoiceCountTo,
and with createdInCurrentContext=true keep only the ones created by the Legal Entity.
Look up the collective identifiers of an invoice
To find the collective identifiers including an invoice, for example, to check whether an invoice was already grouped, call
GET /legal-entities/{legalEntityUuid}/collective-identifiers/lookup/{ksefNumber}
with the KSeF number of the invoice:
curl -i -X GET \
'https://pl-sandbox.api.acubeapi.com/legal-entities/{legalEntityUuid}/collective-identifiers/lookup/1111111111-20260612-6310EC800000-DA' \
-H 'Authorization: Bearer TOKEN'
The response has the same structure as the list, but invoiceCount is null:
{
"collectiveIdentifiers": [
{
"collectiveIdentifierNumber": "1111111111-IZ202607-65ED02180000-E7",
"dateCreated": "2026-07-10T10:00:00+00:00",
"createdInCurrentContext": true,
"invoiceCount": null
}
],
"continuationToken": null
}
Pagination
Decode, list and look up return the results in pages:
- set the page size with
pageSize, from 10 (default) to 200, or to 500 when decoding; - when
continuationTokenis notnull, send it in theX-Continuation-Tokenheader to get the next page.