> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codaclean.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Download CODB files

> List new payroll files, download them, and acknowledge each download.

CODB files are payroll files that payroll providers (social secretariats) deliver to Codaclean for your customers.

The flow is the same as for CODA files. Files arrive in the morning: running it twice a day is enough.

<Steps>
  <Step title="List new files">
    Call [`POST /codb-files`](/api/endpoints/list-codb-files) with a JSON body, at least `{}`.

    By default, the response only contains files you have not acknowledged yet.

    Files are grouped by customer, then by payroll provider and year.

    Useful filters: `enterpriseNumber`, `payrollProvider`, `accountPeriod`, `statementDate`, `processingDate`, `statementNumber`.

    Set `includePdf` to `true` to also get the PDF version of each file.

    **Required scope:** `files:read`
  </Step>

  <Step title="Download each file">
    Each file has a `urls.codb` link (and `urls.pdf` when requested).

    These are pre-signed URLs: download them with a plain `GET`, without the API headers.

    <Warning>
      Download URLs expire **30 minutes** after the list call. If a URL has expired, list the files again to get a fresh one.
    </Warning>
  </Step>

  <Step title="Acknowledge each download">
    Once a file is stored on your side, call [`DELETE /codb-files/{fileId}`](/api/endpoints/acknowledge-codb-file) with the file's `id`.

    The file is **not** deleted. It is marked as downloaded for your API key and the current user, and no longer appears in the next list.

    Acknowledging the same file twice returns `409`.
  </Step>
</Steps>

## Download a file again

To list files that were already acknowledged, send `"redownload": true`.

## Good to know

* In CODB responses, `statementDate` is the generation date of the file and `statementNumber` its sequence number.
* `statementNumber` is a string. It is usually numeric, but it can combine several sequence numbers (for example `"0103-0203"`): do not convert it to a number.
* `accountPeriod` is an integer, as `YYYYMM` (for example `202609`).
* The list is not paginated. Acknowledge files as you go to keep responses small.
* Acknowledgements are per API key and per user.