Organization API: Org Staff Marketing: Staff

Part of Org Staff Marketing.

GET /api/v1/orgs/{org_slug}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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}/staff/marketing/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

GET /api/v1/orgs/{org_slug}/staff/marketing/announcements

Whether a Discord webhook is saved for announcements, and its channel label.

Needs the Admin or Owner role. configured says whether a webhook address is saved, channel_label is the name your team gave the channel (null for none) and webhook_hint is the last four characters of the webhook's ID, so you can tell which webhook is saved. The address is a secret and is never answered.

PUT /api/v1/orgs/{org_slug}/staff/marketing/announcements

Save the Discord webhook address and the channel label. Send only what changes.

Needs the Admin or Owner role. webhook_url must be an https address on Discord's own hosts that starts with https://discord.com/api/webhooks/, or 422 answers with detail and field. It is sealed and never shown again, and null or an empty string removes it. channel_label is at most 80 characters. The answer is the one GET gives. Saving what is already saved changes nothing and writes no audit entry. A change is recorded as announcements.updated with the settings that changed and never the address.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/marketing/announcements/history

The announcements posted or refused, newest first.

Needs the Admin or Owner role. Each entry has status (posted or failed), the title, content and link that were sent, the channel_label then saved, error (why a failed post failed, never what Discord said), actor_type (staff, user or admin for platform staff), actor ({id, name}, null when it is unknown) and created_at. The webhook address is never in an entry.

POST /api/v1/orgs/{org_slug}/staff/marketing/announcements/post

Post one message to the saved Discord webhook.

Needs the Admin or Owner role. content is the message, 1 to 1,800 characters. title (at most 120 characters) becomes a bold first line, and link (an https address) goes after the message. The title, text and link together fit Discord's 2,000 characters, or 422 answers. Nothing in the message can mention a role or a person. The answer is {posted: true}. 409 means no webhook is saved. 502 means Discord did not take the message, with detail saying so in a sentence, and nothing was posted. At most 10 messages an hour for the organization, and the 11th answers 429. Every attempt is recorded in the audit log as announcement.posted or announcement.failed with the words and the channel label, never the address.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/marketing/campaigns

The organization's saved campaign links, newest first.

Needs the Billing, Admin or Owner role. A campaign is a landing page with the UTM words that tag it and an optional coupon. Every campaign has all its fields, archived (true once it was archived) and url, the full link to copy: the storefront address, base_path, the UTM words in the order utm_source, utm_medium, utm_campaign, utm_term, utm_content, then coupon. The words are percent encoded. An organization with no storefront address gets the path and query alone. count is how many campaigns match before limit and offset apply, and max_campaigns is the most an organization keeps.

POST /api/v1/orgs/{org_slug}/staff/marketing/campaigns

Save a campaign link and answer it, with its url.

Needs the Billing, Admin or Owner role. name, utm_source, utm_medium and utm_campaign are required. A bad value answers 422 with detail, the sentence to show, and field, the input it belongs to. A name another campaign already has, in any capitals, answers 409 with field name. An organization keeps at most 500 campaigns, and the 501st answers 409. A coupon_code must be a coupon of this organization. The change is recorded in the audit log as campaign.created.

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/marketing/campaigns/preview

Build the link for the fields sent, and list what is wrong with them. Saves nothing.

Needs the Billing, Admin or Owner role. Send the same body as a save; name may be left out. The answer is {url, problems}. problems is a list of {field, detail} with every problem found, and url is null while there is one. The check is the one a save makes, a repeated name and an unknown coupon included.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/marketing/campaigns/results

What every saved campaign brought in over a period, and the campaign words no saved campaign names.

Needs the Billing, Admin or Owner role. The period is from to to in the brand's time zone, the last 30 days when left out, and at most 366 days. A campaign owns the visits, sign-ups and orders whose utm_campaign is its own, ignoring capitals. The figures are the acquisition report's: a visit is a stored session with bots left out, a sign-up is a customer whose last touch named the campaign, an order is a paid order that is not free, and revenue_minor is the invoice total without tax in currency's minor units. Orders and revenue are counted in one currency and never added across currencies: currencies names every currency with an order in the period. conversion_rate_bp is orders over visits in basis points, so 123 is 1.23 percent. visits_complete is false when the period starts more than 180 days ago, because sessions are kept for 180 days. unmatched lists the campaign words of the period that no saved campaign names, the biggest first, at most limit.

PATCH /api/v1/orgs/{org_slug}/staff/marketing/campaigns/{campaign_id}

Change the fields of a campaign that were sent, or archive it with archived, and answer it.

Needs the Billing, Admin or Owner role. Only the fields sent are checked and changed, by the rules of a save. A null or empty utm_term, utm_content, coupon_code or notes clears it. Saving what is already there changes nothing and writes no audit entry. A change is recorded as campaign.updated with the names of the fields that changed. A campaign of another organization answers 404.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/staff/marketing/campaigns/{campaign_id}

Delete a campaign link. The visits and orders that carried its words stay in the reports.

Needs the Billing, Admin or Owner role. Archive a campaign instead to keep its link and its results in the list. A campaign of another organization answers 404. Recorded as campaign.deleted.

GET /api/v1/orgs/{org_slug}/staff/marketing/campaigns/{campaign_id}/results

What one campaign brought in over a period and over the period before it.

Needs the Billing, Admin or Owner role. The figures and their definitions are those of GET results. totals holds visits, signups, orders, new_customers, revenue_minor and conversion_rate_bp, and totals.previous holds the same for the comparison period, or null when compare is none. A campaign of another organization answers 404.

GET /api/v1/orgs/{org_slug}/staff/marketing/conversions

Every ad platform the organization can send purchases to, with its settings and how it is doing.

Needs the Admin or Owner role. There is one entry for each of ga4, google_ads, meta_capi, tiktok_events, microsoft_ads, reddit_ads and x_ads, whether or not it was ever set up. An entry has enabled, test_mode, config (the settings that are not secret), secret_set (whether a secret is saved; the secret is never answered), fields and secret (what a form for the kind asks), last_delivery (the newest event the kind was sent, with its status) and coverage: orders is how many first purchases were paid in the last 30 days, sent how many of them the kind was sent, and rate is sent over orders (null with no orders). Microsoft Ads has no secret. Its entry has feed_url_masked, the address of its file with the token hidden, and when Microsoft Advertising last fetched it.

GET /api/v1/orgs/{org_slug}/staff/marketing/conversions/deliveries

What each platform was sent, newest first, and why anything was not.

Needs the Admin or Owner role. Every row is one event for one platform: event is purchase (a first purchase), renewal, upgrade, free_server, sign_up, refund or chargeback; status is sent, skipped (error says why: the buyer did not allow marketing, the platform has no such event, renewals are off) or failed (http_status and error hold the platform's answer, and a timeout or a server error is tried again, three attempts in all). invoice names the invoice the row belongs to. Filter by kind, status and invoice_number; count is the total that match.

PUT /api/v1/orgs/{org_slug}/staff/marketing/conversions/{kind}

Turn a platform on or off, set its test mode, change its settings, set or clear its secret.

Needs the Admin or Owner role. Send only what changes. config keys replace the saved ones and a null or empty string removes one; labels (Google Ads) and events (X) replace the whole map. secret is write only: it is sealed, never answered and never written to the audit log, and an empty string clears it. X takes an object of consumer_key, consumer_secret, access_token and access_token_secret. Google Ads and Microsoft Ads take no secret, and a secret for them answers 422. A value that does not fit, or a platform turned on without what it needs, answers 422 with detail, the sentence to show, and field, the input it belongs to. Every ID is checked as the analytics and ad tags check theirs.

Turning Microsoft Ads on the first time makes the address of its file, and only that answer carries the whole address in feed_url. Copy it into a schedule in Microsoft Advertising. Later answers show it with the token hidden. The answer is {integration, changed, feed_url}. Each change is recorded in the audit log without any secret.

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/marketing/conversions/{kind}/rotate-feed-token

Replace the token in the Microsoft Ads file address, so the old address stops working.

Needs the Admin or Owner role. The answer is {integration, feed_url} and the only one that shows the new address whole. Put it in the schedule in Microsoft Advertising; from now on the old address answers 404. Purchases the file already listed stay listed. Answers 409 before Microsoft Ads was first turned on, since that makes the first address.

POST /api/v1/orgs/{org_slug}/staff/marketing/conversions/{kind}/test

Send one made-up purchase to a platform in test mode and answer what the platform said.

Needs the Admin or Owner role. The event is for one currency unit of a product called "Test product" and carries nothing about a person. Meta and TikTok send their test event code, Google Analytics its validation endpoint and Reddit its test flag, so nothing reaches live reporting. The platform needs its settings and secret saved first (422 names the missing one). Google Ads and X have no test mode, so a test would count as a real sale and answers 422, and Microsoft Ads fetches its file and takes no events. At most ten test events an hour for each platform (429). The test is not logged as a delivery and is not counted in coverage. The answer is {kind, event, status, ok, http_status, error, event_id}.

GET /api/v1/orgs/{org_slug}/staff/marketing/flows

Every automatic email flow of the organization, whether or not it was ever turned on.

Needs the Admin or Owner role. There is one entry for each of unpaid_invoice, stuck_setup, free_upgrade, winback, onboarding and review_invite. An entry has its label, kind (service flows are about the customer's own order and need no marketing consent, marketing flows go only to customers who agreed to marketing email) and description; enabled and config, the saved settings with the defaults filled in; fields, what a form for the settings asks (key, label, kind, default, min, max, hint); template_slugs, one for each step; blocked, the sentence that says why the flow cannot send even when on (the review invitation needs a saved Trustpilot review link), or null; and stats, how many emails are scheduled, sent, skipped, failed or canceled and last_sent_at. Every flow is off until turned on. One customer gets at most one flow email in 3 days, from any flow.

GET /api/v1/orgs/{org_slug}/staff/marketing/flows/messages

Every email a flow scheduled, newest first, with what became of it.

Needs the Admin or Owner role. A row has flow, step, status, email, scheduled_at, sent_at, customer_id and error. scheduled waits for the next pass (at most ten minutes), sent went to the mail server, skipped was left out on purpose (error says why: the address unsubscribed, the account is not active, another flow email went to the customer in the last 3 days, or it was due more than a day ago), canceled lost its reason before it went (the invoice was paid, the server is running, the customer withdrew consent, the flow was turned off) and failed was refused by the mail server. count is the total that match, before limit and offset.

PUT /api/v1/orgs/{org_slug}/staff/marketing/flows/{key}

Turn a flow on or off and change its settings. Send only what changes.

Needs the Admin or Owner role. config keys replace the saved ones; GET lists them in fields with their ranges. coupon_code (win-back) takes a coupon of the organization, or null to remove it. A value that does not fit answers 422 with detail, the sentence to show, and field, the input it belongs to (config.after_days, or enabled for the review invitation without a saved Trustpilot review link), and changes nothing. The answer is {flow, changed}: the flow as GET lists it and the names that differ. Saving what is already saved changes nothing and writes no audit entry. A change is audited as flows.updated with the settings before and after. A flow starts mailing at its next pass, within ten minutes, and only customers who qualify from then on.

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/marketing/flows/{key}/test

Send the flow's email, filled with made-up facts, to the address of the signed-in member.

Needs the Admin or Owner role. The test goes out whether or not the flow is on, as service mail, with the brand's own links and the flow's coupon code, and writes nothing to the flow log. An address on the organization's unsubscribe list gets nothing (409). step picks the email of a flow with two (422 for a step the flow lacks). The member needs an address on their account (400). At most ten test emails an hour for one member (429). The answer is {sent, to, flow, step, template}; 502 when the mail server did not accept it. Audited as flows.test_sent.

application/json

GET /api/v1/orgs/{org_slug}/staff/marketing/referrals

Every referral of the organization, newest first, and the program's totals.

Needs the Admin or Owner role. A referral is one referred customer: their first paid invoice started it. status is qualified while it waits out its hold (hold_until), credited once the wallet credit is paid, and void when a rule refused it (void_reason says which, or holds the reason staff gave). referrer and referee name the two customers, code the code that was used and invoice the invoice that started it. reward_amount is what the referrer is paid and referee_reward_amount the welcome credit, both in wallet dollars (currency). count is how many referrals match the filters. totals covers the whole program and ignores the filters: the number of referrals in each status, credited_amount paid out so far and owed_amount for the open ones.

GET /api/v1/orgs/{org_slug}/staff/marketing/referrals/codes

The organization's referral codes, newest first, each with how many referrals it started.

Needs the Admin or Owner role. A customer code is made for each customer the first time they open their referral page. A partner code is made by your team and pays commission_bp of the referred customer's first invoice. referrals on a code is {total, credited, earned}: the referrals it started, how many were paid, and what they paid the owner in wallet dollars.

POST /api/v1/orgs/{org_slug}/staff/marketing/referrals/codes

Make a partner code that pays a share of the first invoice of every customer it brings.

Needs the Admin or Owner role. Name the owner with customer_id or email: an active customer of this organization. commission_bp (1 to 5000, 100 is 1 percent) is the share of the referred customer's first invoice, without tax, paid into the owner's wallet once the hold has passed. code is optional: 3 to 40 letters, digits, hyphens or underscores, and without regard to capitals it must not be in use (409). Left out, we make an 8 character code. At most 30 codes an hour. Answers 422 with detail and field for a value that does not fit. The code is recorded in the audit log as referral_code.created.

application/json (required)

PATCH /api/v1/orgs/{org_slug}/staff/marketing/referrals/codes/{code_id}

Change whether a code works, a partner code's commission, or its label. The code itself never changes.

Needs the Admin or Owner role. active: false stops the code from starting new referrals; referrals it already started still pay. commission_bp (1 to 5000) is for a partner code only: a customer's code pays the program's reward amount. label is a note for your team, and null or an empty string removes it. Send only what changes. Answers 404 for a code of another organization and 422 with detail and field for a value that does not fit. A change is recorded as referral_code.updated with the values before and after.

application/json (required)

POST /api/v1/orgs/{org_slug}/staff/marketing/referrals/{referral_id}/void

Void a referral so it is never paid. Only a pending or qualified referral can be voided.

Needs the Admin or Owner role. reason is required, 1 to 120 characters, and is kept as the referral's void_reason. A referral that is already credited or void answers 409, and money already paid is not taken back. Answers 404 for a referral of another organization. At most 60 an hour. Recorded in the audit log as referral.voided with the reason.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/marketing/reviews

The Trustpilot review settings, and how the review invitation emails are doing.

Needs the Admin or Owner role. enabled is whether the storefront asks signed-in customers for a review, review_url the Trustpilot link it opens (null for none), min_account_age_days how old an account is before it asks, and dismiss_days how long it stays quiet after a customer closes the prompt. The invitation is the email flow review_invite, which uses the same link. invitations holds enabled (the flow's own switch), the number of its messages scheduled, sent, skipped and failed (all 0 until the flow has run) and last_sent_at.

PUT /api/v1/orgs/{org_slug}/staff/marketing/reviews

Change the review settings. Send only what changes.

Needs the Admin or Owner role. review_url must start with https:// and be on trustpilot.com, at most 500 characters, and the prompt cannot be turned on without one. min_account_age_days is 0 to 365 and dismiss_days 1 to 365. A value that does not fit answers 422 with detail, the sentence to show, and field, the setting it belongs to. The answer is the one GET gives, with changed listing the settings that differ from before. Saving what is already saved changes nothing and writes no audit entry. A change is recorded as reviews.updated, and the storefront applies it to new page loads within a minute.

application/json (required)

GET /api/v1/orgs/{org_slug}/staff/marketing/subscribers

The addresses visitors gave the storefront's newsletter form, newest first.

Needs the Admin or Owner role. Every row is one address: id, email, source (where it was collected), consent (whether the visitor agreed to email), consent_text (the words they agreed to), customer_id (the customer with that address, if there is one), suppressed (true when the address is on the suppression list and gets no marketing email whatever its consent says) and created_at. Filter by part of the address with q, by source and by consent; total is every lead the filters match. counts covers the whole organization: leads (every lead), consenting_customers (active customers who agreed to marketing email) and suppressed (addresses on the suppression list).

GET /api/v1/orgs/{org_slug}/staff/marketing/subscribers/export.csv

Every address the organization may send marketing email to, as a CSV file.

Needs the Admin or Owner role. The columns are email, source, consent, kind (lead or customer) and created_at. The file lists leads who agreed to email and active customers who agreed to marketing email, once for each address (an address that is both is a lead). It never lists an address on the suppression list. A cell that starts with =, +, - or @ begins with an apostrophe so a spreadsheet does not run it. A file holds at most 100,000 rows and the answer's X-Export-Truncated: true header says when a list was longer. At most 12 exports an hour (429). Every export is audited as subscribers.exported before the file is answered.

GET /api/v1/orgs/{org_slug}/staff/marketing/subscribers/suppressions

The organization's suppression list, newest first.

Needs the Admin or Owner role. An address on the list gets no marketing email, whatever its owner's consent says. Every row has id, email, reason (unsubscribed, bounced, complained or manual), source (link, account, console or api) and created_at. Filter by part of the address with q; total is every row that matches. The list belongs to this organization alone: an address another brand suppressed is not here.

POST /api/v1/orgs/{org_slug}/staff/marketing/subscribers/suppressions

Stop marketing email to one address.

Needs the Admin or Owner role. reason must be manual (the other reasons are set by an unsubscribe, a bounce or a complaint). The row's source is console. Adding an address cancels the flow emails still waiting for it, takes marketing consent back from a customer with that address and marks a lead with it as not consenting. An address already on the list stays as it was and the answer has added: false. A bad address or reason answers 422 {"detail", "field"}. The answer is {suppression, added} and a new entry is audited as suppression.added.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/staff/marketing/subscribers/suppressions/{suppression_id}

Let marketing email reach an address again.

Needs the Admin or Owner role. This removes the row only: it does not give anyone's consent back, so a customer or lead who withdrew still has to agree again before they get marketing email. 404 for an id that is not on this organization's list. Audited as suppression.lifted.

DELETE /api/v1/orgs/{org_slug}/staff/marketing/subscribers/{lead_id}

Delete one lead for good.

Needs the Admin or Owner role. Only the lead row goes: the customer with that address, their consent and the suppression list are not touched, so an address that unsubscribed stays unsubscribed. 404 for an id that is not this organization's lead. Audited as subscriber.deleted with the lead's id and source, never its address.

GET /api/v1/orgs/{org_slug}/staff/marketing/tags

The tags the storefront loads, and what an editor needs to draw them.

Needs the Admin or Owner role. tags holds the platforms that are on, each with the public ids saved for it; a platform with no id is off and absent. kinds lists every platform with its label, a sentence about it and its fields (key, label, hint, pattern, example), so a form can be drawn from it. consent says whether the storefront shows its cookie banner and which page the banner links to. legacy_google_analytics is true while the Google Analytics ID shown still comes from the older single setting, which the next save replaces.

PUT /api/v1/orgs/{org_slug}/staff/marketing/tags

Replace the tags the storefront loads with the ones sent.

Needs the Admin or Owner role. tags is the whole object: a platform left out is turned off. Each id is trimmed and checked against the shape its platform uses, and a platform with no id is left out. The answer is the one GET gives, with changed listing the platforms that differ from before. A bad id answers 422 with detail, the sentence to show, and field, the input it belongs to (meta.pixel_id). Saving what is already stored changes nothing. Every change is recorded in the audit log with the ids before and after. Tags apply to new page loads within a minute.

application/json (required)