Skip to main content

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.

note

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.

note

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

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
}
  • invoiceUuid is the invoice in A-Cube, null when the invoice is not stored for this Legal Entity.
  • payment is the payment details provided when creating the collective identifier, null if it was not provided.
  • description is the description provided when creating the collective identifier, null if it was not provided.
  • detailsHidden is true when 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 continuationToken is not null, send it in the X-Continuation-Token header to get the next page.