Skip to main content
POST
/
v1
/
payout-api
/
payouts
/
documents
/
upload-url
Get presigned URL to upload supporting document
curl --request POST \
  --url https://gateway.useyala.com/v1/payout-api/payouts/documents/upload-url \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filename": "invoice.pdf",
  "contentType": "application/pdf"
}
'

​
Overview

Returns a presigned PUT URL so your server can upload an invoice directly to Yala’s private S3 bucket. Yala does not accept file bytes on this endpoint—only metadata (filename, contentType). After uploading to S3, use the returned documentUrl on:
  • POST /initiate as supportingDocument, or
  • PATCH /:id/documents in the documents array
Read Uploading Supporting Documents for the full 3-step flow: call Yala, upload to S3, then call Yala again with documentUrl.

​
Upload flow (3 steps)

StepWhereAction
1Yala APIPOST /documents/upload-url returns uploadUrl and documentUrl
2Amazon S3PUT file bytes to uploadUrl (not Yala)
3Yala APIPOST /initiate or PATCH /:id/documents with documentUrl

​
Request

POST /v1/payout-api/payouts/documents/upload-url HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

{
  "filename": "invoice.pdf",
  "contentType": "application/pdf"
}

​
Request Fields

FieldTypeRequiredDescription
filenamestringYesOriginal filename (basename only, e.g. invoice.pdf)
contentTypestringYesMIME type: application/pdf, image/jpeg, image/jpg, or image/png

​
Response

{
  "documentId": "550e8400-e29b-41d4-a716-446655440000",
  "uploadUrl": "https://yala-payout-api-docs-staging.s3.us-east-1.amazonaws.com/staging/payout-api/.../invoice.pdf?X-Amz-Algorithm=...",
  "documentUrl": "https://yala-payout-api-docs-staging.s3.us-east-1.amazonaws.com/staging/payout-api/<businessId>/<documentId>/invoice.pdf",
  "expiresAt": "2024-01-20T10:15:00.000Z",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf"
  }
}

​
Response Fields

FieldTypeDescription
documentIdstring (UUID)Document identifier (embedded in S3 key)
uploadUrlstringPresigned URL for one-time PUT to S3 (~15 min TTL)
documentUrlstringStable HTTPS URL — pass this to initiate/PATCH after upload succeeds
expiresAtstring (ISO 8601)When uploadUrl expires
methodstringAlways PUT
headersobjectHeaders required on the PUT request (e.g. Content-Type)

​
Upload the file to S3

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

const { uploadUrl, documentUrl, headers } = await uploadUrlResponse.json();
const file = await fs.readFile('invoice.pdf');

const putResult = await fetch(uploadUrl, {
  method: 'PUT',
  headers,
  body: file,
});

if (!putResult.ok) {
  throw new Error('S3 upload failed');
}

// Use documentUrl on initiate or PATCH — not uploadUrl
For manual testing, use the Postman collection Upload File to S3 request.

​
Error Responses

​
400 Bad Request

Invalid filename or unsupported contentType.

​
401 Unauthorized

Invalid or missing API key.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
filename
string
required
Example:

"invoice.pdf"

​
contentType
string
required
Example:

"application/pdf"

Response

Presigned upload URL created