# KYC document uploads

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/kyc-document-uploads
Upload, confirm, list, download, and delete KYC documents through the DALP API and SDK.



KYC document uploads use a two-step file flow. Your integration first requests an
upload URL for a draft KYC version, uploads the file to that URL, and then
confirms the upload in DALP so the document is attached to the KYC version.

Use this flow when investors or operators need to attach passports, identity
cards, proof-of-address files, or other supporting evidence to a KYC submission.
The document record belongs to a KYC version, not directly to the user profile.
Submit the version only after the required profile fields and documents are in
place.

## Supported document inputs [#supported-document-inputs]

A document upload requires:

* `versionId`: the KYC version that receives the document
* `documentType`: one of `passport`, `drivers_license`, `national_id`,
  `proof_of_address`, or `other`
* `fileName`: the original file name you want stored with the document record
* `fileSize`: file size in bytes, up to 10 MiB
* `mimeType`: one of `application/pdf`, `image/jpeg`, `image/png`, or
  `image/webp`

If the latest KYC version is already submitted or under review, create a new
draft version before requesting an upload URL.

## Upload flow [#upload-flow]

The upload flow has three calls:

1. Request an upload URL with `user.kyc.documents.getUploadUrl`.
2. Upload the file bytes to the returned `uploadUrl` using the returned HTTP
   method.
3. Confirm the upload with `user.kyc.documents.confirmUpload` and the returned
   `objectKey`.

Use the returned method and headers for the file upload. Some storage backends
include provider-specific headers in the upload URL response.

```ts
const upload = await client.user.kyc.documents.getUploadUrl({
  params: { versionId: "ver_123" },
  body: {
    documentType: "passport",
    fileName: "passport.pdf",
    fileSize: 204800,
    mimeType: "application/pdf",
  },
});

await fetch(upload.data.uploadUrl, {
  method: upload.data.method,
  headers: upload.data.headers,
  body: passportBytes,
});

const document = await client.user.kyc.documents.confirmUpload({
  params: { versionId: "ver_123" },
  body: {
    objectKey: upload.data.objectKey,
    documentType: "passport",
    fileName: "passport.pdf",
    fileSize: 204800,
    mimeType: "application/pdf",
  },
});
```

The confirmation call creates the DALP document record. Until confirmation
succeeds, the uploaded object should not be treated as part of the KYC version.

## List documents [#list-documents]

Use `user.kyc.documents.list` to read documents attached to a KYC version.
Filters can narrow the result set, for example to one document type.

```ts
const documents = await client.user.kyc.documents.list({
  params: { versionId: "ver_123" },
  query: {
    filters: [{ id: "documentType", operator: "eq", value: "passport" }],
  },
});
```

The response includes paginated document records and metadata, so integrations
can build review screens without fetching every document at once.

## Download a document [#download-a-document]

Use `user.kyc.documents.getDownloadUrl` with the KYC version and document ID.
DALP returns a download URL plus document metadata such as the file name and MIME
type.

```ts
const download = await client.user.kyc.documents.getDownloadUrl({
  params: {
    versionId: "ver_123",
    documentId: document.data.id,
  },
});
```

Use the returned URL to retrieve the file. Do not persist the URL as a permanent
file reference; request a fresh download URL when an operator needs to view or
process the document.

## Delete a document [#delete-a-document]

Use `user.kyc.documents.delete` when an uploaded document was attached to the
wrong version, has the wrong type, or needs to be replaced before submission.

```ts
await client.user.kyc.documents.delete({
  params: {
    versionId: "ver_123",
    documentId: document.data.id,
  },
});
```

Deleting a document removes the DALP document record from that KYC version. It
does not approve, reject, or submit the KYC version.

## CLI equivalents [#cli-equivalents]

The DALP CLI exposes the same flow for operator scripts:

* `kyc document-upload-url`
* `kyc document-confirm-upload`
* `kyc documents`
* `kyc document-download-url`
* `kyc document-delete`

Use the CLI commands for back-office scripts and the SDK calls for application
integrations. Both paths follow the same model: request an upload URL, upload the
file, confirm the object key, then manage the document record on the KYC version.

## Related [#related]

* [Developer guides](/docs/developer-guides)
* [Compliance provider subjects](/docs/developer-guides/compliance/compliance-provider-subjects)