# `Codat.Platform.Files`
[🔗](https://github.com/iamkanishka/codat.git/blob/v1.0.0/lib/codat/platform/files.ex#L1)

Upload and retrieve business documents (files) for a company.

The Files API lets you store supporting documents alongside financial data —
bank statements, invoices, receipts, tax returns, etc.

## Supported File Types

Codat accepts PDFs, images (PNG, JPEG), and Excel files. Each file is associated
with a company and optionally tagged with a date range.

## Example

    # Upload a PDF bank statement
    file_data = File.read!("statement.pdf")
    {:ok, _} = Codat.Platform.Files.upload(client, "company-id", file_data, "application/pdf")

    # List all uploaded files
    {:ok, files} = Codat.Platform.Files.list(client, "company-id")

    # Download a specific file
    {:ok, content} = Codat.Platform.Files.download(client, "company-id", "file-id")

# `download`

```elixir
@spec download(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, binary() | map() | list() | nil} | {:error, Codat.Error.t()}
```

Downloads a file's contents by its file ID.

Returns the raw binary content.

## Example

    {:ok, binary} = Codat.Platform.Files.download(client, "company-id", "file-id")
    File.write!("downloaded.pdf", binary)

# `download_all`

```elixir
@spec download_all(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, binary() | map() | list() | nil} | {:error, Codat.Error.t()}
```

Downloads all files for a company as a ZIP archive.

## Example

    {:ok, zip_bytes} = Codat.Platform.Files.download_all(client, "company-id")
    File.write!("company-docs.zip", zip_bytes)

# `list`

```elixir
@spec list(Codat.Client.t() | String.t(), String.t() | keyword()) ::
  {:ok, [map()]} | {:error, Codat.Error.t()}
```

Lists all files uploaded for a company.

## Example

    {:ok, files} = Codat.Platform.Files.list(client, "company-id")
    # => [%{"fileId" => "...", "fileName" => "statement.pdf", ...}]

# `upload`

```elixir
@spec upload(
  Codat.Client.t() | String.t(),
  String.t(),
  binary(),
  String.t(),
  keyword()
) ::
  {:ok, map()} | {:error, Codat.Error.t()}
```

Uploads a file for a company.

## Parameters

- `company_id` — the company to attach the file to
- `file_data` — binary file contents
- `content_type` — MIME type (e.g. `"application/pdf"`, `"image/jpeg"`)

## Options

- `:file_name` — override the filename (default: `"upload"`)

## Example

    pdf = File.read!("statement.pdf")
    {:ok, _} = Codat.Platform.Files.upload(client, "company-id", pdf, "application/pdf",
      file_name: "jan-2024-statement.pdf"
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*