Request ad account replacement
Asks the ad account partner to replace an ad account of the request that is not running, and returns the request with the replacement on that account (accounts[].replacement). Koast follows it through on its own: once the partner hands the new account over, Koast connects it to the brand the old one was on, moves the budget left on the old account to the new one (movedCents) and emails the person who requested the account. The request must be SHARED or READY. Refused with 409 conflict and reason account_running while the ad account is still running, replacement_open while a replacement is under way, already_replaced once it was replaced, request_not_replaceable before the account is shared, and replacement_refused when the partner refuses it. Another organization's request answers 404.
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.
requestId*stringThe ad account request id, or its Koast reference (KST-…).
1 <= length <= 40adAccountId*stringThe ad account that stopped running, act_…: one of the request's accounts.
1 <= length <= 40Idempotency-Key?stringRetrying with the same key within 24 hours returns the first response without acting again.
length <= 255application/json- body
reason?stringWhat happened to the ad account, in the user's words, passed on to the ad account partner.
length <= 500Request ad account replacement
application/json- response
id*stringreference*stringThe Koast reference shown in the app and in emails, KST-….
status*stringQUEUED and SUBMITTED while the request is sent, VERIFYING while the business is checked, CREATING while the account is created, SHARED once it is shared into the Business Manager, READY once it is connected in Koast, REJECTED (see rejectionReason) or CANCELLED. Funds can be added from SHARED.
"QUEUED""SUBMITTED""VERIFYING""CREATING""SHARED""READY""REJECTED""CANCELLED"accountName*stringThe ad account name the customer asked for.
count*integerHow many ad accounts were requested.
-9007199254740991 <= value <= 9007199254740991currency*stringcreatedAt*stringbrandId*|The Koast brand the first ad account was connected to, once connected.
adAccountIds*array<string>The ad accounts connected in Koast, act_….
rejectionReason*string|nullstage*integerThe last stage reached: 1 request sent, 2 business verified, 3 account being created, 4 shared into your Business Manager, 5 connected in Koast, 6 funds added.
0 <= value <= 6awaitingReview*booleanTrue while Koast reviews the request before sending it on. It stays QUEUED at stage 1 until Koast approves it, or REJECTED with a rejectionReason.
accounts*array<>The ad accounts created for the request, once shared.
topUps*array<>Every top-up started for the request, oldest first.
curl -X POST "https://example.com/v1/ad-account-requests/string/accounts/string/replacement" \ -H "Authorization: Bearer koast_sk_..." \ -H "Content-Type: application/json" \ -d '{}'{ "id": "string", "reference": "string", "status": "QUEUED", "accountName": "string", "count": -9007199254740991, "currency": "string", "createdAt": "string", "brandId": -9007199254740991, "adAccountIds": [ "string" ], "rejectionReason": "string", "stage": 0, "awaitingReview": true, "accounts": [ { "adAccountId": "string", "name": "string", "status": "string", "replacement": { "status": "requested", "requestedAt": "string", "reason": "string", "newAdAccountId": "string", "movedCents": -9007199254740991, "completedAt": "string" }, "replaces": "string" } ], "topUps": [ { "id": "string", "adAccountId": "string", "budgetCents": -9007199254740991, "commissionCents": -9007199254740991, "locationFeeCents": -9007199254740991, "netCents": -9007199254740991, "amountCents": -9007199254740991, "currency": "string", "status": "AWAITING_PAYMENT", "paymentMethod": "card", "createdAt": "string", "paidAt": "string", "creditedAt": "string" } ]}Required scope: write. CLI: koast request-ad-account-replacement, see Ad Account Requests commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.
Get ad account request
Returns one ad account request of the organization, by its id or its Koast reference (KST-…), with the timeline of its six stages, the ad accounts it produced and every top-up. Another organization's request answers 404.
Add ad account funds
Creates a top-up and a payment page for it, and returns the top-up with its fees and checkoutUrl. The call itself moves no money: the user pays on the page, by the payment method chosen here only, and Koast adds the funds to the ad account once the payment is received. A card payment is received at once; a US bank transfer takes 1-3 business days to arrive. Follow it with GET /v1/ad-account-requests/{requestId}: the top-up moves from AWAITING_PAYMENT to PAID to CREDITED. Every call creates a new payment page; send an Idempotency-Key so that a retry returns the same one. Refusals are those of GET /v1/ad-account-requests/{requestId}/top-ups/quote, and 409 conflict with reason use_funding_details for a bank transfer or crypto when the organization sends those to its funding details (GET /v1/ad-account-funding) instead of a payment page.