Buvei
API ReferenceKYC

Upload KYC File

Request a presigned URL and upload a KYC document.

POST/open-api/v1/kyc/presignedUploads

KYC documents are uploaded in two steps:

  1. Request an upload URL from this endpoint.
  2. PUT the file directly to that URL.

This pattern keeps document bytes out of our API tier — your file goes straight to cloud storage. The presigned URL carries its own authorisation, so you never need cloud-storage credentials.

Body

fileNamestringbodyrequired

Original file name (max 128 chars), e.g. passport.png.

contentTypestringbodyrequired

MIME type. Allowed: image/png, image/jpeg, application/pdf.

typestringbodyrequired

Document category: IDENTITY_PROOF, SELFIE_PROOF, or ADDRESS_PROOF.

Response

uploadUrlstring

Temporary upload URL. PUT your file here (see below). Expires after expiresIn seconds.

fileTokenstring

File reference token. Save this — you'll pass it in the attachments array on POST /kyc/cardholders/manual.

expiresIninteger

Seconds the uploadUrl remains valid. Default 600 (10 minutes).

Request
{
  "fileName": "passport.png",
  "contentType": "image/png",
  "type": "IDENTITY_PROOF"
}
Response
{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "uploadUrl": "https://s3.amazonaws.com/...&X-Amz-Signature=...",
    "fileToken": "kyc_file_8f3a9c2b1d4e5f6a",
    "expiresIn": 600
  }
}

Step 2 — upload the file

curl -X PUT "https://s3.amazonaws.com/...&X-Amz-Signature=..." \
  -H "Content-Type: image/png" \
  --data-binary @passport.png

The Content-Type header on the PUT must exactly match the contentType you sent to this endpoint. Do not send your X-API-Key / signature headers — the URL itself is the authorisation.

Notes

  • Each uploadUrl is single-use. Request a new one if it expires.
  • Each fileToken is single-use — consumed when you submit it in a manual KYC request.
  • Maximum file size: 10 MB.

On this page

Body
Response
Step 2 — upload the file
Notes