Choose where deposits go
Sets the ad account deposits go to: one of the targets of GET /v1/ad-account-funding, a USD ad account of one of the organization's shared requests. Deposits that were waiting for a choice are added to it at once. Returns the funding details. Refusals: 400 validation_failed on adAccountId for an ad account the request does not hold or one not in USD, 404 for another organization's request, 409 conflict before the request's ad account is shared.
bearerAuthAuthorizationBearer <token>An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.
application/json- body
requestId*stringThe ad account request id, or its Koast reference (KST-…).
1 <= length <= 40adAccountId*stringThe ad account deposits go to, act_…: one of the targets of the funding details.
1 <= length <= 40Choose where deposits go
application/json- response
bank*|Where to send a US bank transfer in USD: ACH, wire or RTP. Null while bank transfers are not offered.
crypto*array<>One deposit address per stablecoin and network. Only that coin on that network may be sent to it: another coin or network can be lost for good. Empty while crypto is not offered.
target*|The ad account deposits go to. Null until one is chosen, when the organization has more than one.
targets*array<>The ad accounts deposits can go to: the organization's shared USD ad accounts.
minimumCents*integerThe smallest budget, in USD cents, a deposit is added for without Koast checking it first.
-9007199254740991 <= value <= 9007199254740991onHold*booleanTrue while deposits and payments for funds are on hold for the organization. The user contacts Koast support.
deposits*array<>The latest deposits, newest first.
balances*array<>What each of the organization's shared ad accounts has left to spend.
curl -X PUT "https://example.com/v1/ad-account-funding/target" \ -H "Authorization: Bearer koast_sk_..." \ -H "Content-Type: application/json" \ -d '{ "requestId": "string", "adAccountId": "string" }'{ "bank": { "accountName": "string", "accountNumber": "string", "routingNumber": "string" }, "crypto": [ { "currency": "string", "network": "string", "address": "string", "memo": "string" } ], "target": { "requestId": "string", "reference": "string", "adAccountId": "string", "name": "string" }, "targets": [ { "requestId": "string", "reference": "string", "adAccountId": "string", "name": "string" } ], "minimumCents": -9007199254740991, "onHold": true, "deposits": [ { "id": "string", "status": "pending", "heldReason": "no_ad_account", "rail": "ach", "receivedCents": -9007199254740991, "currency": "string", "budgetCents": -9007199254740991, "adAccountId": "string", "createdAt": "string", "creditedAt": "string" } ], "balances": [ { "requestId": "string", "adAccountId": "string", "name": "string", "status": "string", "currency": "string", "budgetCents": -9007199254740991, "spentCents": -9007199254740991, "leftToSpendCents": -9007199254740991, "spentYesterdayCents": -9007199254740991, "runwayDays": -9007199254740991, "readAt": "string", "low": true } ]}Required scope: write. CLI: koast set-ad-account-funding-target, see Ad Account Funding commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.
Get ad account funding details
Returns the organization's funding details, opened the first time they are read once one of its ad accounts is shared into its Business Manager. Bank transfers (ACH, wire, RTP) and stablecoins sent to them are added to the chosen ad account as they land, less Koast's fee and the platform location fee: there is no payment page and no amount to announce first. With one shared USD ad account deposits go to it; with more, choose one with PUT /v1/ad-account-funding/target, and deposits wait until then. balances gives each shared ad account's budget, spend and what it has left to spend, read live at most once a minute, or as last read with its readAt while they cannot be read. Refusals: 409 conflict with reason request_not_fundable before any ad account is shared, or funding_details_unavailable while the organization adds funds with a payment page per top-up (POST /v1/ad-account-requests/{requestId}/top-ups). A key limited to specific brands is refused with 403 brand_not_allowed.
List ad account requests
Lists the organization's ad account requests, newest first. Cancelled requests are not listed. Each request carries its stage (1 request sent, 2 business verified, 3 account being created, 4 shared into your Business Manager, 5 connected in Koast, 6 funds added), the ad accounts it produced (act_…) and every top-up with its payment status. Requests are made in the Koast app, where the business documents are uploaded, and Koast reviews each one before sending it on: awaitingReview is true until then. A key limited to specific brands is refused with 403 brand_not_allowed: requests belong to the whole organization.