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.

GET

/v1/ad-account-requests/{requestId}

Authorization

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.

Path Parameters

requestId*string

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

Length1 <= length <= 40

Response Body

Get ad account request

application/json

response

id*string

reference*string

The Koast reference shown in the app and in emails, KST-….

status*string

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

Value in"QUEUED""SUBMITTED""VERIFYING""CREATING""SHARED""READY""REJECTED""CANCELLED"

accountName*string

The ad account name the customer asked for.

count*integer

How many ad accounts were requested.

Range-9007199254740991 <= value <= 9007199254740991

currency*string

createdAt*string

brandId*|

The Koast brand the first ad account was connected to, once connected.

adAccountIds*array<string>

The ad accounts connected in Koast, act_….

rejectionReason*string|null

stage*integer

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

Range0 <= value <= 6

awaitingReview*boolean

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

businessManagerName*string|null

compliance*

What the customer declared about the offer when requesting. Each field is null for a request made before Koast asked for it.

timeline*array<>

The six stages in order.

curl -X GET "https://example.com/v1/ad-account-requests/string" \  -H "Authorization: Bearer koast_sk_..."

{  "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"    }  ],  "businessManagerName": "string",  "compliance": {    "offer": "string",    "specialAdCategory": "none",    "legitScriptUrl": "string"  },  "timeline": [    {      "stage": -9007199254740991,      "label": "string",      "at": "string"    }  ]}

Required scope: read. CLI: koast get-ad-account-request, see Ad Account Requests commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.