Configuration
Upload a File
Upload KYC/KYB identity documents or invoice files to VelaFi. Supports up to 5 files per request in JPG, PNG, JPEG, or PDF format.
POST
/
v2
/
base
/
file
/
upload
Upload a File
curl --request POST \
--url https://api-test.velafi.com/v2/base/file/upload \
--header 'Content-Type: multipart/form-data' \
--header 'X-BH-TOKEN: <api-key>' \
--form 'businessType=<string>' \
--form files=@example-fileimport requests
url = "https://api-test.velafi.com/v2/base/file/upload"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = { "businessType": "<string>" }
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('businessType', '<string>');
form.append('files', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {'X-BH-TOKEN': '<api-key>'}};
options.body = form;
fetch('https://api-test.velafi.com/v2/base/file/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/base/file/upload")
.header("X-BH-TOKEN", "<api-key>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"businessType\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();{
"code": 123,
"msg": "<string>",
"data": [
{
"fileName": "<string>",
"fileType": "<string>",
"fileUrl": "<string>",
"tempFileUrl": "<string>"
}
]
}Use the POST
/v2/base/file/upload endpoint to upload documents to VelaFi. This endpoint supports KYC/KYB identity verification files as well as invoice documents for merchant accounts. The request must be sent as multipart/form-data. You can upload up to five files in a single request; each file must be between 10 KB and 3 MB and in one of the supported formats. The response returns a temporary signed URL for each uploaded file so you can verify the upload succeeded before referencing the file in subsequent API calls.
This endpoint requires authorization. Include your
X-BH-TOKEN header on every request. Requests without a valid token will be rejected.Request
POST /v2/base/file/upload
Headers
| Header | Value | Required |
|---|---|---|
X-BH-TOKEN | Your token from GET /v2/token/generate | ✓ |
Content-Type | multipart/form-data | ✓ |
Body Parameters
string
required
The type of business document being uploaded. Currently fixed to
FIAT_ACCOUNT.file
required
One or more files to upload. Maximum 5 files per request. Each file must be between 10 KB and 3 MB. Supported formats:
jpg, jpeg, png, pdf.Response Fields
number
HTTP-style status code.
200 indicates success.string
Human-readable status message, e.g.
"SUCCESS".array
Array of uploaded file objects, one entry per file.
Show data[]
Show data[]
string
Original filename as provided in the upload (e.g.,
"id-front.jpg").string
File extension of the uploaded document (e.g.,
"jpg", "pdf").string
Relative storage path for the file (e.g.,
"100001/00000000-0000-0000-0000-000000000001.jpg"). Use this value when referencing the file in subsequent API calls, for example the document fields (govIdFrontUrl, govIdBackUrl, certificateOfIncorporationDocumentUrl, taxIdentificationDocumentUrl) of a Pix - Woovi channel activation.string
Temporary pre-signed URL you can use to verify the file was uploaded correctly. This URL expires 30 minutes after the upload and should not be stored permanently.
Example
curl --request POST \
--url 'https://api.velafi.com/v2/base/file/upload' \
--header 'X-BH-TOKEN: YOUR_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--form 'businessType=FIAT_ACCOUNT' \
--form 'files=@/path/to/id-front.jpg'
curl --request POST \
--url 'https://api.velafi.com/v2/base/file/upload' \
--header 'X-BH-TOKEN: YOUR_TOKEN' \
--header 'Content-Type: multipart/form-data' \
--form 'businessType=FIAT_ACCOUNT' \
--form 'files=@/path/to/id-front.jpg' \
--form 'files=@/path/to/id-back.jpg'
Response
{
"code": 200,
"msg": "SUCCESS",
"data": [
{
"fileName": "id-front.jpg",
"fileType": "jpg",
"fileUrl": "100001/00000000-0000-0000-0000-000000000001.jpg",
"tempFileUrl": "https://example-bucket.s3.amazonaws.com/00000000-0000-0000-0000-000000000001.jpg?X-Amz-Signature=..."
}
]
}
Store the
fileUrl field from the response — this is the permanent relative path you reference in KYC/KYB submission requests. The tempFileUrl is a short-lived signed URL for verification only and will expire.Was this page helpful?
⌘I
Upload a File
curl --request POST \
--url https://api-test.velafi.com/v2/base/file/upload \
--header 'Content-Type: multipart/form-data' \
--header 'X-BH-TOKEN: <api-key>' \
--form 'businessType=<string>' \
--form files=@example-fileimport requests
url = "https://api-test.velafi.com/v2/base/file/upload"
files = { "files": ("example-file", open("example-file", "rb")) }
payload = { "businessType": "<string>" }
headers = {"X-BH-TOKEN": "<api-key>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('businessType', '<string>');
form.append('files', '{
"fileName": "example-file"
}');
const options = {method: 'POST', headers: {'X-BH-TOKEN': '<api-key>'}};
options.body = form;
fetch('https://api-test.velafi.com/v2/base/file/upload', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/base/file/upload")
.header("X-BH-TOKEN", "<api-key>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"businessType\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
.asString();{
"code": 123,
"msg": "<string>",
"data": [
{
"fileName": "<string>",
"fileType": "<string>",
"fileUrl": "<string>",
"tempFileUrl": "<string>"
}
]
}