Reacher connects ChatGPT to your TikTok Shop affiliate program. Ask about GMV, creators, videos, samples and campaigns in plain language and get answers from your live Reacher data instead of a dashboard. Find creators across the open TikTok market, see who is actually driving sales, review sample requests and automations, and pull the numbers behind a weekly report — for one shop or all of them. Write actions such as creating an automation or replying to a creator are labelled and confirmed before they run, and money movement is not available through ChatGPT.
CampaignCreatorMapping.status='active'. Sends an acceptance email + SMS to the creator (fire-and-forget) — these are SKIPPED on X-Dry-Run: true.amount is in the minor units of the customer's Stripe billing currency (the currency itself is not carried on this surface). invoice_pdf links are Stripe-hosted and time-limited. Account-scoped: invoices bill the account, not an individual shop, so the result is the same for any x-shop-id.limits is category → limit type → value; the types are typically default (what a new automation is created with), minimum and maximum (the enforced ceiling). A category missing for a tier means the plan expresses no opinion, not a limit of zero. Covers every shop in x-shop-id — send all for the whole account.plan, unit_amount (minor units), status, the live stripe_status, current_period_end, trial_end, cancel_at and access_expires_on — the cancel-grace date after which a canceled seat stops granting access. Only seats linked to shops this key can reach are returned, plus any unassigned seats (which name no shop). Read collection_method and attempt_count before treating past_due as a payment failure: invoice-billed customers sit in past_due legitimately, and attempt_count == 0 means Stripe never attempted a charge. Read-only — plan changes and cancellation are portal-only.x-shop-id; the TARGET shop + campaign are in the body. Restrictions: - Region — the target shop must be region-compatible with the source shop. GLOBAL and US are interchangeable; every other region must match exactly. Mismatch → 409. - Same customer — the target shop must belong to your API key's customer (cross-customer target → opaque 404). - No double-add — if the creator is already ACTIVE (or paid/completed) in the target → 409. A passive/terminal-inactive mapping (viewed/pending/invited/applied/removed/rejected/archived/withdrawn) is UPGRADED to active with NO duplicate row (pg_advisory_xact_lock guards it; a paid_at row is never overwritten). Rewards are recomputed server-side from the TARGET campaign. notify (default true) sends the creator an acceptance-style notification — SKIPPED on X-Dry-Run.commission_paid_at fill in as TikTok settles, typically weeks later, so recent windows keep moving — read data_status` for freshness. Defaults to the last 30 complete days.profile is always true; transcript/video/lookalike auto-enable per region as their data finishes backfilling. Call this BEFORE offering the transcript / video / lookalike search tools so you don't pitch a mode the region can't serve yet. Single shop only.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'.status='archived' — preserves the row in list/detail views but marks it as no longer active.status and search` filters the portal does. Single shop only.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.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.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).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.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'.target_collabs / Messages / skipped_creators tables, so it stays populated even after the aggregate creators_reached / skipped counters on the list/detail responses age out (those read from a stats view that only retains recently-active automations). Queued ≠ delivered. An invite_submitted / outreach_sent outcome means Reacher's worker submitted the invite/DM through the same browser-automation path the portal uses. TikTok does not return a per-creator inbox-delivery receipt, so this is the most authoritative delivery signal available — not a confirmed inbox event. Requires a single shop.read_write scope and an Idempotency-Key.GET /automations/outreach-capacity — so a consumer can pre-check before queuing email outreach and schedule the remainder for tomorrow. emails_sent_today counts today's sends; daily_limit is the denominator the portal's daily-send bar uses, derived from the shop's effective plan entitlement. tier_limits is that entitlement in full (default / minimum / maximum, Extra Limits grants applied). Note the enforced cap is per email automation, stored on the automation itself and clamped into this range when it is written — so a shop running several automations can exceed daily_limit in aggregate. A null field means the tier expresses no such limit, not zero. Requires a single shop.creators_to_include.filters values before submitting a create request. Region differences: Numeric ranges use the region's currency (`£` for UK, `$` for US, `€` for EU regions, `R$` for BR, etc.). Category lists differ — UK has a smaller category set than US. AI-search filters (face_visibility / content_style / personality_tone / etc.) are only fully populated for US today; other regions surface a subset. Ethnicity filter is available globally regardless of region. Supported regions: US, UK, IE, MX, DE, FR, ES, BR, IT, GLOBAL (alias for US).tab_counts carries the creator-tracker, sample-request and video counts (the tracker count already excludes creators on the automation's current omit lists, so it matches the tab it labels). top_line_metrics carries creators_reached, dm_response_count and reply_rate, unique_creators_posted and post_rate, videos_count, total_revenue (GMV), and total views / shares / likes. **Check data_available first.** It is false when the rollup aggregator has not yet computed a row for this automation — the zeros are then 'not computed yet', not 'nothing happened'. top_line_metrics is null for automation types that have no full-funnel view (is_full_view: false`). Single-shop only; the automation must belong to that shop or this returns 404.outreach_quota for the consumption, ceiling and refresh instant. It counts connections shop-wide, so it includes outreach not sent through Reacher. Most shops are on a weekly PERIOD quota; some hold a BONUS grant that does not roll, so check outreach_quota.quota_type before calling it weekly. Null when the shop has no synced quota — null means unknown, never zero. weekly_limit_throttled flags when paused by the limit. The daily pool is shared between the automation engine and direct POST /target-collabs invites. Requires a single shop.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.job_id (a reload, a crashed worker) can rejoin it instead of re-uploading. data is null when nothing is running. Read-only.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.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_id / campaign_name for context. Discord is creator-provided and optional; by default only creators who have linked a Discord account are returned. Set with_discord_only=false to include creators without one (discord_handle and discord_user_id will be null). By default every currently-linked creator is returned except those rejected / removed / withdrawn from a campaign; pass active_only=true to restrict to creators accepted into a campaign (active or settled). Single shop only.read_write scope and an Idempotency-Key; X-Dry-Run: true reports what would be deleted without deleting it.x-shop-id. For multi-shop callers, use the /campaigns` list endpoint to discover which shop owns a campaign before requesting its detail.reasons code is required and a note is mandatory when the reason is other, because the reason reaches the creator. Rejected with 409 when the campaign's results are already final, or when it is a LIVE campaign (scored from live sessions, which can't be excluded individually). Requires read_write scope and an Idempotency-Key; X-Dry-Run: true echoes the intended change without writing.is_terminal. Poll until is_terminal is true. Read-only.active/paused status) alongside the INSTANCES already materialized from them plus any one-off windows. Read-only.x-shop-id (a comma-separated list or all), the campaign's owning shop is resolved automatically and metrics are returned for that shop.scope defaults to campaign (act only on this campaign, what a brand expects from a button on one campaign's Content tab). scope: shop is the opt-in that also resolves every OTHER campaign the video appears in — far more destructive, so it is never implied. Always preview a shop-scoped batch before applying it. Read-only, but gated on read_write scope: it is the first step of the bulk-exclusion write flow and reveals exactly what that flow would change. No Idempotency-Key needed (nothing is written).start_dow/start_time → end_dow/end_time, day 0 = Monday) against the shop's timezone and returns the next concrete window it would produce — so a caller can confirm the window before creating a template. Shop-scoped, NOT campaign-nested: the create flow has no campaign yet when the schedule is being drafted. The shop comes from x-shop-id; a shop_id in the body is ignored. Writes nothing, but gated on read_write scope as the first step of the micro-challenge create flow. No Idempotency-Key needed.read_write scope and an Idempotency-Key; X-Dry-Run: true echoes the intended change without writing.currency). Use for 'which creators drove the most ad revenue', 'commission owed per creator'. Single shop only.start_dow/start_time/end_dow/end_time, or an equivalent nested schedule object), pricing, excluded creators, or status: paused to stop it producing new instances. Affects FUTURE instances only: windows already materialized are never rewritten. When a not-yet-started instance exists for the template, it is returned as already_scheduled_instance so the caller can see what the edit did not touch. Ownership is enforced on the full (template, campaign, shop) triple — a template id from another campaign 404s. Requires read_write scope and an Idempotency-Key; X-Dry-Run: true echoes the patch without applying it.creators_sourced and share` of the cohort. Single-shop only.direction=active returns the creators who qualified at that offset (the cell's numerator); direction=lapsed returns the cohort members who did NOT — the re-engagement target list. Capped at 500 rows (capped` flags truncation). Single-shop only.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.window_days`. Buckets genuinely shift with the window. Single-shop only.source=cohort_cell) or a repost bucket set (source=repost`) — to the underlying creator handles, for exporting or piping into outreach. Single-shop only.total_count / sent_count / failed_count, every envelope in the batch, and a failures list naming the creators whose delivery failed and why. Poll this after a batch is sent from the portal to watch it drain. 404 when the batch does not belong to this shop. Single-shop only.terms the document was rendered from (deliverables, reward structure, usage rights, dates), the signing status, and brand_signed_at / creator_signed_at — null until that party signs. last_error carries the delivery failure reason when status is delivery_failed. 404 when the contract does not belong to this shop. Single-shop only.terms snapshot the document was rendered from, the signing status and both signature timestamps. Filter by status (draft/sent/active/expired/voided/delivery_failed), by creator_id, by campaign_id, or by expiring_within_days to find active contracts about to lapse. status=expired and expiring_within_days are mutually exclusive — expiry is evaluated lazily against today's date, so asking for both is contradictory. Cursor-paginated: pass the next_cursor from the previous response to get the next page. A null next_cursor means the last page. Single-shop only.next_cursor from the previous response to get the next page. A null next_cursor means the last page. Single-shop only.text/html rather than JSON. This is the rendered document body — use it to display or archive the exact terms the creator was shown, without going through a signed URL. Signature blocks are part of the PDF, not this snapshot; fetch the countersigned copy from /download. 404 when the contract does not belong to this shop, or when the document has not been generated yet. Single-shop only.next_cursor from the previous response to get the next page. A null next_cursor means the last page. Single-shop only.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`.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.text (or message), image_url (https) or product_id (from this shop's catalog). Nothing reaches the creator: the draft is saved on the conversation, appears in the Reacher inbox for review, and expires after 30 days. This is step one of replying — show the returned draft to the user, and only after they approve call the send-draft tool with its id. The creator must already have a conversation with the shop (TikTok does not allow cold DMs). Single shop only.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.brief_content) plus its flattened sections, the inspiration videos with their order counts, and the shop's brand colors and logo. Image URLs are re-signed on every read, so use them promptly rather than storing them. Read-only.drafted brief and return it. Each call is a fresh generation that spends model tokens and creates a new brief row, so Idempotency-Key is required: a retried request replays the first result instead of paying for and storing a duplicate. Send X-Dry-Run: true to validate the product without generating. Returns 404 when the product isn't in this shop, and 422 when the product has no analyzed videos to build a brief from — run video analysis first.{"url": null} when the product has no published brief (a drafted or archived brief is not shareable). Read-only.status. Set status: published to make it shareable (its URL is then available from GET /creative-briefs/published-url), or archived to retire it. This is a replace: the stored document is rebuilt from the body, so send the whole brief back with your edits, not just changed fields. Two things happen automatically on save: inspiration videos missing key_points get them AI-generated from that video's analysis, and videos missing an orders count have it filled from our attribution data. Idempotency-Key is optional here (a replace is naturally repeatable); X-Dry-Run: true validates without writing.last_opened_at is the last time the brief was opened in the portal, or null. Read-only.material_id. Date range may not exceed 90 days (inclusive); defaults to the last 30 days. Multi-shop is supported — the campaign's owning shop is resolved automatically from x-shop-id.gmv and videos_posted on summary_metrics_summary, which cover the whole shop. Don't present the two as the same number or treat a difference between them as an error. Covers the whole shop — there is no filter parameter, so don't reach for this to answer a question about a subset of creators; use creators_performance for ranked per-creator numbers instead. No prior-period comparison is returned: to compute change, call twice with adjacent windows and subtract. Requires a single shop_id. A 503 means the aggregate timed out — wait a few seconds and retry rather than reporting failure.week_ending), matching how weekly client reports are cut. A week with no activity is still returned, as zeros. All eight tiers L0-L7 are always present. A creator's tier comes from their ALL-TIME platform-wide GMV — the same basis as the Top Creators level badges — not from the GMV attributed inside the window. The gmv field on each row IS the windowed figure. touches is outreach messages: three DMs to one creator counts three. reached is distinct creators. Single shop only — set x-shop-id to one shop ID.days axis: index i of any array is the value for days[i], oldest first. Creators with no activity come back zero-filled rather than missing; handles that don't exist in the shop are listed in unresolved_handles. Defaults to the trailing 28 days, max 365. Requires a single shop_id.views, likes, comments and paid_orders_count — the attributed-order count TikTok reports for that video. Reads analytics.crm_content_data, the same source behind the portal's expanded creator row. creator_id is required (this is a per-creator drill-down, not a shop-wide content feed — use GET /videos for that); narrow further with product_id. Ordered newest first. Product titles are not returned: the underlying join resolves a single title per creator rather than per product, so it would be wrong on any creator working on more than one. Join product_id against GET /crm/creators for titles. Single-shop only. Creator contact details are never returned: no real name, shipping address, phone or email. creator_name is the public TikTok handle.creator_id is the value from GET /crm/creators. The profile is resolved through the creator's handle, so it spans every creator_id the CRM, content and affiliate syncs filed the creator under — a creator whose content landed under a second id still reports their full video GMV here. Inferred demographics (gender, age range, ethnicity, likely location) shown in the portal are omitted. Single-shop only. Creator contact details are never returned: no real name, shipping address, phone or email. creator_name is the public TikTok handle.customers.crm_creator_status_history — each row is a previous_status → new_status move with the timestamp the sync detected it, plus display labels for both. Use it to measure how long creators sit in a stage, or to reconstruct when a sample was approved, shipped or went unfulfilled. The grain is (creator, product): a creator collaborating on three products has three independent transition chains, so filter by product_id to follow one. Ordered newest first. Single-shop only. Creator contact details are never returned: no real name, shipping address, phone or email. creator_name is the public TikTok handle.status, lifetime and 28-day GMV, commission, fulfillment, video and live counts, and CRM tags. Filter with any combination of status (repeatable display labels), stage (a canonical funnel stage, which overrides status), product_id, tags (creator carries ANY) and tags_all (carries ALL), plus creator_handle for a case-insensitive handle search. Sort with sort_by / sort_dir; the default is GMV descending. start_date/end_date window the metric columns (video_gmv, total_video_views, videos_posted) — pass both or neither. Status, tags and lifetime gmv are always as-of-now. Set include_products=true to attach each creator's product cards (title, image, status, remaining sample stock). Per-product GMV and the videos themselves are deliberately not attached — they are the two heaviest reads in this surface; fetch them per creator from GET /crm/content. Changed 2026-09: the roster returns every creator filed under this shop. It previously dropped anyone whose row in Reacher's global creator registry had been marked inactive — an outreach-side, cross-shop flag that hid creators this shop had earned GMV from. Expect more rows than before on shops with long CRM histories; no field or filter semantics changed. Single-shop only. Creator contact details are never returned: no real name, shipping address, phone or email. creator_name is the public TikTok handle.creator_id values from GET /crm/creators. Re-adding a tag a creator already has is a no-op; creators_updated counts only rows that actually changed. Requires read_write scope and an Idempotency-Key.tags to remove specific tags, or all_tags: true to clear every tag from the named creators. Removing a tag a creator doesn't have is a no-op. Requires read_write scope and an Idempotency-Key.x-shop-id` to a specific shop ID). Mirrors the portal Dashboard exactly.status='deleted'`). The row remains in the DB but is excluded from list / detail views. Re-deleting an already-deleted automation is a no-op that still returns 200 (idempotent on the row itself). Pending boost rows queued by this automation are cancelled in the background — best-effort, not awaited here. Single shop only.status='deleted'. The row remains in the DB but is hidden from list/detail views. Idempotent.can_post telling you where the Reacher bot can actually post. Use a channel's id as channel_id when posting. 404 if the shop has not connected Discord. Single shop only.scheduled_for — the response is the final sent / failed record. - Scheduled: set scheduled_for. - Recurring: set scheduled_for (first fire) and recurrence (e.g. {"frequency": "weekly", "end_type": "never"}). Idempotency-Key is required so a retry can't double-post. X-Dry-Run: true validates without posting or scheduling. Attach up to 10 images / files via images (each base64-encoded, ≤ 8MB) — e.g. a video-breakdown image.read_write scope. Idempotency-Key is optional (a delete is naturally repeatable); X-Dry-Run: true checks the message exists and is yours without deleting it. Single shop only.upcoming_occurrences lists the next fire times. A message id that isn't this shop's reads as 404. Single shop only.reaction_count, reply_count, audience_count) once delivered. counts totals each tab. Single shop only.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.GET /discovery/profiles but any Vault list already saved from it is untouched — deleting the brief never deletes creators you saved. Returns 404 if the profile does not exist or belongs to another shop. Requires read_write scope. Single-shop only.search_query plus optional structured filters (gender, age, ethnicity, region) — that Reacher either generated from the shop's catalog (source = generated) or a user created by hand. Each row carries id (pass it to the creator listing below), title, description, search_query, filters, creator_count (the size of its last resolved match set), hide_unsafe, is_active, last_search_at and the created/updated timestamps. Hidden and deleted profiles are excluded; has_profiles is false for a shop that has never generated any. Single-shop only. Read-only — creating, editing and deleting profiles is not exposed on the public API.search_query and its structured filters are combined into the search that runs, so this returns exactly what the portal shows under that profile. This is a read — POST only because the optional filters payload is a nested object that doesn't survive a query string. Nothing is created or modified. Paginate with page / limit (max 1000 per page); total_creators is the full match count. Sort by any of: relevance_score, follower_count, gmv_num, avg_views, engagement_rate_segment. Supply filters to narrow the set further without editing the profile. Each creator row carries its handle, follower/GMV/engagement metrics, categories, bio and the relevance_score that ordered it. Creator email addresses are omitted, matching the /ai-search surface. Returns 404 when the profile doesn't exist or belongs to a different shop. Single-shop only.include_emails: true to store the email list alongside the handles, which an email automation needs. Optional filters narrow what gets saved without editing the brief. Every matching creator is saved, not just the first page, so this can take a while on a broad brief. The response reports creators_saved. Requires read_write scope and an Idempotency-Key header. Returns 404 if the profile does not exist or belongs to another shop. Single-shop only.search_query or filters re-derives the stored title and re-resolves the match set, and if the brief already backs a Vault list that list is re-synced. Editing a Reacher-generated brief flips its source to user_created; it is then yours and is no longer regenerated. is_deleted is not settable here — use DELETE /discovery/profiles/{profile_id} — so a PATCH can never silently retire a brief. Returns 404 if the profile does not exist or belongs to another shop. Requires read_write scope. Single-shop only.query you'd give the profile-search tool, OR an explicit creator_ids list (not both); omit both to export your region's full browse universe. Returns a CSV attachment; the X-Creator-Row-Count header reports the row count. Single shop only. Only profile-mode results export — transcript / video / lookalike have no CSV export.GET /funnel: creator_count and percentage_of_funnel, the insights block (unique creators, total entries, conversion rate from the previous stage with its conversion_label, and median days spent in the status), the CRM group_id / group_filters that define the stage, the automation_templates available for it, and the active_automations currently working it. stage_id accepts the stage keys from the funnel overview — e.g. sample-requested, sample-approved, content-posted, content-unfulfilled, gmv-generated, top-creators. Set include_products=true to also get the per-product breakdown of the stage (one row per product with stage-relevant metrics such as creators_in_stage, gmv_generated, avg_views, avg_gmv, spark_code_collected); metrics that don't apply to the stage come back as null. Products are paginated independently via products_page / products_page_size and can be narrowed with product_ids. Single-shop only. Data covers the last 90 days, matching the dashboard.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.product_ids / automation_ids / tags before querying /funnel/v2/requests. Single-shop, CRM v2 shops only.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.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.auto_exclude_enabled: false for shops that have never set it. Single shop only.PATCH /campaigns/{id} accepts.rank, weighted composite_score with a per-metric score_breakdown, and the raw GMV / views / videos / units stats. When the campaign has a currently-live (or recently-ended) micro-challenge, its windowed blitz board is nested under micro_challenge. Standings are paginated; total_creators is the full participant count. Scores come from the same shared scorer the dashboard and public share page use, so ranks agree across every surface. Single-shop only (the shop sets the response currency).field, its old_value and new_value (JSON), and the changed_at timestamp. Empty data is a normal 200. Single shop only.creative_delivery_status into a canonical set (delivering, not_delivering, in_review, rejected, inactive, unknown); NULL or unrecognised statuses bucket as unknown. Sorted by spend descending. Empty data is a normal 200. Single shop only.campaign/gmv_max/info payload into a stable snake_case object: status, target_roas, daily_budget, schedule window, auto_budget_enabled, product_selection, roi_protection_enabled, affiliate_posts_enabled, and placements. Settings TikTok did not report are null. Single shop only — set x-shop-id to the campaign's owning shop. 404 if the campaign is not found in this shop.product_card, affiliate, brand, unknown) over a date range. NULL / unrecognised surface_bucket values bucket as unknown. Date range may not exceed 90 days (inclusive); defaults to the last 30 days. Sorted by spend descending. Empty data is a normal 200. Single shop only.unread_conversations counts conversations; unread_messages sums the unread messages inside them — they are NOT the same. For per-creator unread detail, page GET /conversations?unread_only=true.read_write scope and an Idempotency-Key. Single shop only.handle) from this shop's GMV Max bottom-of-funnel delivery. Idempotent on (shop, handle): re-excluding an already-excluded creator is a no-op upsert that returns the existing row. Requires read_write scope and an Idempotency-Key. Single shop only.handle is the creator's TikTok handle (from GET /gmv-max/excluded-creators). Removing a creator who isn't excluded is a no-op that still returns 200 with removed: false. Requires read_write scope and an Idempotency-Key. Single shop only.video_id, without excluding its creator — use this to cut an unprofitable creative (e.g. zero orders at $10+ spend) while the creator's other videos keep delivering. The reconcile job removes the creative from every active campaign it is delivering in within ~4 hours and verifies it flipped to EXCLUDED. Idempotent on (shop, video_id): re-excluding an already excluded video keeps its current applied_status. Requires read_write scope and an Idempotency-Key. Single shop only. For many videos at once use POST /gmv-max/excluded-videos/bulk.already_excluded, and inputs that are not a numeric TikTok video id come back in invalid (nothing is silently dropped). Each excluded creative comes off spend on the next reconcile (~4h) while its creator's other videos keep delivering. Requires read_write scope and an Idempotency-Key. Single shop only.video_id is the TikTok video id (from GET /gmv-max/excluded-videos). Reacher stops enforcing the exclusion; TikTok does not automatically re-add a creative it has already EXCLUDED, so re-adding it to a campaign is done in Ads Manager. Removing a video that isn't excluded is a no-op that still returns 200 with removed: false. Requires read_write scope and an Idempotency-Key. Single shop only.base_sales is the average daily Amazon+Shopify revenue over the 30 days immediately BEFORE the window (the pre-period run rate). incremental_revenue is the window's revenue minus that run rate carried across the days that have data — the revenue above baseline, and the number to quote as halo lift. It goes negative when the window underperformed the prior 30 days. relationship_strength is the Pearson r between daily TikTok views and daily combined off-platform revenue; views_explain is r squared, readable as 'views explain N% of the day-to-day revenue swing'. **channel_correlations** — the same regression per off-platform channel, each with r, a two-sided p_value (below 0.05 is the usual bar for calling it real) and a plain-English label. TikTok GMV is deliberately absent: it is driven by the same views it would be correlated against, so it correlates by construction and is direct attribution, not halo. It appears under attribution instead. **branded_search_correlation** — TikTok views vs Amazon branded search, the earliest and cleanest halo signal. Null when the shop has no branded-search tracking. **attribution** — raw revenue sums per channel for the window, unmodelled. lag_days shifts TikTok views forward before correlating, so a video today can be matched against an Amazon order three days later; sweep 0-14 and keep the strongest r. Any r is null when fewer than 5 aligned day-pairs have data on both sides, or when a channel is not connected — check GET /halo/channels` first. Correlation is not causation: a strong r with a plausible lag is evidence, not proof. Defaults to the last 30 days ending yesterday; max 366, though TikTok views are only daily-resolved for the most recent ~30 days, so wider windows weaken the regression rather than strengthen it. Single-shop only.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.amazon correlation on a shop with amazon: false is expected, not a failure. amazon / shopify mean an active authorization exists; the matching *_has_data` flags mean rows have arrived. Connected but not-yet-populated is the normal state for the first few hours after a brand links a store. Single-shop only.amazon_asins and shopify_product_ids filters on the timeseries, analysis and branded-search endpoints. Omit channel to get both catalogs in one call; a catalog the shop has no data for comes back as an empty list. There is no TikTok catalog: TikTok halo inputs (views, GMV) are only stored shop-wide, so TikTok is never product-filterable and passing channel=tiktok is rejected. search` substring-matches ASIN and product name case-insensitively. Single-shop only.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.date` filters on posting date, not activity date, so a video that kept accruing views is ranked by its lifetime views under the day it was posted. Single-shop only.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.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.Idempotency-Key is required; X-Dry-Run: true reports what would be deleted without deleting it.POST /image-briefs to keep it as a draft. The portal streams this generation token by token; here it is collapsed into one response. Each call spends model tokens, so Idempotency-Key is required and retries replay the first result rather than regenerating. Generation is non-deterministic — the same products give different copy each time.playful, clinical, premium). They are fed to every image-brief generation, so they shape the copy's tone. Read-only.null clears a nullable field. Up to 3 products. Idempotency-Key is optional (a patch is naturally repeatable); X-Dry-Run: true validates without writing.search. Read-only.@. For repeated or typeahead lookups prefer /meta-ads/instagram/creator-lookup, which returns the same profile from a 5-minute cache and so does not spend Meta API quota per keystroke. Single shop only.suggestions list so the response stays stable as more resolution sources are added. Today exactly one source contributes, Meta's business discovery, so the list holds at most one entry. Results are cached in Valkey for 5 minutes per shop and query, which is what makes this the endpoint to call on keystroke; /meta-ads/instagram/business-discovery hits Meta every time and returns richer fields. A handle that cannot be resolved — nonexistent, private, or a personal rather than Business/Creator account — returns an empty suggestions list rather than a 404, so a typeahead never has to treat a miss as an error. verified is always null: Meta's discovery edge does not expose it. Single shop only.metrics map so new metrics can be added without a breaking change. Meta serves per-media insights only for media owned by the connected account. Ask for a tagged post — anything from /meta-ads/instagram/tagged-media — and the answer is 422 INSIGHTS_NOT_AVAILABLE; that is Meta's rule, not a Reacher restriction, and the public engagement counts on the tagged-media row are the substitute. Source media_id values from /meta-ads/instagram/own-media. Single shop only.id here is a valid media_id for /meta-ads/instagram/media/{media_id}/insights, which is the only way to get reach and saves. Media and thumbnail URLs are short-lived signed Meta CDN links; mirror the bytes if you need them to persist. Rows are passed through exactly as Meta returns them. Single shop only.like_count / comments_count. Meta restricts this edge to owner-visible fields, so media_url and thumbnail_url are not available for tagged posts (they are owner-only) — render the permalink for click-through. The public engagement counts here are the only engagement signal available for content the brand did not post; per-media /insights will refuse it. owner is best-effort and may be absent when Meta withholds it. Single shop only.key, a status and, when connected, the connected_at timestamp. Covers tiktok_shop_affiliate and tiktok_shop_customer_service (the TikTok Shop apps that back creator outreach and messaging), tiktok_for_business (the ads account behind GMV Max), meta (the Facebook/Instagram account behind Meta Ads rev-share), amazon and shopify (the off-TikTok revenue channels the Halo tracker correlates against), and discord. status is connected, disconnected, or coming_soon where the integration isn't available to this shop's region yet. Which rows appear is region-dependent: an integration with no presence in the shop's region is omitted rather than returned as disconnected. Use this to explain an empty data surface — Halo with no Amazon revenue and a disconnected amazon row is a setup gap, not missing data. Connecting an integration is a browser OAuth flow, so the portal's install links are not part of this response. Read-only, single-shop.all/active/past/draft) and per type (retainer/challenge/leaderboard).x-shop-id. Returns cached campaign metadata last synced from TikTok by the portal — call the portal's sync endpoints to refresh. Supports multi-shop (x-shop-id: all or comma-separated).unreplied_only=true to get conversations awaiting a reply (what an AI agent typically iterates).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.source: manual) and auto-detected (source: auto_bof). Ordered applied first, then pending, then failed; newest first within each status. Single shop only (set x-shop-id to a specific shop ID).applied_status tells you whether TikTok has confirmed the exclusion (applied), it is waiting for the 4-hourly reconcile (pending), the video is not in any active campaign (no_creatives), or an actively delivering placement could not be excluded (failed). Single shop only.shop parameter on every other tool.live_gmv (default), start_time, units_sold or views. Empty sessions` is a normal 200 response for shops without live-session data.value, unit, the percent change against the immediately preceding window of equal length, and chart_data: one point per day of the window, zero-filled on days with no sessions so the series length always matches the range. **Differs from POST /lives/summary** — that returns flat window totals. This returns the same totals plus period-over-period change and a daily series, and accepts the portal's filters / search so the cards can be scoped to a creator or a GMV band. Engagement rate is a decimal (0.0-1.0), durations are seconds. Single-shop only; defaults to the last 30 days ending today. LIVE analytics is region-gated — shops outside the supported regions get a 403 REGION_NOT_SUPPORTED`. A shop with no sessions returns zeroed cards as a normal 200.POST /lives/list gives the session totals, this explains what inside the session earned them. Pass the key values from POST /lives/list rows in live_session_ids (up to 50 per request). Results are keyed back by session ID in request order. Sessions with no product rows — including any ID that belongs to a different shop, or a shop still on the legacy LIVE data path — return an empty products` list rather than an error. Single-shop only.customers.live_sessions (the Affiliate Center LIVE value shops see on /insights/transaction-analysis → LIVE streams). **Differs from POST /metrics/summary field gmv** — that is ALL affiliate revenue (video + live + product card). This isolates the LIVE-stream slice only. The live_gmv field on /metrics/summary is the same number as a simple cross-shop scalar; this endpoint adds per-shop currency, session count, engagement and viewing duration. Single-shop only — set x-shop-id to a specific shop ID. Defaults to the last 30 days ending today. Empty totals (live_count` 0) are a normal 200 response — live-session coverage is data-presence driven.is_current (and the top-level current_ad_account_id) marks the one this shop's ads and /meta-ads/ad-performance figures are read from. The list is the source of truth for what an account switch could target; switching itself stays in the portal. Requires a live Meta grant — a shop needing reconnection answers 409 META_REAUTH_REQUIRED. Single shop only.conversions is the sum of every entry in Meta's actions breakdown, because the insights edge exposes no single conversions field — read it as total attributed actions, not purchases. spend and the derived rates are in currency, the ad account's own currency, which need not match the shop's TikTok currency. This is paid Meta data straight from the Marketing API and is unrelated to the rev-share attribution figures at /meta-ads/campaigns/{campaign_id}/rollups, which come from Reacher's own ledger — do not add them together. Sub-fetches are best-effort: a failing insights edge yields zeros and an empty ad list rather than an error. Returns 400 when the shop has no ad account linked. Single shop only.ig_user_id / ig_username, with has_instagram as the quick flag). is_current marks the Page this shop is connected through. The Instagram link matters beyond display: Partnership ads and creator whitelisting both run through the Page's IG account, so a Page with has_instagram: false leaves the connection functionally incomplete even while /meta-ads/status reports connected: true. Single shop only.ig object, never the response). connected: false covers both never-connected and revoked/expired-and-not-yet-repaired; a shop in the latter state answers 409 META_REAUTH_REQUIRED on the endpoints that call Meta. Poll this before the network-bound reads. Single shop only./meta-ads/status is a database read, this fans out across several Graph edges — so it is served stale-while-revalidate from the same Valkey cache the portal uses (fresh under 5 minutes, usable-but-refreshing under 30, rebuilt inline only when cold), and invalidated immediately by any connection change. Every sub-object is open-schema: new fields can appear without a breaking change, and a sub-fetch that fails comes back as an empty object rather than failing the call. Single shop only.sent_at marks the delivery attempt, not a provider receipt. creator_id is the TikTok creator id (as returned by GET /automations/{id}/creators or GET /automations/{id}/sent-messages). Returns an empty list when this creator has never been personalized in this shop. Requires a single shop.fallback_rate convenience ratio. Counts are recorded when the send engine locks the copy for delivery (immediately before the DM goes out), so a delivery that fails at the last step may still be counted. An automation with no personalized sends yet returns zeros; an automation not in this shop returns 404. Requires a single shop.fallback_message is returned instead (is_fallback: true). Content Discussion and Product Discussion are AI-generated from the creator's own signals; Product Description / Selling Points / Offer are the fixed strings you pass in (resolve product blocks first via POST /personalization/product-blocks). Region and brand name are taken from the shop (brand name defaults to the shop name). API previews are stateless: nothing is stored, and a later send generates its own copy (or reuses a lock approved in the Reacher portal composer). Generation endpoints share a separate quota (20/min, 500/hr per key). Requires a single shop.[Product Description] (the product's own catalog text) and [Product Selling Points] (2–3 concrete selling points DERIVED from the product's real title/description/attributes — never invented). Use the returned strings verbatim in POST /personalization/preview and in the personalization block of POST /automations/dm, so preview and send share the same fixed copy. Both blocks degrade to empty strings (the block simply drops out of the message) ONLY when the product isn't in this shop's catalog or has too little grounded content; a failed lookup (transient database error) returns 500 instead, so empty strings are always a true statement about the product, never an outage artifact — safe to store. Requires a single shop.engaging | bold | inspirational), preserving every [Block] token so the template stays intact. This is brand-level copy (one message for everyone) — there's no creator here. Degrades to the original body on any failure, so the caller never ends up with a broken template. Requires a single shop./pnl/orders silently omits them — net_amount is the figure to carry across. Windowed on the date TikTok raised the adjustment. settled_date` is null until it reaches a payout.POST /pnl/profit complete, biggest impact first. coverage_pct` is by units, not by SKU count, so one missing best-seller outranks fifty missing long-tail SKUs.id. The units it covered become uncosted again and drop out of contribution_profit — they are not treated as free-of-charge silently, they are reported as uncosted. Scoped to this shop, so an id belonging to another shop returns 404. Requires read_write` scope and a single shop.effective_from — not just what is in force today, so a caller restating an old window can see which amount applied then. sku_id` is null on the product-level default.sku_id to set a product-level default that applies to every SKU without one of its own. Requires read_write` scope and a single shop.POST /pnl/summary reports in aggregate: every active product in the shop with its SKU pricing (sale and original price in currency units, not cents), stock, the derived discount_pct, and the affiliate commission_rate / shop_ads_commission_rate from the shop's most recent Target Collaboration config. gmv_max is shop-level, not per product: whether GMV Max is currently running and the average ROAS actually achieved across its active campaigns. tiktok_fee_pct is the platform's flat fee assumption used by the calculator. These are the *inputs* to a margin calculation, not settled money — for what TikTok actually paid out, use POST /pnl/summary or POST /pnl/orders. Single-shop only. A shop with no catalogued products returns an empty products` list as a normal 200.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.gross_profit is revenue less those per-SKU fees less COGS, and stops one step short of net earnings. For the true shop-level bottom line that includes ad spend, use POST /pnl/summary and POST /pnl/profit. If you request the net_earnings or total_expense columns they are the order-line totals and likewise exclude ad spend. gross_profit is an upper bound while units_uncosted is non-zero — uncosted units are counted, never assumed free. Windowed by order PAID date; single shop only.data_status` for freshness.total_inventory, sku_count, out_of_stock_sku_count) and, by default, a nested skus[] array with per-SKU stock and variant attributes. Set include_skus=false for a lighter product-only payload. All money is reported as integer minor currency units (cents) in the product's currency. Prices and stock are passed through exactly as TikTok reports them: product-level total_inventory and per-SKU inventory can legitimately differ during a sync, so do not assume total_inventory equals the sum of SKU inventories. There is no warehouse-level stock breakdown — inventory exists only at the product and SKU grain. For incremental syncs, pass updated_since and key off each row's updated_at. Soft-deleted products are excluded.title, description, impact type (e.g. 'High Impact', 'Addon'), the navigate path to set it up, its button label, and shop_names — the shops the recommendation applies to. Covers the four automation plays Reacher scores: Target Collab, Message + Product Card, Spark Code, and Content Flywheel. An empty array means the shop is already running all of them. Single-shop only.active. No new notification is sent.CampaignCreatorMapping.status='rejected'. Sends a rejection email + SMS to the creator (fire-and-forget) — SKIPPED on dry-run.removed status). The campaign lives in the x-shop-id shop; pass its id in the body. Removed creators disappear from the creator's portal views. Paid/completed creators are blocked (409) — their payout ledger is preserved and never overwritten. Idempotent: removing an already-removed creator returns 200 with code='already_removed' (no error). Combined with the Idempotency-Key replay, repeated calls are always safe. X-Dry-Run: true validates + echoes the intended action without writing or sending the optional SMS.CampaignCreatorMapping, then fires a notification (email + SMS) asking for additional posts — notifications SKIPPED on dry-run.pendingReview (how many requests await a decision, plus how many of those are expiring soon), approvedInAutoProcess (samples auto-approved by an automation), completionRate (share of approved samples that produced content), and approvalTarget (usage against the shop's approval quota). The change metrics compare against the immediately preceding period of equal length. dataFreshness reports how current the underlying sample data is — TikTok's sample feed lags, so surface it rather than presenting the counts as real-time. date_from/date_to` must be given together and bound request creation date. Single-shop only.toReview → readyToShip → shipped → pendingContent → completed, plus cancelled. Also returns the shop's completionRate, its approvalTarget usage, the archivedCount, and expiringCount (requests about to lapse if no decision is made). Counts honour the same filters as the portal table, so a filtered funnel and a filtered list agree. They EXCLUDE requests hidden because the creator is archived (archivedCount.total is how many those are, and archivedCounts is unset here); for stage counts that include them, and so match TikTok's Affiliate Center, use GET /funnel/v2/counts. The portal's advanced numeric creator filters (GMV / views / post-rate bands) are not exposed here — use POST /samples/list and aggregate if you need those. date_from/date_to` must be given together. Single-shop only.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.read_write scope and a single shop. config_id is re-checked against this shop before the delete — a foreign ID returns 404.usedThisMonth). Products with no row here follow the shop-wide quota only. Read-only; requires a single shop.read_write scope and a single shop. Omitted fields keep their current value; an explicit null clears the setting. config_id is re-checked against this shop before the write — a config belonging to another shop returns 404, never a cross-shop update.productId → usedThisMonth`). This is the counter the portal checks per-product sample limits against, so it answers 'which product is about to run out of its monthly allowance'. Products with no usage this month are omitted. Single-shop only.read_write scope and a single shop. Names are unique per shop — a duplicate returns 409 PROFILE_NAME_EXISTS. Link the new profile to products via idealCreatorProfileIds on a product config.read_write scope and a single shop. profile_id is re-checked against this shop before the delete — a foreign ID returns 404.read_write scope and a single shop. profile_id is re-checked against this shop before the write — a profile belonging to another shop returns 404. Renaming onto an existing name returns 409 PROFILE_NAME_EXISTS. Product configs linked to this profile pick up the new criteria immediately.linkedProducts counts how many product configs reference each profile. Read-only; requires a single shop.monthlyLimit is null when the shop has never set one, which means unlimited — per-product limits still apply. Read-only; requires a single shop.read_write scope and a single shop. monthlyLimit must be present: a number caps the shop, null removes the cap. The shop is taken from the authenticated key / x-shop-id, never from the body.query to browse the top creators in your shop's region. Returns handle, categories, follower_count, gmv, engagement, bio, and top videos. Filter with the typed params: min/max GMV, units sold, average views, engagement, post rate, followers; product categories, gender, ethnicity, age, language; creator_level (GMV tier L0–L7); community (topic/hashtag targeting, e.g. a 'fitness' or 'clean beauty' community); and video/AI attributes (content_style, production_quality, personality_tone, etc.). To discover the exact filter values available for a region call the ai-search-filters tool; for community/hashtag values call the hashtag-autocomplete tool first. NOTE on GMV: gmv is the creator's sparse GLOBAL profile GMV (often null); shop_gmv is the GMV the creator drove for YOUR shop (populated for your affiliate roster). Available in every region. Requires a single shop (not 'all'/comma-separated). For spoken-word matching use the transcript-search tool; for visual matching use the video-search tool; for 'more creators like these' use the lookalike-search tool.seed_creator_ids (TikTok handles or ids, up to 50), a seed_crm_group_id, a seed_list_id, or a text query describing the archetype. CRM group / list seeds resolve to creators scoped to YOUR shop. The seeds themselves are excluded from results. Use for 'more creators like @x and @y' or 'creators like the ones in my Q3 group'. Single shop only. NOT available in every region yet — call the capabilities tool first.query (e.g. 'talks about gut health', 'mentions our brand name') and it matches creator video transcripts. match_sources picks spoken audio and/or on-screen text (defaults to audio). Each result's matched videos carry a match_type and a transcript snippet. Single shop only. NOT available in every region yet — call the capabilities tool first; a region without transcript data returns a 400 explaining it's not enabled. This SEARCHES creators by transcript — it does NOT return a video's transcript text. To read the full transcript of a specific video you own, use the per-video creative-analysis tool instead.query. (Reference-image search exists as a separate upload endpoint and isn't available through this tool.) Single shop only. NOT available in every region yet — call the capabilities tool first; a region without visual data returns a 400.ranking_type=product) or videos (ranking_type=video) ranked by how many new customers they brought in, from customers.sc_buyers_ranking. Use it to find the product or piece of content that actually acquires buyers, as opposed to the one that generates the most GMV from buyers you already had. customer_contribution is the entity's share (0-1) of the shop's new customers over TikTok's trailing period_months window (12 by default). No date window: this is a snapshot ranking that TikTok recomputes and the collector overwrites wholesale. Collection of this ranking 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.shop_tab, search, other) with GMV, impressions, units sold and customers. baseline is TikTok's previous-period value for the same metrics, summed across the window. industry_median is the typical seller in this shop's industry — a benchmark, not an additive quantity, so it is reported as the most recent day in the window that carried one (as_of) rather than summed or averaged. It is null when TikTok returned no benchmark for the window; the daily collection path does not always include one. Max range 90 days. 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.funnel walks impression → click → add-to-cart → order, and channels splits the product's GMV across the seller's own video and live content, creator (affiliate) video and live, the product card, and the shop tab (with its own impression / visitor / conversion counts). Every total is a SUM over the window's daily rows and every rate is recomputed as SUM(numerator) / SUM(denominator) — never an average of the daily rate columns, which would weight a quiet day the same as a peak one. A rate is null, not 0, when its denominator is zero. Sort with sort_by (one of ['gmv', 'orders', 'items_sold', 'customers', 'impressions', 'clicks', 'add_to_cart', 'affiliate_gmv', 'shop_tab_gmv', 'refunds']) and sort_dir; page with page / page_size. Defaults to the last 30 days ending yesterday; max range 90 days. 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.comparison carries the comparison-period totals TikTok attaches to each day, summed across the window, and gmv_change_pct derives the swing. TikTok chooses those periods (typically the immediately preceding equal-length window), so treat it as a directional benchmark rather than a window you control. Related: POST /shop-gmv/timeseries gives the same channel hierarchy day by day, and POST /shop-gmv/summary gives the window totals without the comparison, product-card counts or listing impressions added here. aov is window GMV / window orders; customers is the sum of daily unique-buyer counts, so a buyer who purchased on two days is counted twice. Max range 90 days. 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.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.draft_id from the create-draft tool; the message body is taken from the draft, not from this call. On success the draft is removed so it cannot be sent twice. If TikTok refuses (daily / weekly messaging cap, 429) the draft is kept for the inbox — report that back rather than retrying. Use dry_run=true to check the draft resolves without sending. Single shop only.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.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.uuid, the viewer share_url, status, any locked reporting window, and the report_config describing which cards the viewer sees. The password is never returned; it is stored only as a hash. A shop with no link is simply absent from the list rather than returned as null. Works with a multi-shop key. Read-only — no read_write scope needed.share_url stay valid, so anyone already holding the link keeps working. Rotate the viewer password with password, take the link offline without archiving it with status: inactive, move or clear the locked reporting window, and change which cards the viewer sees with report_config. Omitted fields are left alone, so a password rotation never wipes the metric selection. Clearing the locked window needs clear_lock: true — omitted dates mean 'unchanged', not 'unlock'. Returns 404 if the link does not exist or belongs to a shop this key does not cover. Requires read_write scope.@ and surrounding whitespace are stripped, the handle is lowercased), so @Creator and creator are the same entry. The call is additive and forgiving: handles already on the list are counted in duplicates_skipped, malformed handles (URLs, blanks) in invalid_skipped — neither fails the request, so a partially valid batch still applies. Check added_count for what actually changed. At most 500 handles per request. Requires a key with read_write scope and a single shop.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.@) — that is the form DELETE /shops/blacklist/{creator} expects. Each row also carries the stable id and when it was added. Single-shop only.@Creator and creator both resolve to the same entry. A handle that is not on this shop's list returns 404 — this route is not a silent no-op, so a typo surfaces instead of being mistaken for a successful removal. To empty the whole list use POST /shops/blacklist/clear. Requires a key with read_write scope and a single shop.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.aov is recomputed as total GMV / total orders over the window (a window-correct value, not the average of daily AOVs). customers` is the SUM of daily unique-customer counts — buyers who purchased on multiple days are double-counted; a true window-distinct count is not derivable from this rollup.x-shop-id to a specific shop ID. Defaults to last 30 days ending yesterday. Max range 90 days (TikTok backfill depth). The newest available day is yesterday; today's row is not returned. Empty series` is a normal 200 response — Seller Center coverage is still rolling out.sps_score (0-5), sps_tier, peer_percentile, and the per-sub-metric dimensions breakdown. Single-shop only. snapshot is null` when the shop has no SPS data yet (non-official-API shop, or the first daily pull hasn't run).shop_performances/overview API — the same SPS shown in Seller Center. Each point carries sps_score (0-5), sps_tier, peer_percentile, and a dimensions breakdown of the sub-metrics (on-time dispatch, negative-review rate, etc.). Single-shop only — set x-shop-id to a specific shop ID. Defaults to the last 30 days ending yesterday. Max range 90 days. Only shops on the official-API sync path are covered; an empty series` is a normal 200 response (history builds from the first daily pull).granularity (weekly / monthly / quarterly), the period it applies from (created_at), and a targets object with the per-metric goals: target_collabs, creators_messaged, sample_requests, sample_approved, videos_posted, videos_converted, spark_codes. Omit granularity to get the latest target for each granularity the shop has set; pass one to get that granularity's history, newest first. An empty targets array means the shop has not set any. Read-only — targets are created and edited in the Reacher dashboard. Single-shop only.read_write scope. Single-shop only.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.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.brandName, the brand the video was made for. Pass seller_id to restrict to one brand's videos, or days to window relative to the creator's most recent post. Capped at 500 rows (capped flags truncation).lastUpdated is null when no sync has landed for the region yet.truncated before treating the result as complete.truncated in the response before treating the result as complete.truncated before treating the result as complete.video_ids to export a specific selection instead. Returns JSON rows by default; pass format: "csv" for a downloadable file. Capped at 1000 rows for most customers; truncated: true in the JSON response means the cap clipped the result. Read-only, but it consumes one of the shop's daily exports — a quota shared with portal exports.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.brand ID into the seller endpoints or a product ID into the product endpoints to resolve it. Favorites are per shop, not per user: everyone on the account sees the same watchlist. Read-only — no read_write scope needed. Single-shop only.percent_change, a daily shop_timeseries, and the matching ecosystem benchmark_avg / benchmark_p90 and benchmark_timeseries. percentile_all ranks you against every tracked shop; percentile_segment ranks you inside your own GMV segment (gmv_segment), which is the fairer comparison. Precomputed daily — computed_date is the snapshot the numbers come from.value, the Reacher-wide benchmark_avg, and the stage-to-stage conversion_rate against benchmark_conversion_rate. Stages converting below the benchmark are flagged status: action_required and carry a recommendation. biggest_dropoff_stage names the weakest link. Also returns content_unfulfilled — creators who took a sample and never posted.read_write scope. Single-shop only.benchmark_timeseries. Pass any segment, not just your own: all (every shop), segment_1 ($0–5K), segment_2 ($5K–50K), segment_3 ($50K–100K), segment_4 ($100K+). Use this to size the gap to the tier above you; use /my-benchmarks for where you sit today.transcript of a Social Intelligence (competitor) video — one of the videos surfaced by the seller / product / trending video endpoints. Pass a video_id from one of those lists. Returns available: false when no transcript is held yet (e.g. no_speech, still processing, or the video isn't in our SI corpus). For your OWN shop's videos use the video creative-analysis endpoint (/videos/{video_id}/analysis) instead — that one carries the transcript plus the full creative breakdown./gmv-max/spark-codes/sync-all is run. This one returns the codes themselves, including the ones creators submit through the spark-code form an automation DMs them. source says where a code came from: form (submitted through the form, or entered by hand), scraped (found on the creator's video), or bulk_upload (a retainer CSV). form_uuid ties a row back to the form link the creator was sent. permission reflects the checkbox on the form and is not a usage-rights grant — usage rights are a separate flow with their own statuses, exposed under /usage-rights. Creator contact details captured by the same form (email, address, phone) are deliberately not returned here. Single shop only — set x-shop-id to one shop ID.status='stopped' (terminal — no resume). Already-stopped automations are returned unchanged (idempotent on the row itself, independent of the Idempotency-Key` header). Boost cancellation against TikTok is best-effort and runs in a background thread on the portal side; this endpoint does not wait for it. Single shop only.synced. Writes pending rows to gmv_max_spark_code_sync; the offline CRJ fires the TikTok /tt_video/authorize/ calls on its next run. Returns immediately with {queued, skipped, message}. Shops without an active TikTok Business connection return 422 TIKTOK_NOT_CONNECTED`. Single shop only./tt_video/authorize/ call: * On success → code's sync_status flips to synced. * On TikTok QPS / rate-limit → code is left pending so the offline CRJ retries it; the response counts this in queued. * On hard error → failed with the error string. Up to 100 codes per request. Shops without an active TikTok Business connection return 422 TIKTOK_NOT_CONNECTED`. Single shop only.status: "queued". Actual TC delivery happens asynchronously through Reacher's TC delivery worker (browser automation, the same path the portal uses). Typical end-to-end latency is a few seconds, sometimes longer under worker load. Poll GET /public/v1/automations/{automation_id} for delivery status and target_collabs.invitation_id once the worker submits. Not for bulk. For >10 invites at a time, use POST /public/v1/automations/target-collab directly with a multi-creator audience — that's more efficient than calling this endpoint in a loop, and exposes the full TC feature set (content type, sample policy, follow-up DMs). Required. read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting or queueing.support_contact used as a fallback when a TC create request omits support_contact (CORE-5428). Returns configured: false (with null fields) when no default is set — in that state TC creates still require a per-request support_contact. Requires a single shop (x-shop-id).support_contact once, so TC create requests can omit it (CORE-5428). A per-request support_contact still overrides this default for that request. email is required; phone is optional. The upsert is keyed on the shop, so re-sending the same body yields the same state. Requires read_write scope, a single shop (x-shop-id), and an Idempotency-Key header (for contract consistency with the other public-API write endpoints) — replay/conflict semantics match those writes.granularity, the most recent set is updated in place; otherwise a new set is created. Only the metrics you send are stored, so send the full set you want in effect rather than a partial diff. Available metrics: target_collabs, creators_messaged, sample_requests, sample_approved, videos_posted, videos_converted, spark_codes. At least one is required, and each must be a non-negative integer. Read the current targets back with GET /targets. Requires a key with read_write scope and a single shop.PUT /targets — set weekly, monthly and quarterly goals in one request instead of three. Each entry is upserted exactly as the single-granularity route does, and each granularity may appear only once. NOT atomic: entries are applied in order and an invalid one aborts the request, leaving earlier entries already written. Re-sending the whole payload after fixing the bad entry is safe — writes are upserts. Requires a key with read_write scope and a single shop.AUTOMATION_NOT_EDITABLE or AUTOMATION_EXPIRED. PATCH semantics — fields the caller does NOT include are left unchanged. Sending null for boost_start_date / boost_end_date clears the boost window (both dates must be sent together). X-Dry-Run: true echoes the patch without writing. Idempotent via the Idempotency-Key` header. Single shop only.campaign_type and creator_source are immutable post-create — pass them and you'll get 400 IMMUTABLE_FIELD.operation_status). Requires read_write scope. PATCH semantics — fields the caller omits are left unchanged; at least one field must be provided. The shop must be connected to TikTok Business / GMV Max (400 INVALID_REQUEST otherwise). Idempotent via the Idempotency-Key header. X-Dry-Run: true` echoes the mapped TikTok patch without calling TikTok. Single shop only.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.creatorId is rejected). If the DM can't be delivered the request is rolled back and 422 DM_NOT_DELIVERED is returned — so the call is all-or-nothing. Requires read_write scope and an Idempotency-Key. Single shop only.requested, accepted, active, declined, …), filterable by status, search, date, GMV/views, creators, products, and spoken-transcript keywords. Ordered and paginated. Single shop only (set x-shop-id).video_id (get ids from the videos-list tool) and a single shop. Returns: transcript (verbatim spoken audio) with transcript_language/transcript_source, a hook_summary of how it opens, the structure_outline of its beats, on_screen_text (OCR), vision_tags, detected_products, and scored creative features (hook-in-first-3s, pace, product-demo, voiceover, content summary). Pass include_experimental=true for the full analyzer block (~80 fields incl. hook_text, target_audience, sentiment, content_style, call-to-action, social-proof). analyzed:false (HTTP 200) = your video, not analyzed yet; 404 = not your shop's video. To SEARCH creators by what they say, use the transcript-search tool instead.video_ids and get each one's transcript, hook_summary, structure_outline, features, etc. Never 404s — ids that aren't your shop's come back in not_found. Use to pull transcripts/analysis for a whole set of videos in one call. Single shop only.bof_status, bof_confidence, is_bof, and the matched_signals/matched_keywords behind the call. For the transcript and full creative breakdown use the per-video analysis tool. Single shop + video_id.watch_finish_rate), exposure (impressions), views, CTR and engagement — the organic hook-quality signal. TikTok exposes a 2-second view rate only for GMV Max ad creatives (video_view_rate_2s on /campaigns/{id}/creative-metrics); for organic videos the retention metric is completion, so use watch_finish_rate as the quality bar (min_watch_finish_rate filters to it). Ordered strongest-hook first. Scope: videos in the shop's own Seller Center analytics (posted for the shop).x-shop-id: all, a comma-separated list, or a single shop ID — a key scoped to a subset of shops only ever sees that subset. Sortable by any of: affiliate_gmv, videos_posted, video_views, active_creators, gmv_per_video, gmv_per_sample, video_conversion_rate, shop_name; search filters on shop name; results are paginated (page / page_size, max 100) and total_pagination` is the number of shops you can see after filtering. The window defaults to the last 7 settled days.type (e.g. reactivate_creators, amplify_videos, prioritize_products), a headline title, a one-line description, and the items it refers to (creator, video or product, each with a display label, image and a formatted metric). Generation is rule-based over the same top-N data the report uses. Single-shop only — set x-shop-id to a specific shop ID. The window defaults to the last 7 settled days and is capped at 90 days. An empty actions` list is a normal 200 for a shop with no qualifying activity.recommendations. Single-shop only — set x-shop-id to a specific shop ID. The window defaults to the last 7 settled days and is capped at 90 days; end_date must be at least 1 day in the past. An end_date past the shop's newest settled day is clamped to it, which can make the window shorter than requested (the 7-day default included) — the response's start_date/end_date` always report the window actually used, and the period-over-period comparison follows that same length. Returns 404 when the shop has no activity in the settled part of the window, and when the requested window lies entirely past the settled day — that message names the newest day the shop is reportable through, so a caller can retry against a window that works.shops is the shops this KEY can reach, which is not always what the account owns — a connector authorized for two shops reports two. Read scopes before attempting a write: a key without read_write gets a 403 from every write endpoint. Cheap and side-effect free, so it is the right first call to verify a connection rather than a real query that might fail for its own reasons.Click any prompt to copy it.
App Stats
323
Tools
3
Prompts
ChatGPT
Platforms
Category
Brand MonitoringWorks with
Data refreshed daily
