---
title: "Submit a proof of address for a customer (via document upload)"
method: POST
path: "/v1/headless_kyc/proof_of_address/upload"
tags: ["Headless KYC"]
---

# Submit a proof of address for a customer (via document upload)

`POST /v1/headless_kyc/proof_of_address/upload`

## Request

- Base URL: `https://api.breeze.cash`
- URL: `https://api.breeze.cash/v1/headless_kyc/proof_of_address/upload`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/breeze/apis/breeze-api/docs/v1/headless_kyc/proof_of_address/upload/post.ts> (a function with typed inputs; its response is checked against the schema)

Submits a proof-of-address document for a customer who has already been submitted for KYC.

The document is the only data to supply: the name and address sent for verification are read back from the customer's earlier KYC submission. Supplementary documentation does not change the customer's KYC status, and it does not create or advance a KYC request, so the response carries no identifier of its own — track the submission by the `customerReferenceId` you submitted under.

**One document per submission.** If the proof spans several pages or images, combine them into a single file (for example a multi-page PDF) before submitting. Submitting again does not add a page to the previous document — it sends a separate document for review.

**Note:** This endpoint is only available to merchants configured by the Breeze team. Please reach out to the Breeze team to find out more.

To reference a document you host instead, use the `Submit a proof of address for a customer (via document URL)` endpoint.

## Headers

- `Content-Type` string
- `Accept` string

## Request body `multipart/form-data`

- SubmitHeadlessKycProofOfAddressWithUploadRequest: Upload the proof-of-address document as a file. The JSON payload must be serialized as a JSON string in the `data` form field.
  - `data` object, required: Must be serialized as a JSON string.
    - `customerReferenceId` string, required
  - `document` string, binary, required: Proof-of-address document file. Supported formats: JPEG, PNG, HEIC, PDF. Exactly one file per submission — combine multi-page proof into a single file.

## Response `200`

Success

- object: The accepted proof of address submission
  - `status` 'SUCCEEDED', required
  - `data` SubmitHeadlessKycProofOfAddressWithUploadResponse, required: Response for both proof-of-address submission endpoints. A proof-of-address submission is supplementary documentation: it does not create or advance a KYC request, and it never changes the customer's KYC status. It therefore has no identifier of its own to return — the customer reference the merchant submitted under is the handle, and the headless KYC request id is deliberately NOT echoed, since nothing about that request changed.
    - `customerReferenceId` string, required
    - `submittedAt` number, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized

## Changes

- **2026-11-03** `4af083d182a6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/breeze/apis/breeze-api/changes/v1/headless_kyc/proof_of_address/upload/post.md)

---

[API](https://skmtc.dev/breeze/apis/breeze-api.md) - [All operations](https://skmtc.dev/breeze/apis/breeze-api/llms.txt) - [OpenAPI document](https://skmtc.dev/breeze/apis/breeze-api/revisions/4af083d182a6?raw)