Get ad account request
Reads one ad account request by its id or its Koast reference (KST-…): its status, the six-stage timeline with when each stage was reached, the ad accounts it produced and every top-up.
Tool name: get-ad-account-request.
Reads one ad account request by its id or its Koast reference (KST-…): its status, the six-stage timeline with when each stage was reached, the ad accounts it produced and every top-up.
When to use
Use when the user names one request or reference, or to follow a payment for funds after add-ad-account-funds: its top-up moves from AWAITING_PAYMENT to PAID to CREDITED.
Access
| Property | Value |
|---|---|
| Required scope | read |
| Publishes | No |
| Read-only | Yes |
| Destructive | No |
| Idempotent | Yes |
| Open world | No |
Input
| Field | Type | Required | Description |
|---|---|---|---|
requestId | string | Yes | The ad account request id, or its Koast reference (KST-…). At most 40 characters. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
reference | string | Yes | The Koast reference shown in the app and in emails, KST-…. |
status | string | Yes | 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. One of QUEUED, SUBMITTED, VERIFYING, CREATING, SHARED, READY, REJECTED, CANCELLED. |
accountName | string | Yes | The ad account name the customer asked for. |
count | integer | Yes | How many ad accounts were requested. |
currency | string | Yes | |
createdAt | string | Yes | |
brandId | integer | null | Yes | The Koast brand the first ad account was connected to, once connected. |
adAccountIds | string[] | Yes | The ad accounts connected in Koast, act_…. |
rejectionReason | string | null | Yes | |
stage | integer | Yes | 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. Minimum 0, maximum 6. |
awaitingReview | boolean | Yes | 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 | object[] | Yes | The ad accounts created for the request, once shared. |
topUps | object[] | Yes | Every top-up started for the request, oldest first. |
businessManagerName | string | null | Yes | |
compliance | object | Yes | What the customer declared about the offer when requesting. Each field is null for a request made before Koast asked for it. |
timeline | object[] | Yes | The six stages in order. |
REST equivalent
GET /v1/ad-account-requests/{requestId}, Get ad account request. CLI: koast get-ad-account-request.
Add ad account funds
Starts adding funds to an ad account from an ad account request: prices the budget plus Koast's fee and the platform location fee, and returns the payment page (checkoutUrl) the user must open to pay.
List ad account requests
Lists the organization's requests for new Meta ad accounts made through Koast: each request's status and stage, the ad accounts it produced with their act ids, and the funds added to them.