Uploading files

Overview

The Soldo Business API supports two distinct file upload flows:

• Document uploads — store files in a centralised document repository, independent of any specific transaction. Use this for identity documents, KYC materials, invoices, or any supporting evidence that belongs to your business account rather than a single spend event.
• Transaction attachments — link files (such as receipts or invoices) directly to a specific transaction. Use this when a file is evidence for a particular card spend.

Both flows share the same three-step pre-signed URL pattern, which keeps large file payloads off the Soldo API servers for better performance and security:

1. Request a short-lived, pre-signed upload URL from Soldo.
2. Upload the file directly to cloud storage using that URL — no Soldo auth headers needed for this step.
3. Confirm the upload so Soldo registers and indexes the file.

Required scopes

Make sure the application you created during API set-up has the relevant scope enabled. You can view and edit scopes from the Soldo web app under Integrations > Business API.

Uploading a document

Use the document upload flow when the file belongs to your business account rather than a single transaction — for example, an identity document submitted during onboarding, or an invoice you want to keep on record.

The upload targets /business/v2/documents/upload (Step 1) and /business/v2/documents/confirm (Step 3). After confirmation, Soldo returns a Document object containing a unique id you can use to retrieve or delete the file later.

Prerequisites: a valid OAuth2 access token with the document_write scope, the file you want to upload, and its MIME type (e.g. application/pdf) and extension (e.g. pdf).

Attaching a file to a transaction

Use the transaction attachment flow when a file is evidence for a specific card spend — for example, a receipt photo or a supplier invoice.

The upload targets /business/v1/transactions/{TRANSACTION_ID}/attachments/ (Steps 1 and 3). After confirmation the url_type field in the response changes from UPLOAD_URL to DOWNLOAD_URL, indicating the file is ready and linked to the transaction.

Prerequisites: a valid OAuth2 access token with the transaction_write scope, the ID of the transaction to attach the file to, and the file itself (e.g. a JPEG receipt or a PDF invoice).

Choosing the right flow

⚠️

Pre-signed upload URLs are short-lived. If you receive a 403 or other 4xx error during the cloud storage upload step, request a fresh pre-signed URL by repeating Step 1.