Request ad account change
Asks for a change on one ad account of the request and returns it (change), open until the ad account partner makes it. kind picks the change and the field it needs: rename (name), share_business_manager (businessManagerId, access), connect_pixel (pixelId), connect_page (pageUrl), connect_instagram (instagram), change_domain (domain); note is passed on with any of them. A pixel, page or Instagram account must first be shared, with admin access, with the Business Manager in assetBusinessManagerId of the request. Koast emails the person who asked once it is done or refused; follow it with GET /v1/ad-account-requests/changes. kind: card is refused with 400 validation_failed (card_in_app): cards are added in the Koast app. Refused with 409 conflict and reason change_already_open while a change of the same kind is open on the ad account, and account_not_changeable for an account the request did not deliver (SHARED or READY) or one that was replaced. A missing or malformed field answers 400 validation_failed naming it. Another organization's request answers 404, and a key limited to specific brands 403 brand_not_allowed.
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 to change, 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
kind*stringWhat to change: rename (give name), share_business_manager (give businessManagerId and access), connect_pixel (give pixelId), connect_page (give pageUrl), connect_instagram (give instagram), change_domain (give domain). card is refused here: a card is added in the Koast app.
"rename""card""share_business_manager""connect_pixel""connect_page""connect_instagram""change_domain"name?stringFor rename: the new ad account name.
1 <= length <= 100businessManagerId?stringFor share_business_manager: the id of the Business Manager to share the ad account into.
1 <= length <= 40access?stringFor share_business_manager: manage (full control) or advertise (create and run ads).
"manage""advertise"pixelId?stringFor connect_pixel: the pixel (dataset) id. The pixel must first be shared with Koast's Business Manager, assetBusinessManagerId on the request.
1 <= length <= 40pageUrl?stringFor connect_page: the Facebook page link. The page must first be shared with Koast's Business Manager.
1 <= length <= 500instagram?stringFor connect_instagram: the Instagram handle or profile link. The account must first be shared with Koast's Business Manager.
1 <= length <= 100domain?stringFor change_domain: the new domain the ads send people to, such as newdomain.com.
1 <= length <= 253note?stringAnything else the team should know, in the user's words.
length <= 1000Request ad account change
application/json- response
change*curl -X POST "https://example.com/v1/ad-account-requests/string/accounts/string/changes" \ -H "Authorization: Bearer koast_sk_..." \ -H "Content-Type: application/json" \ -d '{ "kind": "rename" }'{ "change": { "id": "string", "requestId": "string", "adAccountId": "string", "kind": "rename", "status": "open", "label": "string", "reason": "string", "askedAt": "string", "decidedAt": "string", "acknowledged": true, "cardLast4": "string" }}Required scope: write. CLI: koast request-ad-account-change, 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.
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.