Skip to content

Exactly what the Avvio assistant answers for: - capacity: can the business pay amount currency now (balance, limits and the approval rule together, and by how much it falls short); - by-person: what each person was paid between from and to (YYYY-MM-DD, to included).

GET

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.

  • kindstringRequired
    Allowed values:capacityby-personchangesoutlook
    Show 8 more valuesbills-openpayments-recentpayments-torecipients-checkcurrenciesquotemonth-endschedules

Query parameters

  • amountstringOptional

    capacity: a decimal, e.g. 4250.00.

  • currencystringOptional

    capacity, currencies: ISO 4217.

  • fromstringOptional

    by-person: first day (YYYY-MM-DD). quote: the source currency (default USD).

  • tostringOptional

    by-person: last day, included (YYYY-MM-DD). quote: the payout currency.

  • receivebooleanOptional

    quote: amount is what the recipient gets.

  • daysintegerOptional

    changes (1-30, default 1) or outlook (1-90, default 14).

  • thisMonthbooleanOptional

    outlook: to the end of the calendar month.

  • monthstringOptional

    payments-recent: only payments paid (or prepared) in that month.

  • namestringOptional

    payments-to: the payee or vendor name.

Behavior

Never to an AI agent key (403); - changes: money in and payments out in the last days (1-30); - outlook: bills and scheduled payments due in the next days (1-90), or to the end of this month with thisMonth=true, against what is available; - bills-open: open bills and where each stands; - payments-recent: recent payments, optionally in one month; - payments-to: what was paid to name (a saved payee or an invoice's vendor); - recipients-check: saved recipients that need attention; - currencies: the currencies this business can pay out in, or for one currency the smallest and largest payment and the bank details to collect; - quote: an estimate for amount from from to to (receive=true when amount is what the recipient gets); - month-end: a month's payments, totals and per-payee split (month, YYYY-MM; default last month); - schedules: the scheduled payments. Parameters a kind does not take are refused.

Responses

200The insight, as the assistant reads it (beta; fields may be added).

Errors

  • 400

    VALIDATION_ERROR: a query parameter was refused, and errors names it. A limit outside its range is refused, not clamped; a cursor we did not issue for this organization is refused (start from the first page); an unknown filter value or a parameter sent twice is refused.

  • 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

    A valid key that may not make this call. Nothing ran.

    • FORBIDDEN: the key belongs to a different organization.
    • ACCOUNT_BLOCKED: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
  • 404

    No such insight.

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

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 getAssistantInsight

Try it: The assistant's read-only insights (beta)

GET https://api.avvio.xyz/business/api/v1/assistant/v1/{orgId}/insights/{kind}

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?