API referenceIntegrations

Connect ClickFlare

Connects ClickFlare to the brand. Koast checks the key against ClickFlare, reads the account timezone and currency, and detects which tracking fields carry the ad platform campaign, ad set and ad ids. Sending a new key to a connected brand replaces the key and keeps the settings. Answers 422 when ClickFlare rejects the key. Requires an organization owner or admin.

POST
/v1/brands/{brandId}/integrations/clickflare

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

brandId*integer

The brand the request acts on. Every brand-scoped resource lives under its brand.

Header Parameters

Idempotency-Key?string

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

Lengthlength <= 255

Request Body

application/json
  1. body
apiKey*string

A ClickFlare API key (ClickFlare → Settings → API keys).

Length1 <= length <= 512
workspaceIds?array<>

ClickFlare workspace ids to read. An empty list reads every workspace of the account.

Itemsitems <= 200

Response Body

Connect ClickFlare

application/json
  1. response
brandId*number
connected*boolean

Whether a ClickFlare API key is connected to the brand.

maskedApiKey*string|null
timezone*|

The ClickFlare account timezone used for reports. Null means UTC is used.

currency*string|null
workspaceIds*array<string>
trackingFields*
trackingFieldsSource*

How each tracking field was chosen: data (matched Koast ids in ClickFlare traffic), traffic_source (the traffic source template), or manual.

lastPullAt*string|null
lastPullError*string|null
lastPullRows*number|null
curl -X POST "https://example.com/v1/brands/0/integrations/clickflare" \  -H "Authorization: Bearer koast_sk_..." \  -H "Content-Type: application/json" \  -d '{    "apiKey": "string"  }'
{  "brandId": 0,  "connected": true,  "maskedApiKey": "string",  "timezone": "string",  "currency": "string",  "workspaceIds": [    "string"  ],  "trackingFields": {    "campaign": "string",    "adset": "string",    "ad": "string"  },  "trackingFieldsSource": {    "campaign": "data",    "adset": "data",    "ad": "data"  },  "lastPullAt": "string",  "lastPullError": "string",  "lastPullRows": 0}

Required scope: write. CLI: koast connect-clickflare, see Integrations commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.

Upload creative

Stores an image in the brand's creative library and returns its creativeId. Pass exactly one of imageUrl (a public https URL that Koast downloads and re-hosts) or fileData (base64 bytes, with contentType and fileName). Uploading bytes the brand already holds returns the existing creative with reused: true. Images only; no ad is created or changed.

Disconnect ClickFlare

Disconnects ClickFlare from the brand: removes the API key, the campaign mappings and the spend push setting. Conversion and revenue data already pulled from ClickFlare is kept. Requires an organization owner or admin.