List open uploads
AWAITING_UPLOAD, PENDING or RUNNING), with its scope, parameters and — while awaiting files — its current upload URL:
FAILED while its run is still open on our side — report it to us with its upload_id. Note that we are notified of failures automatically, so we may already be looking into it.
Get one upload
404 (UPLOAD_NOT_FOUND), just like they disappear from the list.
Cancel an open upload
Discards the uploaded files and releases the upload, for example to restart with different parameters:404 (UPLOAD_NOT_FOUND). Cancelling an upload that was already submitted returns 409 Conflict (UPLOAD_NOT_AWAITING) — at that point the batch is being processed and can no longer be cancelled.
File conventions
- Place each file in a subfolder named after its endpoint type, one level below the upload directory root (for example
{UPLOAD_URL}/invoices/...). - All files in such a subfolder share the data format agreed with aiGust for that endpoint type. That format is bespoke: it is discussed and settled with us before you start (see Upload data as an integration partner).
- Files placed directly in the root of the upload directory are ignored — they belong to no endpoint type.
Caveats and limitations
- One open upload per scope. A scope is either the whole connector or a single
administration_code. Multiple administrations can have an open upload at the same time, but a connector-wide upload blocks all administration-scoped ones — and vice versa. - No new upload while a previous one is processing. After you submit, the upload is processed (
PENDING/RUNNINGin the upload list) and overlappingcreatecalls are rejected with409 Conflictuntil it finishes. Poll the upload list to know when you can open the next batch. - Parameters are locked while an upload is open. Calling
createwith a differentadministration_codeorfull_uploadthan the open batch returns409 Conflict— submit or cancel the open upload first. - Administrations must be active. Creating an upload for an unknown or inactive administration fails (
404/400— see errors). Deactivating an administration after opening its upload makes its submit fail the same way. - New administrations require a connector-wide upload. Administration discovery happens on connector-wide uploads (no
administration_code). An administration-scoped upload can only target an existing administration — a brand-new code fails with404. To onboard a new administration, open a connector-wide upload first; afterwards it can be synced scoped. - Submit within 2 days. An upload that is never submitted is cancelled automatically roughly 2 days after creation and its files are deleted. Check
expires_atfor the upload URL’s expiry. - Submitting is final. Finish uploading and finalizing all files before submit. The URL may still work afterwards, but you must stop using it. During processing, aiGust takes a separate copy of the batch; later uploads do not update that copy. Create a new upload for additional data.
- Automatic processing only covers connector-wide uploads. If enabled for your connector, the daily schedule processes existing open connector-wide uploads. Uploads for a single administration must always be submitted manually. The schedule does not create uploads or retry previously submitted runs.
- Follow the agreed data format. The uploader is responsible for the uploaded data. Empty uploads follow the normal processing flow and may fail; they are not automatically skipped or marked successful.
Errors
All endpoints return a JSON error body, in one of two shapes:401 — authentication
Example:{ "detail": "Access token expired" }. Your token is expired or invalid — request a new one and retry the call.
403 — forbidden
Your credentials are valid but not authorized for this call. The provisioned credentials only work for your own connector — using them with another connector id (even within the same firm) returns 403.404 — not found
- Without a
code: the tenant or connector id is unknown to us. ADMINISTRATION_NOT_FOUND— theadministration_codedoes not exist on this connector.UPLOAD_NOT_FOUND— theupload_iddoes not exist on this connector (or the upload is already processed, on the get-by-id endpoint).
400 — bad request
- Without a
code: the action is not supported for this connector — theupload/*endpoints are only available on external-upload connectors. ADMINISTRATION_NOT_SYNCABLE— the administration exists but is not active for syncing (for example deactivated); the message includes its current status.NO_SYNCABLE_ADMINISTRATIONS— the connector has no active, syncable administrations.
409 — conflict
- Without a
codeoncreate: an upload is already open for an overlapping scope — submit or cancel it first; the message describes the conflict. UPLOAD_NOT_AWAITING— the upload exists but is no longer awaiting files (it was already submitted and is pending, running or processed). The message includes the current state. Submitting or cancelling is only possible while an upload awaits files; request a new upload URL once processing has finished.OPEN_SYNC_EXISTS— a sync is currently running or pending for this connector; a new upload can be opened once it finishes.ADMINISTRATIONS_LOCKED— one or more administrations are locked by a running sync; retry shortly.
500 — server error
Something went wrong on our side (for example the upload storage is unreachable). Retry later, check the platform status, or contact us; theupload_id helps us investigate.
Security notes
- The upload URL is write-only: you cannot read, list, or delete anything.
- Your client credentials are scoped to your connector only — they cannot read or modify any other connector, and all calls outside the
upload/*lifecycle are rejected. - Keep the Client Secret and upload URLs confidential — they grant write access.
- Stop using an upload URL after submit or cancel, even if it still accepts files.
- Contact us to revoke API access. Already-issued upload URLs can remain valid until their own
expires_at, even after API access is revoked.