Client Connections API

All endpoints require authentication and clients tool permissions. Routes are mounted under /api/clients.

Connections

List Connections

GET /api/clients/:companyId/connections

Returns all platform connections for a client. Credentials are never returned in the response.

Permission: clients:view

Path parameters:

Param	Type	Description
companyId	string	Company ID

Response: { connections }

Each connection includes: id, company_id, platform, status, source, connected_by_user_id, connected_at, last_synced_at, last_sync_error, store_url, account_id, display_name, scopes, token_expires_at, created_at, updated_at.

---

Create Connection

POST /api/clients/:companyId/connections

Creates a new platform connection. Tests the credentials before saving. Credentials are encrypted at rest.

Permission: clients:update

Path parameters:

Param	Type	Description
companyId	string	Company ID

Body:

Field	Type	Required	Description
platform	string	Yes	Platform identifier (e.g. meta_ads, google_ads, tiktok_ads, shopify, ga4)
credentials	object	Yes	Platform-specific credentials
display_name	string	No	Friendly name for the connection

Response: { connection } (201)

Error responses:

• 400 — Invalid platform or connection test failed
• 409 — Platform is already connected

---

Update Connection

PATCH /api/clients/:companyId/connections/:id

Permission: clients:update

Body:

Field	Type	Description
display_name	string	Updated display name

Response: { ok: true }

---

Disconnect

DELETE /api/clients/:companyId/connections/:id

Soft-disconnects a connection by setting status to disconnected and clearing credentials.

Permission: clients:update

Response: { ok: true }

Error: 404 if connection not found.

---

Test Connection

POST /api/clients/:companyId/connections/:id/test

Tests an existing connection by decrypting credentials and running a platform-specific health check.

Permission: clients:update

Response: { success, error?, account_id?, display_name? }

Error: 404 if connection not found or not active.

---

Manual Sync

POST /api/clients/:companyId/connections/sync

Triggers a background sync for all connected platforms.

Permission: clients:update

Response: { message: "Sync started" } (202)

---

Historical Backfill

POST /api/clients/:companyId/connections/backfill

Triggers a historical data backfill for ad platform connections.

Permission: clients:update

Body:

Field	Type	Required	Description
days	number	Yes	Backfill period: 30, 60, or 90

Response: { message: "Backfill started for {days} days" } (202)

Error responses:

• 400 — Invalid days value
• 409 — A backfill is already in progress

---

Results

Get Aggregated Results

GET /api/clients/:companyId/results

Returns aggregated metric snapshots for a client over a period, with prior-period comparison and goal tracking.

Permission: clients:view

Path parameters:

Param	Type	Description
companyId	string	Company ID

Query parameters:

Param	Type	Description
period_type	string	week, month (default), quarter, or year
period_end	string	End date (default: today)

Response: { period, prior_period, metrics, insight, connected_platforms }

Each metric includes:

Field	Type	Description
metric_key	string	Metric identifier
value	number	Total value for period
avg_value	number	Average value
data_points	number	Number of data points
currency	string	Currency code
prior_value	number|null	Prior period value
delta_pct	number|null	Period-over-period change %
target	number|null	Goal target
tracking_status	string|null	on_track, at_risk, or off_track

---

Get Campaign Results

GET /api/clients/:companyId/results/campaigns

Returns campaign-level aggregated metrics with prior-period spend delta.

Permission: clients:view

Query parameters:

Param	Type	Description
period_type	string	week, month (default), quarter, or year
period_end	string	End date (default: today)
platform	string	Filter by platform
sort_by	string	Sort column (default: spend). Options: spend, impressions, clicks, conversions, conversion_value, reach, frequency, roas, cpa, cpm, ctr, campaign_name
sort_dir	string	Sort direction: asc or desc (default)

Response: { period, campaigns, totals }

Each campaign includes: campaign_id, campaign_name, platform, campaign_status, campaign_objective, daily_budget, lifetime_budget, spend, impressions, clicks, conversions, conversion_value, reach, frequency, cpm, cpc, ctr, roas, cpa, currency, spend_delta_pct.

---

Get Campaign Daily Data

GET /api/clients/:companyId/results/campaigns/daily

Returns daily spend data per campaign for sparkline rendering.

Permission: clients:view

Query parameters:

Param	Type	Description
period_type	string	week, month (default), quarter, or year
period_end	string	End date (default: today)
platform	string	Filter by platform

Response: { daily } — object keyed by campaign_id, each value is an array of { date, spend }.

---

AI Q&A

POST /api/clients/:companyId/results/ask

Ask a natural-language question about the client’s performance data. Uses AI to generate an answer.

Permission: clients:view

Body:

Field	Type	Required	Description
question	string	Yes	Natural-language question

Response: { answer }

---

Prepare QBR

POST /api/clients/:companyId/results/prepare-qbr

Generates a Quarterly Business Review summary from the last 3 months of metrics and the latest AI insight. Creates a QBR record and updates the client profile’s last_qbr_date.

Permission: clients:update

Response: { qbr } (201)

The QBR object includes id, date, and summary.

---

Platform Metadata

Get Supported Platforms

GET /api/clients/platforms

Returns metadata for all supported platform types (no permission required beyond authentication).

Response: { platforms } — object keyed by platform ID with display names, icons, and credential requirements.