Send an invoice to prepare
Send an invoice or bill (PDF, PNG or JPEG).
Path parameters
orgIdstringRequiredThe opaque organization id issued to you, normally CUID-shaped (for example
cmsx…). It is not anorg_-prefixed alias. Pass it unchanged in every organization-scoped path.
Headers
Idempotency-KeystringOptionalSame semantics as
Idempotency-Keyon the money routes (replay on the same body,409on a different one, released by a4xx), but optional here: without it the request simply runs once with no replay. EveryPOST,PATCHandDELETEhonors it; send one whenever your client might retry.
Body
This endpoint expects a JSON object.
filenamestringRequiredcontentTypestringRequiredAllowed values:application/pdfimage/pngimage/jpegdataBase64stringRequiredThe file, base64. The request body is capped at 10 MB, so about 7 MB of file.
Behavior
Avvio reads it, matches the payee, runs the same checks as the dashboard, and prepares the payment.
Nothing is paid from this API. A person on your team reviews and
approves the package in Avvio, at approveUrl, with their own sign-in.
There is no approve or send endpoint.
Needs a live key with scopes ["write", "assistant"]. At most two
documents per key at once (429 TOO_MANY_IN_FLIGHT). Sending the same
file again from the same key returns the same package.
Responses
201The package. Usually status is still a hold while the document is read; poll the package or subscribe to assistant_package.ready.
Body · AssistantPackage
idstringRequiredThe package id.
objectstringRequiredcreatedAtstring<date-time> | nullOptionalcreatedByobjectRequiredShow 2 properties
apiKeyIdstringOptionalnamestring | nullOptional
documentobjectOptionalShow 1 property
filenamestring | nullOptional
approveUrlstring<uri>RequiredWhere a person on your team reviews and approves it in Avvio. Send them here; this key cannot approve.
packageobjectRequiredThe prepared payment as Avvio shows it:
status(readyonce a person can approve it),bill,payee(account numbers masked to their last 4),checks,questions, andpayoutIdonce sent. New fields are added without a major version.
Errors
400Not a PDF, PNG or JPEG, empty, or over the page limit.
401The key was refused. Nothing ran.
UNAUTHORIZED: missing, invalid or revoked, or a key on a route that does not accept one.KEY_EXPIRED: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated.KEY_IP_NOT_ALLOWED: the key is pinned to source addresses and this request came from another.
403INSUFFICIENT_SCOPE(the key lackswriteorassistant),LIVE_KEY_REQUIRED(a test key), orAPI_KEY_REQUIRED(a dashboard session).409DUPLICATE_DOCUMENT: someone else already sent this file. Nothing new was created. Or anIdempotency-Keyreused with a different body.429Too many requests. The default ceiling is 100 requests per minute per API credential on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies.
Obey
Retry-After; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its sameIdempotency-Key.503ASSISTANT_API_DISABLED: the Assistant API is not on for this organization.
Error body · Error
typestringRequiredStable machine-readable code.
detailstringRequiredWhat went wrong, in a sentence. Always a string, so
detail.toLowerCase()is safe.More
This is the field to read on
BAD_REQUESTandPROVIDER_REJECTED, where the type alone does not name the condition.messagestringRequiredThe same text as
detail, kept for integrations written beforedetailexisted. Readdetail.resolutionstringOptionalWhat to do about it, when there is a specific answer. It is not on every error (it is absent on
BAD_REQUEST,NOT_FOUND,PAYOUT_NOT_CANCELABLEandDESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back todetail.statusintegerRequiredHTTP status, repeated in the body.
statusCodeintegerRequiredThe same value as
status, kept for integrations written beforestatusexisted. Readstatus.requestIdstringRequiredQuote this to support and we can find the exact request. Also sent as the
x-request-idresponse header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your ownx-request-idon the request and we use it, so your trace and ours share one identifier; otherwise we mint one.errorsarray of stringOptionalPresent on VALIDATION_ERROR; names each field that failed.
originalIdempotencyKeystringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.originalPayoutIdstringOptionalOn
DUPLICATE_REQUEST_DETECTEDonly. The payout the first request created.originalBatchIdstringOptionalOn a batch
DUPLICATE_REQUEST_DETECTED. The run the first request created.originalRequestIdstringOptionalOn a
409 PAYOUT_OUTCOME_UNKNOWNreplay. TherequestIdof the call whose outcome is unknown; quote it to support.existingRecipientIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.existingMethodIdstringOptionalOn
BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.limitobjectOptionalOn
PAYOUT_LIMIT_EXCEEDEDfrom a payout. Which cap refused it and what is left of it.Show 8 properties
scopestringRequiredorganization: a cap on your whole organization (seelimitsonGET /policy).api_key: a cap on the key that made the call (apiKeyLimits).Allowed values:organizationapi_keywindowstringRequiredsingleis one payout;dailyandmonthlyare the UTC day and calendar month.Allowed values:singledailymonthlycapUsdstringRequiredusedUsdstring | nullRequiredWhat already counts in this window.
nullforsingle. On the per-end-user cap, that end user's own volume.remainingUsdstring | nullRequiredcapUsd - usedUsd, never below zero: the most a payout may be under this cap right now.nullforsingle.resetsAtstring<date-time> | nullRequiredWhen the window starts over.
nullforsingle.capstringOptionalThe cap's name as the message says it (
single-payout,daily,daily per-end-user,monthly). Prose; branch onscopeandwindow.valueUsdstringOptionalThe same value as
capUsd.
Branch on type, never on the status or the message. Every error type is listed with what to do about it.
Was this page helpful?