Reacher

Every halo channel on one contiguous date axis: TikTok views and GMV, Amazon revenue, Shopify revenue, branded-search volume and click share. ``dates[i]`` indexes every other array, so the arrays can be plotted or diffed element-wise without re-joining on date. A ``null`` means no data for that day; a ``0`` means a real zero — the distinction is preserved deliberately, and channels the shop hasn't connected are null throughout. Pass ``amazon_asins`` / ``shopify_product_ids`` to scope revenue (and branded search) to specific products; omit them for shop totals. TikTok points are only daily-resolved for the most recent ~30 days — beyond that TikTok's stored series is monthly-bucketed and cannot be aligned to days, so ``tiktok_views`` / ``tiktok_gmv`` come back null for the out-of-coverage tail while the revenue series stay complete. Defaults to the last 30 days ending yesterday; max 366. Single-shop only.

halo_timeseries_halo_timeseries_post

Scrape the brand's website and extract a brand profile — name, voice descriptors, target audience, categories — and store it for the shop. This is what `PUT /image-briefs/brand-voice` depends on: a shop that has never had brand analysis run 404s there until this endpoint has created the profile. After it runs, brand voice is populated (and can be overridden with the PUT). It scrapes the site and runs an LLM, so it is a write: it needs `read_write` scope, counts against the write rate limit, and the shop's existing profile is returned as-is unless `refresh: true` (a shop has one profile). A required `Idempotency-Key` makes a retry replay rather than re-scrape; `X-Dry-Run: true` validates without scraping. Single shop only.

image_brief_analyze_brand_voice

Applies a batch of video ids across every campaign the chosen `scope` resolves to. Returns a `job_id` IMMEDIATELY — a wide sweep costs one full re-aggregation per campaign and would outlive the request otherwise. Poll `GET /campaigns/{campaign_id}/content/exclusions/jobs/{job_id}` for progress. The job RE-RESOLVES the targets rather than trusting a preview: minutes can pass between preview and apply, and in that window a creator can be removed or another manager can exclude the same video. Same `scope` semantics and reason/note rules as the preview and single-exclude calls. Requires `read_write` scope and an `Idempotency-Key`; `X-Dry-Run: true` echoes the intended job without enqueuing it.

campaign_bulk_exclude_videos

Sets `status='archived'` — preserves the row in list/detail views but marks it as no longer active.

archive_campaign_campaigns__campaign_id__archive_post

Soft-deletes a CampaignCreatorMapping's content tracker so it no longer surfaces in campaign content lists.

archive_tracker_campaigns_content_archive_post

Archive one share link. The uuid stops resolving immediately, so anyone holding the URL loses access — this is the revoke button. Archiving frees the shop to create a new link, which gets a fresh uuid and a fresh password rather than reviving the archived one's settings. Use `PATCH ... {status: inactive}` instead if you only want to pause a link you intend to bring back. Returns 404 if the link does not exist or belongs to a shop this key does not cover. Requires `read_write` scope.

shared_dashboard_delete

Message TEMPLATES configured on one automation: TC invite text, ordered DM sequence, follow-ups, AI chatbot Q&A. Placeholders not substituted. For the text actually sent per creator, use the sent-messages tool. Single shop.

automation_messages_automations__automation_id__messages_get

Shop-level overview of your automations: ``total_automations``, ``live_automations``, ``archived_automations``, and the split between ``regular_automations`` and ``email_automations``, plus three breakdowns — ``by_type`` (Target Collab, Message, Email, Sample Request Processing, …), ``by_status`` (running / stopped / completed / …) and ``by_type_and_state`` (each type split live vs archived) — and an aggregated ``metrics`` block rolled up across the shop's automations. This is the portfolio view; use ``POST /automations/list`` for the per-automation rows behind it. Pass ``crm_only=true`` to count only automations backed by a CRM group. Single-shop only.

automation_stats_automations_stats_get

Benchmark your shop against TikTok Shop ecosystem peers in your GMV segment. Includes funnel comparison and content-unfulfilled metrics.

get_insights_overview_social_intelligence_insights_overview_get

Amazon branded search is the cleanest halo signal there is: nobody searches a brand by name unless something put it in their head, and on TikTok-driven brands that something is usually a video. This returns the daily branded-search volume and click share for the window, the window totals, the peak day, and the Pearson correlation against TikTok views at the requested ``lag_days`` — the same regression the analysis endpoint runs. ``top_search_terms`` is always null: Amazon reports branded-search volume per ASIN per day, not the query strings, so there is no term list to return. The field exists so it can be filled later without a breaking change. Pass ``asins`` to scope to specific products; omit for every tracked ASIN. An empty ``series`` means branded search isn't tracked for this shop (check ``branded_search`` on ``GET /halo/channels``). Single-shop only.

halo_branded_search_halo_branded_search_post

The creator's per-brand breakdown — every seller they have posted for, with `videos`, `gmv`, `unitsSold`, `avgViews` and `latestVideoAt` for each. The competitive-overlap view: who else is already working with this creator, and how well it is going. Pass `days` to window relative to the creator's most recent post, or `search` to filter by brand name. `total` is the full brand count, not just the current page.

si_community_creator_brands

What the CUSTOMER paid for each order x SKU, as opposed to what the seller earned: subtotal before and after discount, which party funded each discount, shipping, retail delivery fee and tax. Paired to order lines on (order, SKU) to get a paid date, since this sheet carries none of its own. TikTok does not guarantee that pairing is 1:1, so a payment row with no matching order line falls outside the window rather than being invented into it.

pnl_customer_payments

The values you can actually filter the CRM v2 pipeline by for this shop — the products, sourcing automations, CRM tags and status tabs that exist in its data, plus the bounds of each metric range. Call this once to build a filter UI or to discover valid `product_ids` / `automation_ids` / `tags` before querying `/funnel/v2/requests`. Single-shop, CRM v2 shops only.

funnel_v2_filter_config

How many sample requests sit in each pipeline tab — `toReview`, `readyToShip`, `shipped`, `pendingContent`, `completed`, `cancelled` — under the filters you pass, plus the overall `completionRate`, the shop's `approvalTarget` (limit and used), `archivedCount`, `expiringCount` and a `dataFreshness` stamp. This is the tab-badge row above the board. Every tab count INCLUDES requests hidden because the creator is archived, so the funnel matches TikTok's Affiliate Center. `archivedCounts` breaks that hidden share down per tab, and `archivedCount.total` is the hidden request count overall. With `show_archived=true` the archived rows are counted as visible, so `archivedCounts` comes back zeroed; to list them, pass the same flag to `/funnel/v2/requests`. Accepts the same filters as `/funnel/v2/requests` (the counts respect them), so you can ask 'how many are in each stage for this product / date range'. Single-shop, CRM v2 shops only.

funnel_v2_counts

The headline metrics above the Sample Requests board: `pendingReview` (count plus how many expire soon), `approvedInAutoProcess` (count with period-over-period `changePct` and `changeDirection`), `completionRate`, and `approvalTarget` progress against the shop's sample-approval limit, with a `dataFreshness` stamp. `pendingReview.count` INCLUDES requests hidden because the creator is archived, so it matches TikTok's Affiliate Center; `expiringSoon` and `completionRate` stay over the visible rows, which are the ones you can act on. Accepts the same filters as `/funnel/v2/requests`. Under a `sku_ids` filter, `notScopableBySku` names the metrics that could not be narrowed — `approvalTarget`, whose limit and used counters are product-grain — so treat those as unscoped rather than filtered. Single-shop, CRM v2 shops only.

funnel_v2_metrics

The paginated sample-request pipeline for one shop — the rows behind the Sample Requests board. Each row carries the creator (handle, followers, level, rising-star / fast-growing signals, CRM tags), the product, the request's status and timestamps, and the creator's performance metrics (post rate, PPS score, average views, engagement rate, GMV per sample, videos per sample). Filter by pipeline tab (`status`), product, SKU, creator profile, sourcing automation, tag, date range, free-text `search`, and any of the metric ranges (`min_*` / `max_*`). `product_ids` and `sku_ids` are AND-ed: passing both narrows to those SKUs rather than widening. `show_archived` returns the archived board instead; `show_expiring` narrows to requests about to expire. Response also reports `archivedCount` (requests hidden because the creator is archived), `expiringCount`, `lastUpdatedAt` (when this shop was last observed on TikTok; `null` if never) and a `dataFreshness` stamp. Single-shop only, and only for shops on the CRM v2 pipeline — others get a 404 and should use `/samples`.

funnel_v2_requests

Cancel a pending usage-rights request (status `requested`, `accepted`, or `pending_payment`). No-op-safe: cancelling an already-terminal record returns 409. Requires `read_write` scope and an `Idempotency-Key`. Single shop only.

usage_rights_request_cancel

The most-viewed videos across the product categories this shop sells in, from `customers.sc_top_viewed_videos` — competitive intelligence, **not** the shop's own content (for that use GET /videos). Each entry carries the video's rank and rank change, the creator's public handle, the view bucket TikTok reports (`views_min` / `views_max` — TikTok does not publish an exact count here) and the product the video links to, with its price range and rating. No date window: the latest collected snapshot is returned, and its range is echoed as `start_date` / `end_date`. Collection is currently paused upstream, so the response reflects the last snapshot collected for the shop. Single-shop only — set `x-shop-id` to a specific shop ID. An empty result is a normal 200 response: Seller Center collection is per-shop and still rolling out.

seller_center_trending_videos

Remove every creator from this shop's blacklist in one call, making all of them eligible for outreach again. There is no undo — the rows are deleted, not archived, so read the list with `GET /shops/blacklist` first if you may need to restore it. Clearing an already-empty list is a no-op that returns `removed_count: 0`. Requires a key with `read_write` scope and a single shop.

shop_blacklist_clear

The retention grid for one shop: creators grouped by the month they first posted (rows), tracked across month-offsets M0..M6 (columns). Each cell carries raw counts — ``posted`` (creators who posted), ``gmv_count`` (creators who drove GMV) and ``total_videos`` — so a consumer derives % Posting / % Driving GMV / videos-per-creator itself. Omit ``product_id`` for the latest all-products snapshot, or pass one to live-aggregate that product's cohorts. Single-shop only.

cohort_grid_cohorts_grid_get

Ecosystem-wide profile for one creator by TikTok handle: name, avatar, TikTok URL, region, content categories, and windowed `performance` (GMV, average views, shop posts, engagement rate, followers). This is the community view — what the creator does across all brands, which is the only view that exists for creators you have never worked with. For their history with *your* shop, use the CRM endpoints.

si_community_creator_detail

Community/hashtag autocomplete for the `community` filter: the hashtags creators in your region actually post under, with per-hashtag creator counts. Omit `q` for the region's top communities; pass `q` to substring-match (leading '#' optional, case-insensitive). Feed the returned hashtag values into the `community` filter on creator search for topical targeting (e.g. 'find creators in the fitness community'). Answers 'which communities / hashtags can I target'.

ai_search_hashtags

Every creator tracked in your region's TikTok Shop ecosystem — not just your affiliates. Each row carries the profile (handle, name, avatar, follower count, content categories) and windowed performance (GMV, average views, shop posts, engagement rate) over a 1-, 7- or 28-day window. `isMyAffiliate` marks creators already in your CRM; set `hide_my_affiliates=true` to return only new prospects. Results are capped at 1000 rows — `capped: true` with `totalMatching` above that means you should narrow with `search` / `category` before paging.

si_list_community_creators

Whether Reacher is still collecting for a shop, so a consumer can tell **"this shop genuinely had no activity"** from **"we stopped collecting for it"** — the two look identical on every other endpoint. `is_collecting` is the one-field answer; `failure_reason` explains a false (banned / account_dead / shop_punished / permission_denied / affiliate_access_missing / login_issue) and `onboarding_status` covers shops that never finished setup. `region_supported` is false for shops in a region Reacher does not operate in — those never collect at all. `shop_id` must be one of your own shops. Send `x-shop-id: all` to poll any of them without re-issuing the request per shop.

shop_connection_health_shops__shop_id__health_get

TikTok's bottom line carried down by the costs it cannot see. ``net_earnings`` is taken from the daily series unchanged — the only source that includes GMV Max ad spend — and cost of goods and sample cost are subtracted from it. Set ``cadence`` to get the running series as well as the totals. Units with no cost on file are COUNTED, never assumed to be zero, so ``contribution_profit`` is an upper bound while ``units_uncosted`` or ``sample_units_uncosted`` is non-zero. Use ``POST /pnl/costs/coverage`` to get the list of what is missing.

pnl_profit

Create a Direct Message automation. The `mode` field selects the variant: - mode='vanilla': just a text message addon in messages[] - mode='with_image': message + image addon (requires image addon in messages[]) - mode='with_product_card': message + product card addon (requires product_card addon) - mode='spark_code': spark code collection form (requires spark_code_form addon + dm_config.spark_code). MESSAGES vs FOLLOW_UPS: `messages` is the initial outreach (all items dispatched together when the automation engages a creator). `follow_ups` is a separate optional array of delayed steps (each step has `delay_days` + 1-5 addons). Multi-touch sequences require both arrays. REQUIRED: schedule, creators_to_include, messages array, shop, idempotency_key.

automation_create_dm

Create an outbound email automation. DIFFERENT recipient model from outreach — use `selection_mode: mailing_list` (with vault list IDs in `mailing_list.lists_selected` OR upload emails inline in `mailing_list.list_upload_emails`) OR `selection_mode: filters` (creator-search criteria). REQUIRED: email_account_id (an account MAY back several active email automations; reuse deliberately, since each one adds to that inbox's daily send volume and the daily cap is applied per automation), subject, body (HTML or plaintext), selection_mode + matching mailing_list/filters, shop, idempotency_key. NOT SUPPORTED in v1 (extra='forbid' rejects them with 422): `schedule`, `end_date`, `email_sent_per_day`. The underlying `email_automations` table has no columns for them; timing is governed by portal-level defaults (one cycle per `next_run_cycle`). v1.1 will add columns + expose these fields. PATCH/start/stop/delete are also unsupported (501 EMAIL_LIFECYCLE_NOT_SUPPORTED) — email lifecycle is portal-only in v1.

automation_create_email

Auto-approve OR auto-reject incoming TikTok Shop sample requests by performance criteria. Side-effect: backend internally creates a CRM Group from `minimum_performance_criteria` so creator membership stays dynamic — the new crm_group_id is returned in `side_effects`. REQUIRED: sample_request.action (approve/reject), products (caps + items OR include_all), minimum_performance_criteria, target_list (vault list IDs — sample_request uses target_list for creator selection, NOT creators_to_include), shop, idempotency_key. If action='reject', also set rejection_reason (NOT_MATCH / OFFLINE / OUT_OF_STOCK / OTHER).

automation_create_sample_request

Create a TC Cleanup automation — re-targets creators in this shop who received a prior TC invite but didn't accept. Structurally lean: PRODUCTS + creator selection only, no `messages` / `follow_ups`. Use `invite_start_before_days` / `invite_expire_after_days` to scope which unaccepted invites qualify (e.g. start_before=30 + expire_after=7 = creators whose invite was sent 30+ days ago AND is expiring within 7 days). REQUIRED: products (≥1 with commission_rate), schedule, creators_to_include, shop, idempotency_key. Stamps `automation_type='TC Cleanup'`.

automation_create_tc_cleanup

Create a Target Collab (TC) invitation automation. Optional follow-up DMs via `messages` (each step has `addons` like message text, image, product card). REQUIRED: target_collab.products (≥1 with commission_rate), schedule (≥1 day active), creators_to_include with list_upload OR lists_selected, shop. ALWAYS supply unique idempotency_key (UUID v4). Use dry_run=true to preview. Example: see api-docs/automation-management.md → Target Collab + Message section.

automation_create_target_collab

Create a reusable CRM Group from a dashboard segment — a GMV tier, an automation, and a date window — then target or exclude it in automations. Use for 'make a group of the L3 creators automation 812 reached last month'. You cannot build a group from arbitrary filter conditions through this API; only these segment dimensions. IMPORTANT: after creating, compare creator_count (what actually went into the group) against handles_resolved (what the segment matched). Only creators with an existing CRM record can be grouped, so DM-only and organic creators drop out and creator_count is often far below handles_resolved — report the group's real size as creator_count, not handles_resolved. dry_run=true checks the segment size and the group-size limit but CANNOT show that drop-off. Membership is a snapshot frozen at creation, NOT live: re-run this tool to refresh it. Reusing an existing group_name overwrites that group and replaces its members. Requires idempotency_key.

crm_group_create_from_segment

Create a new creator brief for the shop — a `search_query` plus optional demographic `filters` — and resolve it immediately, so the response carries the `creator_count` it matched. The brief is created with `source: user_created` and shows up in `GET /discovery/profiles` right away. The stored `title` is regenerated from the query and filters rather than kept verbatim, so read it back from the response instead of assuming what you sent. Requires `read_write` scope and an `Idempotency-Key` header — a replay of the same key and body returns the original 201 rather than creating a second brief. Single-shop only.

discovery_create_profile

Create a new automation that watches the selected campaign(s) and fires creative boosts when its conditions match. Requires ``read_write`` scope. Idempotent via the ``Idempotency-Key`` header — replays of the same key + same body return the cached 201 instead of creating a duplicate row. ``X-Dry-Run: true`` validates the body and echoes the would-be row without touching the DB. Single shop only — set ``x-shop-id`` to the owning shop. Every ``set_up_creative_boost`` action requires a ``total_creative_boost_cost`` guardrail (lifetime spend cap) — missing one returns 422 ``TOTAL_BUDGET_CAP_REQUIRED``. Each campaign_id can only belong to one active automation at a time — conflicts return 422 ``CAMPAIGN_ALREADY_ASSIGNED``.

create_automation_gmv_max_automations_post

Create a new GMV Max (TikTok Smart+) campaign on the shop's connected TikTok Business ad account. Requires ``read_write`` scope. Single shop only — set ``x-shop-id`` to the owning shop. The canonical body is mapped to TikTok's create payload server-side (``daily_budget``→budget, ``target_roas``→ROAS bid, ``product_selection``→ALL / CUSTOMIZED_PRODUCTS, etc.). The shop must already be connected to TikTok Business / GMV Max — an unconnected or incomplete connection returns 400 ``INVALID_REQUEST``. Idempotent via the ``Idempotency-Key`` header — replays of the same key + same body return the cached 201 without creating a duplicate. ``X-Dry-Run: true`` validates the body + connection and echoes the exact TikTok payload without calling TikTok.

create_gmv_max_campaign

Create a Retainer / Challenge / Leaderboard / Live GMV Challenge campaign. `X-Dry-Run: true` validates the body and echoes what would be submitted without writing any rows. Image fields take HTTPS URL strings — host the image yourself and pass the URL. The 201 response includes an `invite_link` field — the public URL the caller can share with creators to bring them into the campaign. Subdomain is picked by `creator_source`: legacy `social_army` campaigns use `https://soco.reacherapp.com`; everything else (`my_community`, etc.) uses `https://creator.reacherapp.com`. Full pattern: `{base}/campaigns/{shop_id}/{uuid_id}`. Every campaign endpoint that returns a campaign payload carries the same field — POST, GET list, GET single, GET detail — so callers can lift it directly without constructing the URL themselves.

create_campaign_campaigns_post

Upload a list of creator handles + emails. Two paths: (1) JSON body with {name, description?, creator_handles: [...], creator_emails: [...]} — convenient when you have data structured. (2) Multipart CSV: file part `file` (csv with `creator_name` column required + optional `email` column) + form fields `name`, `description`. Returns list_id which you pass to automations as creators_to_include.lists_selected. Requires idempotency_key.

list_create

Creates a micro-challenge ('weekend blitz') under a parent Leaderboard (contest) campaign — a short scoring window with its own pricing and its own board. Two shapes, discriminated by `schedule.mode`: * `one_off` — an explicit `start_at`/`end_at` window (shop-local); materializes an instance immediately. * `recurring` — a weekly window (`start_dow`/`start_time` → `end_dow`/`end_time`, day 0 = Monday, shop-local); creates a TEMPLATE that the daily materializer turns into instances. Use `POST /micro-challenges/preview-window` to see the next window a draft recurring schedule would produce. Rejected when the parent isn't a running contest campaign, when it is itself a micro-challenge (no nesting), or when the parent already has the maximum number of ACTIVE templates (409). Requires `read_write` scope and an `Idempotency-Key`; `X-Dry-Run: true` validates the shop/campaign and echoes the payload without creating anything.

campaign_create_micro_challenge

Mint a password-protected, publicly-reachable dashboard link for the shop — the thing a brand sends an agency or an investor. The response carries the `uuid` and the `share_url` to hand out; the password is never echoed back, so store what you sent. One live link per shop: creating a second while one is active returns 409. Archive the old one first with DELETE, which mints a fresh uuid and password on the next create rather than resurrecting the old link. Optionally lock the link to a fixed reporting window (`locked_start_date` + `locked_end_date`, both or neither) and choose what it shows via `report_config`. Outreach-volume metrics — TC invites, DMs sent, creators reached, sample counts — cannot be put on a share link and are rejected. Requires `read_write` scope and an `Idempotency-Key` header. Single-shop only.

shared_dashboard_create

Save an image brief as a draft — typically the content returned by `POST /image-briefs/generate`, but any content is accepted. Up to 3 products; index 0 is the hero. Omit `name` and the brief is named after its headline. `Idempotency-Key` is required so a retry doesn't leave you with duplicate drafts. `X-Dry-Run: true` validates without saving.

image_brief_create

Create the auto-approval rule for one product. Requires `read_write` scope and a single shop. `productId` must not already have a config in this shop — a duplicate returns 409 `PRODUCT_CONFIG_EXISTS`; use `PUT /samples/product-config/{config_id}` to change an existing rule. `idealCreatorProfileIds` that don't belong to this shop are dropped rather than linked.

samples_product_config_create