Skip to content

Send an invoice or bill (PDF, PNG or JPEG).

POST

Path parameters

  • orgIdstringRequired

    The opaque organization id issued to you, normally CUID-shaped (for example cmsx…). It is not an org_-prefixed alias. Pass it unchanged in every organization-scoped path.

Headers

  • Idempotency-KeystringOptional

    Same semantics as Idempotency-Key on the money routes (replay on the same body, 409 on a different one, released by a 4xx), but optional here: without it the request simply runs once with no replay. Every POST, PATCH and DELETE honors it; send one whenever your client might retry.

Body

This endpoint expects a JSON object.

  • filenamestringRequired
  • contentTypestringRequired
    Allowed values:application/pdfimage/pngimage/jpeg
  • dataBase64stringRequired

    The 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

  • idstringRequired

    The package id.

  • objectstringRequired
  • createdAtstring<date-time> | nullOptional
  • createdByobjectRequired
    Show 2 properties
    • apiKeyIdstringOptional
    • namestring | nullOptional
  • documentobjectOptional
    Show 1 property
    • filenamestring | nullOptional
  • approveUrlstring<uri>Required

    Where a person on your team reviews and approves it in Avvio. Send them here; this key cannot approve.

  • packageobjectRequired

    The prepared payment as Avvio shows it: status (ready once a person can approve it), bill, payee (account numbers masked to their last 4), checks, questions, and payoutId once sent. New fields are added without a major version.

Errors

  • 400

    Not a PDF, PNG or JPEG, empty, or over the page limit.

  • 401

    The 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.
  • 403

    INSUFFICIENT_SCOPE (the key lacks write or assistant), LIVE_KEY_REQUIRED (a test key), or API_KEY_REQUIRED (a dashboard session).

  • 409

    DUPLICATE_DOCUMENT: someone else already sent this file. Nothing new was created. Or an Idempotency-Key reused with a different body.

  • 429

    Too 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 same Idempotency-Key.

  • 503

    ASSISTANT_API_DISABLED: the Assistant API is not on for this organization.

Error body · Error
  • typestringRequired

    Stable machine-readable code.

  • detailstringRequired

    What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.

    More

    This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.

  • messagestringRequired

    The same text as detail, kept for integrations written before detail existed. Read detail.

  • resolutionstringOptional

    What 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_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.

  • statusintegerRequired

    HTTP status, repeated in the body.

  • statusCodeintegerRequired

    The same value as status, kept for integrations written before status existed. Read status.

  • requestIdstringRequired

    Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.

  • errorsarray of stringOptional

    Present on VALIDATION_ERROR; names each field that failed.

  • originalIdempotencyKeystringOptional

    On DUPLICATE_REQUEST_DETECTED only. 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.

  • originalPayoutIdstringOptional

    On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.

  • originalBatchIdstringOptional

    On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.

  • originalRequestIdstringOptional

    On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.

  • existingRecipientIdstringOptional

    On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.

  • existingMethodIdstringOptional

    On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

  • limitobjectOptional

    On PAYOUT_LIMIT_EXCEEDED from a payout. Which cap refused it and what is left of it.

    Show 8 properties
    • scopestringRequired

      organization: a cap on your whole organization (see limits on GET /policy). api_key: a cap on the key that made the call (apiKeyLimits).

      Allowed values:organizationapi_key
    • windowstringRequired

      single is one payout; daily and monthly are the UTC day and calendar month.

      Allowed values:singledailymonthly
    • capUsdstringRequired
    • usedUsdstring | nullRequired

      What already counts in this window. null for single. On the per-end-user cap, that end user's own volume.

    • remainingUsdstring | nullRequired

      capUsd - usedUsd, never below zero: the most a payout may be under this cap right now. null for single.

    • resetsAtstring<date-time> | nullRequired

      When the window starts over. null for single.

    • capstringOptional

      The cap's name as the message says it (single-payout, daily, daily per-end-user, monthly). Prose; branch on scope and window.

    • valueUsdstringOptional

      The 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.

Avvio Partner Payouts · Assistant · operation createAssistantDocument

Try it: Send an invoice to prepare

POST https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/documents

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

Was this page helpful?