API referenceAd Account Requests

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.

POST
/v1/ad-account-requests/{requestId}/accounts/{adAccountId}/changes
bearerAuth
headerAuthorizationBearer <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*string

The ad account request id, or its Koast reference (KST-…).

Length1 <= length <= 40
adAccountId*string

The ad account to change, act_…: one of the request's accounts.

Length1 <= length <= 40
Idempotency-Key?string

Retrying with the same key within 24 hours returns the first response without acting again.

Lengthlength <= 255
application/json
  1. body
kind*string

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

Value in"rename""card""share_business_manager""connect_pixel""connect_page""connect_instagram""change_domain"
name?string

For rename: the new ad account name.

Length1 <= length <= 100
businessManagerId?string

For share_business_manager: the id of the Business Manager to share the ad account into.

Length1 <= length <= 40
access?string

For share_business_manager: manage (full control) or advertise (create and run ads).

Value in"manage""advertise"
pixelId?string

For connect_pixel: the pixel (dataset) id. The pixel must first be shared with Koast's Business Manager, assetBusinessManagerId on the request.

Length1 <= length <= 40
pageUrl?string

For connect_page: the Facebook page link. The page must first be shared with Koast's Business Manager.

Length1 <= length <= 500
instagram?string

For connect_instagram: the Instagram handle or profile link. The account must first be shared with Koast's Business Manager.

Length1 <= length <= 100
domain?string

For change_domain: the new domain the ads send people to, such as newdomain.com.

Length1 <= length <= 253
note?string

Anything else the team should know, in the user's words.

Lengthlength <= 1000

Response Body

Request ad account change

application/json
  1. 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.