Create File Upload

POST/files/uploads

Summary

Creates a temporary upload link and a token for adding a file to a worker or invoice you can access. Upload the raw file bytes with PUT, then pass the token to the record's update endpoint. See File Uploads for the complete flow.

Query Parameters

Name	Type	Required	Description
agency	string	Conditional	Select the worker agency when the key has multiple agencies
company	string	No	Narrow the key's accessible hiring-company scope

Request Body

Field	Type	Required	Description
resource	string	Yes	invoice or worker
recordId	string	Yes	Existing record ID or nanoid
purpose	string	Yes	payment for invoices; attachments or rightToWork for workers
fileName	string	Yes	Original filename, including extension; 1–255 characters
contentType	string	Yes	application/pdf, image/jpeg, or image/png
size	integer	Yes	Raw file size in bytes, from 1 to 20,971,520

Request Example

curl -X POST 'https://api.requidex.com/api/open/v1/files/uploads' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"resource":"invoice","recordId":"<INVOICE_ID>","purpose":"payment","fileName":"remittance.pdf","contentType":"application/pdf","size":12345}'

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Upload instructions Show child attributes uploadUrl (string): temporary URL for uploading the file with PUT uploadToken (string): token bound to the caller, record, agency where applicable, and purpose method (string): PUT headers (object) Show child attributes Content-Type (string): required upload MIME type expiresIn (integer): validity in seconds; 900 (15 minutes)
meta	object	Empty metadata object

Upload exactly the declared number of bytes, with the returned Content-Type. Do not include your Requidex API key in this upload request.

curl -X PUT '<UPLOAD_URL>' \
  -H 'Content-Type: application/pdf' \
  --data-binary '@remittance.pdf'

After uploading, mark the invoice paid:

{
  "status": "paid",
  "paymentDate": "2026-10-12",
  "ref": "PAY-123",
  "file": { "uploadToken": "<UPLOAD_TOKEN>" }
}

The token expires after 15 minutes. The update endpoint rechecks access and validates the uploaded size, MIME type, and file signature. Issuing a URL or uploading the file does not attach the file to the record.

Errors

HTTP status	Description
400	Invalid metadata, purpose, or invoice status
401	Missing or invalid authentication
403	Missing resource-specific write scope, company-scoped worker key, or disabled agency action
404	Record or selected agency not found or inaccessible
429	Rate limit exceeded
500	Unable to create upload instructions