Attachments

A file field lets the data subject attach supporting documents (for example, proof of identity) when submitting a privacy request. This page covers both adding a file field to your intake form and enabling file uploads in your Fides deployment.

Add a file field

File fields accept two additional attributes beyond the common ones described in Configuration:

The supported file extensions are: pdf, doc, docx, txt, jpg, jpeg, png, xls, xlsx, csv, zip. Each extension is bound to a specific MIME type and a magic-byte signature; the upload endpoint verifies the file bytes against that signature rather than trusting the client-declared Content-Type or filename, so renaming a payload to .pdf does not bypass the allow-list.

"supporting_documents": {
  "label": "Supporting documents",
  "field_type": "file",
  "required": false,
  "max_size_bytes": 5242880,
  "allowed_file_types": ["pdf", "png", "jpg"]
}

Uploads are submitted to the public, rate-limited endpoint POST /api/v1/privacy-request/attachment. Each uploaded file is bound to the originating field and policy at upload time, and to the property when one is provided. If the privacy request is later submitted against a different action — or against a different property than the upload was scoped to — the upload is rejected and the attachment is cleaned up.

Example workflow

With the supporting_documents field configured above, attaching a file to a privacy request looks like this:

Data subject — Privacy Center

1. The data subject opens the Privacy Center and selects a privacy request type (for example, Access my data).
2. The intake form renders the Supporting documents field with a file picker. The picker lists the accepted extensions (pdf, png, jpg) and the maximum size (5 MiB).
3. The data subject selects a file. The Privacy Center uploads it immediately and shows the filename with a remove button once the upload is accepted.
   • If the file is too large, of a disallowed type, or flagged by the virus scanner, the form shows an inline error and the file is not attached.
4. The data subject completes the rest of the form and submits the request. The uploaded file is attached to that request.

Admin — Fides Admin UI

1. The new privacy request appears in the request manager queue.
2. Opening the request shows a Custom fields section containing the Supporting documents entry with a link to download the attached file.
3. The reviewer can download the attachment to verify identity (or whatever the field is collecting) before approving or denying the request.

How attachments work

When a data subject submits a privacy request with a file field, each attached file is:

1. Checked against the size limit and allowed file types you configured.
2. Scanned for viruses, if attachment_scanning.enabled is true.
3. Stored in your configured storage destination once it passes every check.

If a file fails any check, the upload is rejected and nothing is saved. Files that are uploaded but never submitted with a privacy request are cleaned up automatically.

Before you start

To enable file uploads you need:

• A storage destination (S3, GCS, or local for development).
• A virus scanner reachable from Fides (optional but strongly recommended). For Fides Cloud, Ethyca provides and manages this for you. For self-hosted deployments, run the clamav-icap container alongside your Fides worker, or set attachment_scanning.enabled = false to skip scanning.
• At least one file field declared in your Privacy Center's custom_privacy_request_fields.

Enable file uploads

To enable file uploads for privacy requests, please add the following section to your fides.toml file:

[attachment_scanning]
enabled = false
icap_host = "clamav-icap"
icap_port = 1344
icap_service = "avscan"
icap_timeout = 30
 
[execution]
allow_custom_privacy_request_field_collection = true
allow_custom_privacy_request_fields_in_request_execution = true
allow_custom_privacy_request_file_upload = true

execution.allow_custom_privacy_request_file_upload = true enables the POST /api/v1/privacy-request/attachment endpoint. Without it, the endpoint returns 403 Forbidden and the Privacy Center cannot upload files. The other two execution flags are also required so the file field is accepted on intake and passed through to request execution.

Set attachment_scanning.enabled to true once your scanner is reachable. Leave it false if you want to accept attachments without virus scanning — uploads still run size and file-type checks, but bypass the ICAP scanner. The other attachment_scanning values point Fides at your scanner — keep the defaults unless your scanner runs on a different host, port, or service path.

Attaching files via the API

If you submit privacy requests programmatically instead of through the Privacy Center, attaching a file is a two-step flow: upload the file to get an attachment id, then reference that id in the privacy request body.

The examples below assume the minimum configuration: file uploads are enabled in fides.toml (see Enable file uploads) and the Privacy Center declares a supporting_documents file field under the property FDS-A1B2C3 and policy default_access_policy:

"custom_privacy_request_fields": {
  "supporting_documents": {
    "label": "Supporting documents",
    "field_type": "file",
    "required": false,
    "max_size_bytes": 5242880,
    "allowed_file_types": ["pdf", "png", "jpg"]
  }
}

Step 1 — Upload the file

POST /api/v1/privacy-request/attachment is a public, rate-limited, multipart endpoint. No auth token is required.

curl -X POST "https://<your-fides-host>/api/v1/privacy-request/attachment" \
  -F "file=@./proof_of_identity.pdf" \
  -F "property_id=FDS-A1B2C3" \
  -F "policy_key=default_access_policy" \
  -F "field_name=supporting_documents"

A successful upload returns the attachment id:

{ "id": "att_01HXYZ..." }

policy_key and field_name are bound to the upload, and property_id is bound too when supplied — the privacy request that claims the upload must match all values that were set. If you omit property_id at upload time, the upload is not scoped to a property and can be claimed by a privacy request regardless of its property_id.

Step 2 — Submit the privacy request

POST /api/v1/privacy-request accepts a list of privacy requests. Pass the attachment id(s) returned from step 1 as the value of the matching custom_privacy_request_fields entry:

[
  {
    "identity": { "email": "user@example.com" },
    "policy_key": "default_access_policy",
    "property_id": "FDS-A1B2C3",
    "custom_privacy_request_fields": {
      "supporting_documents": {
        "label": "Supporting documents",
        "value": ["att_01HXYZ..."]
      }
    }
  }
]

The value is always a list, even when only one file was uploaded. If the upload context does not match the privacy request (different policy_key, different field_name, or a different property_id when one was set at upload time), the attachment is rejected and cleaned up.

Common error responses

Good to know

• Uploads fail safe. If the scanner is unreachable or a file looks suspicious, the upload is rejected and nothing is stored. Data subjects will see an error and can try again.
• Keep the scanner reachable. Because uploads are rejected when the scanner is down, monitor your scanner's health so privacy request submissions are not blocked.
• Storage permissions. The Fides worker needs both write and delete access to your storage destination so that unclaimed uploads can be cleaned up.