Organization API: Organizations & Members: Ads

Part of Organizations & Members.

GET /api/v1/orgs/{org_slug}/ads

Every ad platform with its status, every connected ad account, and the last 30 days of spend.

Needs the Admin or Owner role. platforms lists Google Ads, Meta Ads, TikTok Ads, Microsoft Ads and Reddit Ads. A platform's status is not_configured (Coritan has not added its app credentials, so it cannot be connected), not_connected, pending (signed in, no account picked yet), connected, failing (an account has had errors and no successful read for an hour) or reauth (the sign-in ended, so connect again). connections has one entry for each ad account the sign-in found, with the same status words (an account that is found but not picked reads pending), when it was last read, the last error, how far its 13 month history has been read and its spend per currency. summary is the last 30 days of spend per currency, with entered spend included. warning is set when a sign-in ends within 14 days. Nothing here carries a token.

DELETE /api/v1/orgs/{org_slug}/ads/connections/{connection_id}

Disconnect one ad account.

Needs the Admin or Owner role. The account's saved sign-in is deleted and nothing is read from it again. The spend already imported stays in your reports. Connect the platform again to read the account again.

POST /api/v1/orgs/{org_slug}/ads/connections/{connection_id}/sync

Read one ad account now.

Needs the Admin or Owner role. With no body it reads today and the two days before. With from and to it reads those days again (at most 400, none before 13 months ago), which is how to refresh a month after the platform adjusts its numbers. The read runs in the background: check last_sync_at on the account. Answers 409 when the account's sign-in has ended or the account is not picked, and 429 after 4 requests an hour for one account.

application/json

GET /api/v1/orgs/{org_slug}/ads/return

What the ad spend returned: orders, new customers, revenue, CAC and ROAS per platform, and per campaign.

Needs the Admin or Owner role. An order counts for the platform its last touch came from, when its invoice is paid and it is not free: the touch's source and medium name the platform, and when they do not, its click ids do. Within a platform an order counts for the campaign whose name (or id) equals its utm_campaign, ignoring case. new_customers counts customers whose first paid order it was. roas is revenue without tax over spend, cac_minor is spend over new customers, and platform_roas is the value the platform reports over spend. Each is empty when its divisor is zero. Rows are per currency: spend and revenue meet only when they are in the same currency, so an ad account billed in one currency and customers paying in another show as separate rows with no CAC or ROAS. Payback is not computed, because it needs a gross margin that is not kept. truncated is true when more than 50,000 orders were in the range.

GET /api/v1/orgs/{org_slug}/ads/spend

What was spent, grouped by platform, campaign or day.

Needs the Admin or Owner role. Every row is in one currency, and a platform that spent in two currencies has two rows: amounts in different currencies are never added. totals is the whole range per currency, even when limit (rows for each currency, by campaign) cuts the rows. Spend entered by hand is included, spread evenly over its days. The range is at most 400 days. Days follow each ad account's own time zone (Microsoft Ads and Reddit Ads follow the organization's), so a day's spend can differ a little from the platform's own report in another zone.

GET /api/v1/orgs/{org_slug}/ads/spend/manual

Spend entered by hand, newest first.

Needs the Admin or Owner role. ignored is true for an entry whose channel has since been connected, which reports leave out because the platform's own numbers cover it.

POST /api/v1/orgs/{org_slug}/ads/spend/manual

Enter spend for a channel that has no connection.

Needs the Admin or Owner role. amount_minor is the whole amount over starts_on to ends_on (at most 400 days), and reports spread it evenly over those days. A platform with a picked account, or one that was already read for some of these days, is refused with 409 because its own numbers cover it. Answers 422 for a channel, currency, amount or dates that do not fit.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/ads/spend/manual/{entry_id}

Remove an entry of spend entered by hand. Needs the Admin or Owner role.

POST /api/v1/orgs/{org_slug}/ads/{platform}/accounts

Pick which of the platform's accounts to read.

Needs the Admin or Owner role. account_ids is the whole list: accounts you name start being read (their 13 month history first), and accounts of this platform you leave out stop being read but keep the spend already imported. At most 50 accounts for one platform. Answers 422 for an account that is not on the sign-in. Pick only the accounts that belong to this organization: a sign-in to a manager account can list accounts that are not yours.

application/json (required)

POST /api/v1/orgs/{org_slug}/ads/{platform}/connect

Start signing in to an ad platform. Answers authorization_url, the platform's own page.

Needs the Admin or Owner role. Send the person to authorization_url. The platform sends the browser back to Coritan, which finds the accounts the sign-in can read and returns the person to return_path (a page of the console on the host of this request) with ads=connected or ads=error in the address. The link is good for 15 minutes. Answers 409 not_configured when the platform's app credentials have not been added to Coritan, and 422 when the request does not come from one of your console's hosts.

application/json