API docs by Redocly

Reacher Data API (1.0.0)

Download OpenAPI specification:

Access your Reacher affiliate data programmatically. Use your API key in the x-api-key header and shop ID in the x-shop-id header.

Shops

Discover your shops and their regions.

List your shops

Returns all active shops accessible to this API key. Use the returned shop_id values in the x-shop-id header for other endpoints.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Creators

Affiliates who have worked with your shop.

List creators

List affiliate creators for your shop with pagination, sorting, and filtering. GMV represents the creator's lifetime revenue for this shop. Data updates approximately every hour.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Status (string) or Status (null) (Status)
Creator Handle (string) or Creator Handle (null) (Creator Handle)
Min Shop Gmv (number) or Min Shop Gmv (null) (Min Shop Gmv)
Min Overall Gmv (number) or Min Overall Gmv (null) (Min Overall Gmv)
Min Videos (integer) or Min Videos (null) (Min Videos)
Min Followers (integer) or Min Followers (null) (Min Followers)
Group Id (string) or Group Id (null) (Group Id)
Array of Tags (strings) or Tags (null) (Tags)
Product Id (string) or Product Id (null) (Product Id)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "shop_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "status": "string",
  • "creator_handle": "string",
  • "min_shop_gmv": 0,
  • "min_overall_gmv": 0,
  • "min_videos": 0,
  • "min_followers": 0,
  • "group_id": "string",
  • "tags": [
    ],
  • "product_id": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Creator performance (date-filtered)

Top creators ranked by GMV earned within a specific date range. Unlike /creators/list (which shows lifetime GMV), this endpoint uses daily performance data and matches the dashboard's 'Top Creators' section exactly. Defaults to the last 30 days. Use this for period-specific rankings and reports.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Creator Handle (string) or Creator Handle (null) (Creator Handle)
Min Gmv (number) or Min Gmv (null) (Min Gmv)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "creator_handle": "string",
  • "min_gmv": 0
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Creator activity totals for a window

Four headline totals for the shop over a date window: creators added, affiliate GMV earned, videos posted, and orders placed. Runs the same aggregate query that backs the summary cards above the portal's My Creators table, over the same trailing-28-day default window (TikTok reporting day, GMT-7).

gmv_generated and video_posts are scoped to the shop's CRM-tracked creators, which makes them narrower than their whole-shop namesakes on POST /metrics/summary (gmv, videos_posted) — the two will not agree, by design.

Aggregates cover the whole shop — there is no filter parameter in v1. Defaults to the trailing 28 days. Requires a single shop.

No prior-period comparison is included; for a period-over-period delta, call twice with adjacent windows and subtract. Returns 503 when the aggregate times out — back off and retry rather than treating it as a failure.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
Start Date (string) or Start Date (null) (Start Date)

Window start (inclusive). Omit for a trailing 28-day window ending at end_date.

End Date (string) or End Date (null) (End Date)

Window end (inclusive). Defaults to today.

Responses

Request samples

Content type
application/json
{
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "currency": "string",
  • "date_range": {
    }
}

Creator distribution by GMV level

Distribution of creators by GMV tier (L0-L7). Matches the dashboard's 'Creators by Level' pie chart. Uses active creators from the date range (defaults to last 30 days). Pass start_date and end_date query params (YYYY-MM-DD) to customize the window. L0=$0, L1=<$5k, L2=$5k-$25k, L3=$25k-$60k, L4=$60k-$150k, L5=$150k-$400k, L6=$400k-$1M, L7=>$1M.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
Start Date (string) or Start Date (null) (Start Date)

Start date (YYYY-MM-DD). Defaults to 30 days ago.

End Date (string) or End Date (null) (End Date)

End date (YYYY-MM-DD). Defaults to the shop's newest settled day.

Responses

Response samples

Content type
application/json
null

Get creator detail

Get detailed information for a single creator, including groups, products, and latest 10 videos (for full video list, use POST /creators/{creator_handle}/videos).

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "groups": [ ],
  • "products": [ ],
  • "videos": [ ],
  • "currency": "string"
}

List creator's videos

Paginated list of videos by this creator in your shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "video_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

List creator's products

Products this creator is affiliated with in your shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "shops_queried": [
    ]
}

Products

Your products and their affiliate performance.

List products

Product performance metrics aggregated over a date range. Defaults to the last 7 days if no dates are specified. Data is typically 2-3 days behind the current date. Each product also carries its TikTok Seller Center per-product metrics as sc_* fields: all-channel GMV with its per-channel breakdown (affiliate, seller video, seller live, product card, shop tab), plus orders, units sold, customers, impressions, clicks, CTR, conversion, AOV, GMV per 1,000 impressions, add-to-cart, and refunds. The sc_* fields are null for products not yet on the Seller Center sync.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Product Name (string) or Product Name (null) (Product Name)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "product_name": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

List product's creators

Creators affiliated with this product.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
product_id
required
string (Product Id)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "shops_queried": [
    ]
}

List product's videos

Videos featuring this product.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
product_id
required
string (Product Id)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "video_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Videos

Affiliate videos and performance metrics.

List videos

Affiliate videos and their performance metrics. Values represent lifetime totals per video (total views, total GMV, etc.). Data can be up to three days stale, given the delay in affiliate center.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Creator Id (string) or Creator Id (null) (Creator Id)
Creator Handle (string) or Creator Handle (null) (Creator Handle)
Product Id (string) or Product Id (null) (Product Id)
Min Gmv (number) or Min Gmv (null) (Min Gmv)
Min Views (integer) or Min Views (null) (Min Views)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "video_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "creator_id": "string",
  • "creator_handle": "string",
  • "product_id": "string",
  • "min_gmv": 0,
  • "min_views": 0
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Top videos with creative breakdown

The shop's top videos ranked by GMV earned in the date range (defaults to the last 30 days, same ranking as /videos/performance), each enriched with the AI creative breakdown: hook, sell points, product niche, shot style, and videography. Use this to analyze WHY the top videos perform — not just how much they earned. Videos that haven't been analyzed yet keep their metrics and list the unavailable breakdown fields in creative.missing_fields; render those as 'not analyzed' rather than blank. Multi-shop requests (x-shop-id: all or comma-separated) mirror /videos/performance's semantics: one ranking across shops with a single top-level currency (USD fallback) — use a single shop when per-shop currency precision matters.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
limit
integer (Limit) [ 1 .. 50 ]
Default: 10
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
{
  • "limit": 10,
  • "sort_by": "video_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "date_range": {
    },
  • "coverage": {
    },
  • "total_count": 0,
  • "message": "string",
  • "shops_queried": [
    ]
}

Video performance (date-filtered)

Top videos ranked by GMV or views earned within a specific date range. Unlike /videos/list (which shows lifetime totals), this endpoint uses daily performance data and matches the dashboard's 'Top Videos' section exactly. Defaults to the last 30 days. Use this for period-specific rankings, trend analysis, and correlating video performance with product sales.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Creator Handle (string) or Creator Handle (null) (Creator Handle)
Min Gmv (number) or Min Gmv (null) (Min Gmv)
Min Views (integer) or Min Views (null) (Min Views)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "video_gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "creator_handle": "string",
  • "min_gmv": 0,
  • "min_views": 0
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Samples

Sample request tracking and per-product breakdowns.

List sample requests

Track sample requests from creators in your shop. Shows only sample-related statuses. Data updates approximately every hour.

Each row includes the requesting creator's bio, categories, and email (sourced from the same regional creators table the AI Creator Search API reads), so consumers can score sample requests on brand/niche fit without a second API call. These fields are null when the creator has no row in the regional creators table.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Status (string) or Status (null) (Status)
Creator Handle (string) or Creator Handle (null) (Creator Handle)
Product Id (string) or Product Id (null) (Product Id)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "updated_at",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "status": "string",
  • "creator_handle": "string",
  • "product_id": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Sample metrics by product

Sample performance breakdown by product. Shows requests, approvals, and GMV per product. Data can be up to three days stale, given the delay in affiliate center.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "total_requests",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ]
}

Automations

Automation performance and outreach metrics.

List automations

Your automations with performance and outreach metrics. Includes creators reached, sample requests, videos posted, and GMV. reply_rate is populated for Running, Stopped, and Completed automations.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 50
Sort By (string) or Sort By (null) (Sort By)
sort_dir
string (Sort Dir)
Default: "desc"
Enum: "asc" "desc"
Start Date (string) or Start Date (null) (Start Date)

Inclusive window start (YYYY-MM-DD). When supplied (alone or with end_date), creators_reached / skipped / total_creators switch from LIFETIME materialized-view values to in-window DISTINCT counts against the raw event tables. Filters the row set on Automation.created_at as well.

End Date (string) or End Date (null) (End Date)

Inclusive window end (YYYY-MM-DD). When supplied (alone or with start_date), see start_date for the creator-metric semantic change.

Automation Type (string) or Automation Type (null) (Automation Type)
Status (string) or Status (null) (Status)
Array of Created Via (strings) or Created Via (null) (Created Via)

Include only automations created by these surfaces. Common values: portal | api | api_direct | mcp | agent | slack | internal | campaign_tc_auto (set is not closed). NULL/empty provenance matches portal. Values not present in the shop's automation data match nothing; future/internal values remain filterable when they appear in the data. Example: ["api_direct"] returns only single-creator direct invites.

Array of Exclude Created Via (strings) or Exclude Created Via (null) (Exclude Created Via)

Exclude automations created by these surfaces. Applied after created_via. Example: ["api_direct"] hides the API direct invite — {handle} rows produced by POST /public/v1/target-collabs so the list shows only your managed automations.

Responses

Request samples

Content type
application/json
{
  • "page": 1,
  • "page_size": 50,
  • "sort_by": "gmv",
  • "sort_dir": "asc",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "automation_type": "string",
  • "status": "string",
  • "created_via": [
    ],
  • "exclude_created_via": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "currency": "string",
  • "pagination": null,
  • "date_range": {
    },
  • "shops_queried": [
    ],
  • "aggregate": {
    }
}

Region-specific filter options

Returns the filter options (categories, GMV ranges, follower segments, engagement / view tiers, content-style options, etc.) valid for the given shop region. Use the response to drive filter dropdowns or to validate 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).

Authorizations:
(ApiKeyAuthShopId)
query Parameters
shop_region
required
string (Shop Region)

Responses

Response samples

Content type
application/json
null

Outreach send capacity for this shop

Current outreach send-capacity for a single shop, so callers can pre-check before sending TC invites / DMs and schedule retries when capacity frees.

Two independent limits govern outreach:

  • Daily per-shop throttle counted in UTC (resets at 00:00 UTC — see daily_window_resets_at). daily_creators_used counts actual sends only (skipped/creator_not_found invites do not count). The daily ceiling is plan/TikTok-dependent and is not returned as a single number; daily_limit_throttled flags when the shop is currently paused by it.
  • TikTok's weekly outreach limit (resets at the start of each week, enforced TikTok-side — the remaining count is not knowable to us). weekly_limit_throttled flags when paused by it; if true, retry next week.

The daily pool is shared between the automation engine and direct POST /target-collabs invites. Requires a single shop.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
{
  • "shop_id": 0,
  • "daily_creators_used": 0,
  • "daily_window_resets_at": "string",
  • "concurrent_automations_running": 0,
  • "max_concurrent_automations": 0,
  • "daily_limit_throttled": true,
  • "weekly_limit_throttled": true
}

Get automation detail

Detailed automation data with performance metrics.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "creators_remaining": 0,
  • "currency": "string"
}

Update automation

Partial update across all 4 types. Cannot change automation_type, shop, lifecycle state, or system fields. Idempotency-Key optional; X-Dry-Run: true supported.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
Automation Name (string) or Automation Name (null) (Automation Name)
AutomationSchedule (object) or null
CreatorsToInclude (object) or null
CreatorsToExclude (object) or null
Array of Messages (objects) or Messages (null) (Messages)

Replace the initial-outreach addon set. ALL items are sent immediately together when the automation engages a creator. Pass [] to clear messages (invite-only). Use follow_ups for delayed sequencing. Only valid for target_collab and dm automations.

Array of Follow Ups (objects) or Follow Ups (null) (Follow Ups)

Replace the delayed follow-up sequence. Pass [] to clear. Only valid for target_collab and dm automations.

TargetCollabPatchPayload (object) or null

Partial update for the TC-specific config. Send only the keys you want to change — supported sub-keys mirror TargetCollabConfig: invitation_name, valid_until, message, products, content_type, sample_policy, support_contact, lock_receivers_profiles. Unknown keys are rejected with 422 (extra='forbid'). The translator merges into the existing config blob and dual-writes to the legacy UPPERCASE root.

DmConfigPatchPayload (object) or null

Partial update for the DM-specific config. Currently supports spark_code only (other dm_config keys were removed 2026-05-01).

SampleRequestPatchPayload (object) or null

Partial update for the sample-request config. Send only the keys you want to change — supported sub-keys mirror SampleRequestPayload: action, rejection_reason, approval_message, rejection_message, message_images, products, minimum_performance_criteria, maximum_performance_criteria, auto_approval_settings, target_list. Unknown keys (top-level OR nested) are rejected with 422 (extra='forbid'). The translator routes both criteria blocks through the V2 prefix + percent-scale helper.

Ai Enabled (boolean) or Ai Enabled (null) (Ai Enabled)
Is Evergreen (boolean) or Is Evergreen (null) (Is Evergreen)
End Date (string) or End Date (null) (End Date)
Business Hours Timezone (string) or Business Hours Timezone (null) (Business Hours Timezone)

Set or change the 9am–9pm send-window timezone (CORE-3031). Pass an IANA name to enable, or the empty string "" to disable. Only valid for target_collab and dm automations.

Email Sent Per Day (integer) or Email Sent Per Day (null) (Email Sent Per Day)
Subject (string) or Subject (null) (Subject)
Body (string) or Body (null) (Body)

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "schedule": {
    },
  • "creators_to_include": {
    },
  • "creators_to_exclude": {
    },
  • "messages": [
    ],
  • "follow_ups": [
    ],
  • "target_collab": {
    },
  • "dm_config": {
    },
  • "sample_request": {
    },
  • "ai_enabled": true,
  • "is_evergreen": true,
  • "end_date": "2019-08-24",
  • "business_hours_timezone": "string",
  • "email_sent_per_day": 1,
  • "subject": "string",
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Delete automation

Soft-delete (state=archived). Reversible only by Reacher support. Calling on already-archived returns 200 with already_archived: true.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Per-creator outcome ledger

Per-creator outcomes for ONE automation: which creators got an invite/DM submitted, which were skipped (and why), which were previously invited, etc. This is the authoritative per-creator answer to 'what happened to each invite' — backed by the always-present 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "summary": {
    },
  • "pagination": null
}

Automation message templates

The message copy configured on one automation, flattened into a uniform shape regardless of automation type: the TC invite template (tc_invite_message), the ordered DM sequence (message_sequence — array order is send order), follow-up steps, and AI-chatbot Q&A. Placeholders (e.g. {{creators username}}) are NOT substituted — this is the template. For the exact per-creator text that was actually sent, use GET /automations/{automation_id}/sent-messages. Requires a single shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)

Responses

Response samples

Content type
application/json
{
  • "automation_id": 0,
  • "automation_name": "string",
  • "automation_type": "string",
  • "tc_invite_message": "string",
  • "message_sequence": [
    ],
  • "follow_up_steps": [
    ],
  • "ai_custom_qa": [
    ],
  • "personalization": {
    }
}

Exact sent message copy (grouped by creator)

What this automation actually sent, with honest coverage semantics:

  • dm_sent — the exact rendered DM text per creator (placeholders substituted at send time), grouped by creator, most recently messaged first. Filter with creator_handle; page depth with creator_limit / messages_per_creator.
  • tc_sent — Target-Collab invitation batches (who was invited, when, status) plus the invite template. TikTok TC invites are sent from the template and the per-creator rendered text is not stored — exact_copy: false and coverage_note state this explicitly. When the automation is a campaign's TC automation, campaign carries the link.

Hybrid automations (Message + TC) populate both sections. Empty sections carry an explicit message instead of blank lists. Read-only. Requires a single shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
query Parameters
creator_limit
integer (Creator Limit) [ 1 .. 100 ]
Default: 20
messages_per_creator
integer (Messages Per Creator) [ 1 .. 50 ]
Default: 20
Creator Handle (string) or Creator Handle (null) (Creator Handle)

Responses

Response samples

Content type
application/json
{
  • "automation_id": 0,
  • "automation_name": "string",
  • "automation_type": "string",
  • "template": {
    },
  • "dm_sent": {
    },
  • "tc_sent": {
    },
  • "message": "string"
}

Create Target Collab automation

Create a Target Collab (TC) invitation automation with optional follow-up DMs. Required: read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
X-Created-Via (string) or X-Created-Via (null) (X-Created-Via)
Request Body schema: application/json
required
automation_name
required
string (Automation Name) [ 1 .. 120 ] characters
required
object (AutomationSchedule)

Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema.

object (CreatorsToInclude)

Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A):

  • lists mode — list_upload and/or lists_selected populated
  • filters mode — filters populated (dynamic by attribute)
  • crm_group mode — crm_group_id populated (saved predicate)

The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derived from which mode is set — callers don't need to set it explicitly.

object (CreatorsToExclude)

Outreach-paradigm recipient exclusion. Mirrors creators_to_omit in the legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel.

required
object (TargetCollabConfig)

TC-specific config — invitation metadata, commission rates, sample policy, content type, support contact. Maps to the legacy TC config blob shape (UPPERCASE root keys: BASE_INVITATION_NAME, VALID_UNTIL, TARGET_COLLAB_MESSAGE, EMAIL, PHONE_NUMBER, OFFER_FREE_SAMPLES, AUTO_APPROVE, PRODUCTS) — the worker reads from those, so the translator flattens this nested model accordingly.

Array of objects (Messages) <= 5 items

Initial-outreach addons — text, images, product cards, etc. ALL items in this list are sent immediately together when the automation engages a creator. Use follow_ups for delayed follow-up steps. Empty messages = invite-only TC.

Array of objects (Follow Ups) <= 3 items

Delayed follow-up steps. Each step has delay_days after the prior step (or after the initial outreach for the first follow-up) and one or more addons that fire together. Use this to build a multi-touch sequence.

ai_enabled
boolean (Ai Enabled)
Default: false
End Date (string) or End Date (null) (End Date)
auto_resolve_conflicts
string (Auto Resolve Conflicts)
Default: "MOVE_NOT_ACCEPTED"
Enum: "SKIP_ALL" "MOVE_NOT_ACCEPTED" "MOVE_ALL"

How the runtime handles creators who already have a pending TC invite from another automation. SKIP_ALL leaves them untouched; MOVE_NOT_ACCEPTED (default — matches portal-created automations) re-targets creators whose prior invite was never accepted; MOVE_ALL re-targets regardless of prior invite state. Maps to config.AUTO_RESOLVE_CONFLICTS.

is_evergreen
boolean (Is Evergreen)
Default: false

When true, the automation continuously re-evaluates its creators_to_include.filters and queues newly-qualifying creators on each run. Has no effect for lists mode (lists are static) or crm_group mode (CRM groups are inherently evergreen). Maps to top-level Automations.is_evergreen column.

Business Hours Timezone (string) or Business Hours Timezone (null) (Business Hours Timezone)

When set, the runtime restricts outbound message delivery (initial outreach + follow-ups) to 9am–9pm in this IANA timezone (e.g. America/Los_Angeles). Null disables the restriction — messages can fire at any time within the schedule's daily window. The 9–9 window is fixed; only the timezone is configurable. Distinct from schedule.timezone, which governs when the automation evaluates its queue (per CORE-3031).

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "schedule": {
    },
  • "creators_to_include": {
    },
  • "creators_to_exclude": {
    },
  • "target_collab": {
    },
  • "messages": [
    ],
  • "follow_ups": [
    ],
  • "ai_enabled": false,
  • "end_date": "2019-08-24",
  • "auto_resolve_conflicts": "SKIP_ALL",
  • "is_evergreen": false,
  • "business_hours_timezone": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Create TC Cleanup automation

Create a TC Cleanup utility automation — re-targets creators in this shop who received a TC invite from a prior automation but didn't accept it. Conceptually closer to sample_request than to the proactive TC outreach types: products + creator selection only, no messages, no follow-ups. Required: read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
X-Created-Via (string) or X-Created-Via (null) (X-Created-Via)
Request Body schema: application/json
required
automation_name
required
string (Automation Name) [ 1 .. 120 ] characters
required
object (AutomationSchedule)

Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema.

object (CreatorsToInclude)

Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A):

  • lists mode — list_upload and/or lists_selected populated
  • filters mode — filters populated (dynamic by attribute)
  • crm_group mode — crm_group_id populated (saved predicate)

The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derived from which mode is set — callers don't need to set it explicitly.

object (CreatorsToExclude)

Outreach-paradigm recipient exclusion. Mirrors creators_to_omit in the legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel.

required
Array of objects (Products) [ 1 .. 50 ] items

Products to re-invite the matching creators for. Cleanup uses the same TargetCollabProduct shape (product_id + commission rates) as a regular TC. Required — runtime needs at least one product to issue the re-invite.

Invite Start Before Days (integer) or Invite Start Before Days (null) (Invite Start Before Days)

Re-target only creators whose original TC invite was sent at least N days ago. Null = no lower bound on invite age. Persists as config.INVITE_START_BEFORE_DAYS.

Invite Expire After Days (integer) or Invite Expire After Days (null) (Invite Expire After Days)

Re-target only creators whose original TC invite expires within the next N days. Null = no upper bound on time-to-expiry. Persists as config.INVITE_EXPIRE_AFTER_DAYS.

End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "schedule": {
    },
  • "creators_to_include": {
    },
  • "creators_to_exclude": {
    },
  • "products": [
    ],
  • "invite_start_before_days": 1,
  • "invite_expire_after_days": 1,
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Create DM automation

Create a Direct Message automation. The mode field selects between 4 variants: vanilla (text-only), with_image, with_product_card, spark_code (collect TikTok spark codes via form). Each mode has specific addon and config requirements — see model schema.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
X-Created-Via (string) or X-Created-Via (null) (X-Created-Via)
Request Body schema: application/json
required
automation_name
required
string (Automation Name) [ 1 .. 120 ] characters
mode
string (Mode)
Default: "vanilla"
Enum: "vanilla" "with_image" "with_product_card" "spark_code"
required
object (AutomationSchedule)

Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema.

object (CreatorsToInclude)

Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A):

  • lists mode — list_upload and/or lists_selected populated
  • filters mode — filters populated (dynamic by attribute)
  • crm_group mode — crm_group_id populated (saved predicate)

The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derived from which mode is set — callers don't need to set it explicitly.

object (CreatorsToExclude)

Outreach-paradigm recipient exclusion. Mirrors creators_to_omit in the legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel.

required
Array of objects (Messages) [ 1 .. 5 ] items

Initial-outreach addons — text + optional image / product card / spark_code form. ALL items are sent immediately together when the automation engages a creator. Use follow_ups for delayed steps.

Array of objects (Follow Ups) <= 3 items

Delayed follow-up steps — same shape as TC.

DmConfig (object) or null
DmPersonalizationConfig (object) or null

CORE-4857: enable AI personalization of the initial-outreach DM. Omit to send the message exactly as written. When set, the send engine rewrites the DM per creator from the [Block] tokens in your message text and falls back to fallback_message for low-signal creators. See DmPersonalizationConfig.

ai_enabled
boolean (Ai Enabled)
Default: false
End Date (string) or End Date (null) (End Date)
is_evergreen
boolean (Is Evergreen)
Default: false

When true, the automation continuously re-evaluates its creators_to_include.filters for new qualifying creators on each run. No effect when creators_to_include.crm_group_id is set (CRM groups are inherently evergreen). Maps to top-level Automations.is_evergreen column.

Business Hours Timezone (string) or Business Hours Timezone (null) (Business Hours Timezone)

When set, the runtime restricts outbound message delivery (initial outreach + follow-ups) to 9am–9pm in this IANA timezone (e.g. America/Los_Angeles). Null disables the restriction. The 9–9 window is fixed; only the timezone is configurable. Distinct from schedule.timezone.

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "mode": "vanilla",
  • "schedule": {
    },
  • "creators_to_include": {
    },
  • "creators_to_exclude": {
    },
  • "messages": [
    ],
  • "follow_ups": [
    ],
  • "dm_config": {
    },
  • "personalization": {
    },
  • "ai_enabled": false,
  • "end_date": "2019-08-24",
  • "is_evergreen": false,
  • "business_hours_timezone": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Create Email automation

Create an outbound email automation. Different recipient model from outreach — use selection_mode: mailing_list (with vault list IDs or upload emails inline) OR selection_mode: filters (creator search criteria). Constraint: each email_account_id can be linked to at most ONE active email automation.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
X-Created-Via (string) or X-Created-Via (null) (X-Created-Via)
Request Body schema: application/json
required
automation_name
required
string (Automation Name) [ 1 .. 120 ] characters
email_account_id
required
integer (Email Account Id) > 0

Pre-connected email account. Each account links to at most ONE active email automation per shop.

subject
required
string (Subject) [ 1 .. 255 ] characters
body
required
string (Body) [ 1 .. 50000 ] characters

HTML or plaintext.

selection_mode
required
string (Selection Mode)
Enum: "mailing_list" "filters"
EmailMailingList (object) or null
EmailFilters (object) or null
object (CreatorsToExclude)

Outreach-paradigm recipient exclusion. Mirrors creators_to_omit in the legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel.

Array of objects (Attachments) <= 10 items

Email attachments — [{name, url}] shape. URL must be a hosted HTTPS URL (no file uploads). Server fetches at create time and re-hosts internally.

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "email_account_id": 0,
  • "subject": "string",
  • "body": "string",
  • "selection_mode": "mailing_list",
  • "mailing_list": {
    },
  • "filters": {
    },
  • "creators_to_exclude": {
    },
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Create Sample Request auto-processing automation

Auto-approve OR auto-reject incoming TikTok Shop sample requests by criteria. Side-effect: a CRM Group is internally created from the minimum_performance_criteria so creator membership stays dynamic. The new crm_group_id is returned in side_effects. If CRM-group creation fails, the automation still creates (logged + Sentry breadcrumb). Sample request type uses target_list (vault list IDs) instead of creators_to_include.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
X-Created-Via (string) or X-Created-Via (null) (X-Created-Via)
Request Body schema: application/json
required
automation_name
required
string (Automation Name) [ 1 .. 120 ] characters
required
object (SampleRequestPayload)

Inner sample_request config — mirrors the legacy sample_request_config shape exactly (the worker reads from it).

AutomationSchedule (object) or null

Optional — sample_request can run continuously. If set, the automation only auto-approves/rejects during scheduled hours.

object (CreatorsToExclude)

Optional creator exclusion. Persists as config.excluded_creators (sibling of sample_request_config) using {excluded_lists_ids, excluded_crm_groups_ids, excluded_creator_ids} shape — matches reacher-web-react formDataTransformer.ts.

Responses

Request samples

Content type
application/json
{
  • "automation_name": "string",
  • "sample_request": {
    },
  • "schedule": {
    },
  • "creators_to_exclude": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Start automation

Transition automation to running. Idempotent — already-running returns 200. Rejects with 422 AUTOMATION_NOT_STARTABLE when the automation can never run as configured (no schedule day with maxCreators > 0, or valid_until/end_date already passed) — this prevents the 'start succeeded but nothing ever sends' trap.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Stop automation

Transition automation to stopped. Idempotent.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": false,
  • "side_effects": { }
}

Personalization

AI-personalized outreach (CORE-4857): preview the message a creator would receive, resolve product blocks, retone copy, and read fallback stats + per-creator sent history. Configure it on a DM via the personalization block of POST /automations/dm. Single-shop only.

Preview the personalized message a single creator would receive

Generate the AI personalization blocks for one creator and return the fully assembled message — exactly what a send with the same configuration would ship. When the creator has too little signal to personalize, the brand 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.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
required
object (PersonalizationPreviewCreator)

The single creator to generate a preview for.

message_body
required
string (Message Body) [ 1 .. 4000 ] characters

The DM template with [Block] tokens (mirrors the automation's CREATOR_MESSAGE).

tone
string (Tone)
Default: "engaging"
Enum: "engaging" "bold" "inspirational"
fallback_message
required
string (Fallback Message) [ 1 .. 4000 ] characters

Sent (name/product blocks filled) when the creator has too little signal to personalize. Required — matches the DM config contract: personalization must always have a safe fallback, so a low-signal preview never returns an empty message.

brand_name
string (Brand Name) <= 200 characters
Default: ""

Brand display name used in the copy. Defaults to the shop name when omitted.

product_description
string (Product Description) <= 4000 characters
Default: ""

Pre-resolved [Product Description]. Get it from POST /personalization/product-blocks.

product_selling_points
string (Product Selling Points) <= 2000 characters
Default: ""

Pre-resolved [Product Selling Points]. Get it from POST /personalization/product-blocks.

offer_discussion
string (Offer Discussion) <= 2000 characters
Default: ""

[Offer Discussion] block value — the brand's offer text.

Responses

Request samples

Content type
application/json
{
  • "creator": {
    },
  • "message_body": "string",
  • "tone": "engaging",
  • "fallback_message": "string",
  • "brand_name": "",
  • "product_description": "",
  • "product_selling_points": "",
  • "offer_discussion": ""
}

Response samples

Content type
application/json
{
  • "creator_id": "string",
  • "message": "string",
  • "is_fallback": true,
  • "blocks_used": [
    ]
}

Resolve product description + derive selling points

Resolve the two product-sourced personalization blocks for one of your products: [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.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
product_id
required
string (Product Id) [ 1 .. 100 ] characters

A product id in this shop's catalog. Blocks resolve empty if it isn't.

Responses

Request samples

Content type
application/json
{
  • "product_id": "string"
}

Response samples

Content type
application/json
{
  • "product_description": "",
  • "product_selling_points": ""
}

Rewrite a message body in a new tone

Rewrite the shared message body in a new tone (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.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
message_body
required
string (Message Body) [ 1 .. 4000 ] characters

The message body to rewrite. Every [Block] token is preserved.

tone
string (Tone)
Default: "engaging"
Enum: "engaging" "bold" "inspirational"

Responses

Request samples

Content type
application/json
{
  • "message_body": "string",
  • "tone": "engaging"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Personalization fallback usage for one automation

How many of an automation's personalized outreach messages used the brand fallback (creator had too little signal to personalize) versus were fully personalized. A lifetime aggregate across every send run of the automation, plus the 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id)

Responses

Response samples

Content type
application/json
{
  • "automation_id": 0,
  • "messages_sent": 0,
  • "fallback_used": 0,
  • "fallback_rate": 0
}

Personalized messages a creator was actually sent

The personalized outreach messages this shop sent to one creator (the creator record's audit trail), newest first — the exact copy, whether it was fully personalized or fell back. Rows are recorded when the send engine locks the copy for delivery, so 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_id
required
string (Creator Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "creator_id": "string",
  • "count": 0,
  • "messages": [
    ]
}

Target Collabs

Send a single TikTok Shop Target Collab invitation to one creator by handle — convenience surface over the two-step automation create + start. For >10 invites at a time, use POST /automations/target-collab with a multi-creator audience instead. Also exposes GET/PUT /target-collabs/support-contact-default to configure a shop-level default support_contact, which the TC create surfaces fall back to when a request omits it.

Send a Target Collab invite directly

Send a single TikTok Shop Target Collab (TC) invitation to a creator by handle. This is a convenience surface — it internally creates a single-creator TC automation and immediately starts it.

Queued semantics. The response returns immediately with 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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
creator_handle
required
string (Creator Handle) [ 1 .. 64 ] characters

TikTok @-handle (without the @). Resolved server-side against this shop's CRM / affiliate list (a row in crm_creators for reacher_shop_id=<shop_id> whose creator_name matches the handle, ordered by GMV via a LEFT JOIN against the region's creator table). The creator must already have interacted with your shop — handles for creators who haven't applied / sampled / transacted yet will not resolve, even if the handle exists globally on TikTok. Unknown handle → 404 CREATOR_NOT_FOUND.

product_id
required
string (Product Id) [ 1 .. 64 ] characters

TikTok Shop product ID to attach to the invitation.

commission_rate
required
number (Commission Rate) [ 0 .. 1 ]

Affiliate commission rate (0.0-1.0, e.g. 0.20 for 20%).

Shop Ads Commission Rate (number) or Shop Ads Commission Rate (null) (Shop Ads Commission Rate)

Optional Shop Ads (co-funded) commission rate (0.0-1.0). When set, persists into the legacy PRODUCTS blob at the per-product level; the TC runtime fills the matching field on the TC form. Omit to leave unset (worker treats as not configured).

message
required
string (Message) [ 1 .. 500 ] characters

TC card message body shown to the creator (max 500 chars). Mirrors target_collab.message on the full TC create surface — the portal rejects bodies containing the word amazon.

invitation_name
required
string (Invitation Name) [ 1 .. 30 ] characters

Name shown on the TC invitation card (max 30 chars). Same field as target_collab.invitation_name on the full TC create.

Valid Until (string) or Valid Until (null) (Valid Until)

Date the TC card stops being valid. Defaults to today + 30 days when omitted. After this date the dispatcher stops the underlying automation (see internal/queries/automations_to_run.py).

TargetCollabDirectSupportContact (object) or null

Brand-side support contact shown on the TC card. Optional ONLY when this shop has a default configured via PUT /public/v1/target-collabs/support-contact-default (CORE-5428) — in that case it's used as the fallback. When provided here it overrides the shop default for this request. If neither is present the request is rejected with 422 SUPPORT_CONTACT_REQUIRED.

Responses

Request samples

Content type
application/json
{
  • "creator_handle": "string",
  • "product_id": "string",
  • "commission_rate": 1,
  • "shop_ads_commission_rate": 1,
  • "message": "string",
  • "invitation_name": "string",
  • "valid_until": "2019-08-24",
  • "support_contact": {
    }
}

Response samples

Content type
application/json
{
  • "automation_id": 0,
  • "status": "string",
  • "creator_id": "string",
  • "creator_handle": "string",
  • "shop_id": 0,
  • "check_status_at": "string",
  • "queued_at": "string",
  • "dry_run": false
}

Get the shop's default Target Collab support contact

Read the shop-level default 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).

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
{
  • "shop_id": 0,
  • "configured": true,
  • "email": "string",
  • "phone": "string",
  • "updated_at": "string"
}

Set the shop's default Target Collab support contact

Configure the shop-level default 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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
Request Body schema: application/json
required
email
required
string (Email) [ 3 .. 255 ] characters

Default contact email shown to the creator on the TC card.

Phone (string) or Phone (null) (Phone)

Optional default contact phone. E.164 format recommended.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "shop_id": 0,
  • "configured": true,
  • "email": "string",
  • "phone": "string",
  • "updated_at": "string"
}

Metrics

Time-series metrics for dashboards and charts.

Time-series metrics

Fetch time-series data for one or more metrics over a date range. Returns daily/weekly/monthly data points for charting trends. Available metrics: gmv (affiliate-attributed), total_gmv (full shop from the Seller Center scrape), creators, videos_posted, video_views, gmv_per_video, gmv_per_sample, creators_reached, creators_messaged, tc_invites_sent, samples_approved, sample_requests, gmv_driving_videos, new_creators_posting, open_collabs, accepted_tc_count, emails_sent, dm_responses, reply_rate. Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (aov/ctr/conversion_rate are ratios computed over the full window, not averages of daily ratios; 0 for shops not yet on the Seller Center sync). Granularity (day/week/month) is auto-detected based on the date range if not specified. IMPORTANT: 'creators' returns distinct creators PER DAY — summing daily values double-counts creators active on multiple days. For the headline distinct count over the full period, use POST /metrics/summary instead. Similarly, gmv_per_video and gmv_per_sample are daily ratios — use /metrics/summary for the period-level headline values. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes).

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
metrics
required
Array of strings (Metrics) [ 1 .. 24 ] items
Items Enum: "gmv" "total_gmv" "creators" "videos_posted" "video_views" "gmv_per_video" "gmv_per_sample" "creators_reached" "creators_messaged" "tc_invites_sent" "samples_approved" "sample_requests" "gmv_driving_videos" "new_creators_posting" "open_collabs" "accepted_tc_count" "emails_sent" "dm_responses" "reply_rate" "orders" "units_sold" "aov" "ctr" "conversion_rate"
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Granularity (string) or Granularity (null) (Granularity)

Responses

Request samples

Content type
application/json
{
  • "metrics": [
    ],
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "granularity": "day"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "granularity": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "currency": "string",
  • "shops_queried": [
    ]
}

Dashboard headline metrics

Pre-computed headline scalar metrics for a date range, matching the Reacher dashboard's top-level KPIs exactly. Use this for summary cards and headline numbers. Includes derived metrics like active_creators (distinct count, not daily sum), gmv_per_video, and gmv_per_sample. Also includes Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (all-channel; aov/ctr/conversion_rate are ratios computed over the full window). Defaults to the last 30 days if no dates are specified. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes).

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
Any of
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Request samples

Content type
application/json
Example
{
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "gmv": 0,
  • "total_gmv": 0,
  • "active_creators": 0,
  • "video_views": 0,
  • "videos_posted": 0,
  • "samples_approved": 0,
  • "gmv_per_video": 0,
  • "gmv_per_sample": 0,
  • "sample_requests": 0,
  • "gmv_driving_videos": 0,
  • "new_creators_posting": 0,
  • "open_collabs": 0,
  • "accepted_tc_count": 0,
  • "creators_reached": 0,
  • "creators_messaged": 0,
  • "tc_invites_sent": 0,
  • "emails_sent": 0,
  • "dm_responses": 0,
  • "reply_rate": 0,
  • "orders": 0,
  • "units_sold": 0,
  • "aov": 0,
  • "ctr": 0,
  • "conversion_rate": 0,
  • "errors": [
    ],
  • "start_date": "string",
  • "end_date": "string",
  • "currency": "string",
  • "shops_queried": [
    ]
}

Shop GMV

Full TikTok Seller Center shop GMV (ads + organic + affiliate) — daily series and window totals with channel breakdown. Distinct from POST /metrics/timeseries metric=gmv, which is affiliate-attributed only.

Daily shop GMV time series (Seller Center, full shop view)

Daily GMV for one shop from the TikTok Seller Center daily rollup, including channel breakdown (video → affiliate/seller, live → affiliate/seller, product_card → shop_tab/search) and traffic (product impressions/clicks).

Differs from POST /metrics/timeseries metric=gmv — that endpoint reports affiliate-attributed GMV only (Reacher's view of creator-driven sales). This endpoint reports the total shop GMV including ads / Smart+ and organic. Use this when the customer wants numbers matching their TikTok Seller Center dashboard.

Single-shop only — set 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.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
Start Date (string) or Start Date (null) (Start Date)

Inclusive window start (YYYY-MM-DD). Defaults to 29 days before end_date (30-day window). The Seller Center data is back-filled ~90 days per shop, so older ranges will return an empty series.

End Date (string) or End Date (null) (End Date)

Inclusive window end (YYYY-MM-DD). Defaults to yesterday (today is excluded because the daily row is still incomplete).

Responses

Request samples

Content type
application/json
{
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "shop_id": 0,
  • "currency_code": "string",
  • "granularity": "daily",
  • "start_date": "string",
  • "end_date": "string",
  • "series": [
    ]
}

Shop GMV window totals (Seller Center, full shop view)

Window totals for one shop from the TikTok Seller Center daily rollup — SUMmed across the window with the same channel hierarchy as the timeseries response.

Same coverage caveats as the timeseries endpoint. 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.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
Any of
Start Date (string) or Start Date (null) (Start Date)

Inclusive window start (YYYY-MM-DD). Defaults to 29 days before end_date.

End Date (string) or End Date (null) (End Date)

Inclusive window end (YYYY-MM-DD). Defaults to yesterday.

Responses

Request samples

Content type
application/json
Example
{
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "shop_id": 0,
  • "currency_code": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "day_count": 0,
  • "gmv": 0,
  • "orders": 0,
  • "items_sold": 0,
  • "customers": 0,
  • "aov": 0,
  • "channels": {
    },
  • "traffic": {
    }
}

Analytics

Affiliate funnel and creator level distributions.

Affiliate funnel overview

Affiliate funnel stage counts matching the dashboard's 'Affiliate Funnel' section. Shows creators at each stage: sample requested, approved, content posted, content unfulfilled, GMV generated, and top creators (>$10k GMV). Data is based on the last 90 days.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
null

GMV Max

TikTok Smart+ (GMV Max) campaigns and daily performance metrics for your shop.

List GMV Max campaigns

List all GMV Max (TikTok Smart+) campaigns for the shop(s) addressed by 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).

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "shops_queried": [
    ]
}

Daily GMV Max campaign metrics

Daily performance metrics (spend, impressions, clicks, orders, gross_revenue, ROAS, CPC, CPM, CTR) for one campaign over a date range. Date range may not exceed 90 days (inclusive). Defaults to the last 30 days. Multi-shop is supported — when multiple shops are addressed via x-shop-id (a comma-separated list or all), the campaign's owning shop is resolved automatically and metrics are returned for that shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
string (Campaign Id) [ 1 .. 64 ] characters
query Parameters
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)

Responses

Response samples

Content type
application/json
{
  • "campaign_id": "string",
  • "shop_id": 0,
  • "data": [
    ],
  • "start_date": "string",
  • "end_date": "string",
  • "currency": "string"
}

GMV Max dashboard KPIs

Aggregated GMV Max KPIs for a shop over a recent window, with previous-period comparison: spend, revenue, orders, impressions, clicks, ROAS — plus a per-day breakdown for charting. Single shop only (set x-shop-id to a specific shop ID). Mirrors the portal Dashboard exactly.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
days
integer (Days) [ 1 .. 90 ]
Default: 7

Window size in days (default 7).

Responses

Response samples

Content type
application/json
null

GMV Max campaign detail

Detail for one campaign: name, status, ad type, budget, ROAS bid, last sync time, plus the campaign's daily metric rows (spend, impressions, clicks, orders, gross_revenue, CPC, CPM, CTR, ROAS). Single shop only — the caller must address the campaign's owning shop via x-shop-id. For multi-shop callers, use the /campaigns list endpoint to discover which shop owns a campaign before requesting its detail.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
string (Campaign Id) [ 1 .. 64 ] characters

Responses

Response samples

Content type
application/json
null

GMV Max creatives for a campaign

List the synced creatives (videos, spark codes, etc.) attached to a specific GMV Max campaign, with per-creative performance summaries. Single shop only.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
campaign_id
required
string (Campaign Id) [ 1 .. 64 ] characters

GMV Max campaign ID.

Responses

Response samples

Content type
application/json
null

GMV Max spark code sync state

Cached spark-code sync state for the shop: which codes are queued, in flight, succeeded, or failed against TikTok. Read-only — sync itself is JWT-only on the portal. Single shop only.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
null

GMV Max automation quick-start templates

Hard-coded set of quick-start automation templates the portal exposes (e.g. 'Boost top performers', 'Wind down low-ROAS'). Useful as a starting point when scaffolding an automation via the Phase-2 writes API. Not shop-scoped — same set for every caller.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
null

List GMV Max automations

List all GMV Max automations configured for the shop, with their current status, trigger frequency, boost window, and last-run summary. Single shop only — automations are per-shop.

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
null

Create a GMV Max automation

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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
Template Type (string) or Template Type (null) (Template Type)

Optional reference to one of the /templates template_type values the automation was scaffolded from. Free-form — does not affect execution.

trigger_frequency
string (TriggerFrequency)
Default: "daily"
Value: "daily"

How often the automation evaluates. Only daily is wired up today.

campaign_ids
Array of strings (Campaign Ids)

TikTok GMV Max campaign IDs the automation acts on. Each campaign_id can only be assigned to one active automation at a time — the controller rejects conflicts with a 422.

Array of objects (Conditions)
Array of objects (Actions)
Array of objects (Guardrails)
Boost Start Date (string) or Boost Start Date (null) (Boost Start Date)

First day boosts may fire. Must be paired with boost_end_date. Window cannot exceed 90 days.

Boost End Date (string) or Boost End Date (null) (Boost End Date)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "template_type": "string",
  • "trigger_frequency": "daily",
  • "campaign_ids": [
    ],
  • "conditions": [
    ],
  • "actions": [
    ],
  • "guardrails": [
    ],
  • "boost_start_date": "2019-08-24",
  • "boost_end_date": "2019-08-24"
}

Response samples

Content type
application/json
null

GMV Max automation detail

Detail for one automation: full configuration (conditions, actions, guardrails) plus its 10 most recent runs. Single shop only — automation_ids are scoped per shop.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1

Responses

Response samples

Content type
application/json
null

Update a GMV Max automation

Patch an existing automation. Only active, non-expired automations are editable — stopped, deleted, or past-end-date rows return 422 with 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
TriggerFrequency (string) or null
Array of Campaign Ids (strings) or Campaign Ids (null) (Campaign Ids)
Array of Conditions (objects) or Conditions (null) (Conditions)
Array of Actions (objects) or Actions (null) (Actions)
Array of Guardrails (objects) or Guardrails (null) (Guardrails)
Boost Start Date (string) or Boost Start Date (null) (Boost Start Date)
Boost End Date (string) or Boost End Date (null) (Boost End Date)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "trigger_frequency": "daily",
  • "campaign_ids": [
    ],
  • "conditions": [
    ],
  • "actions": [
    ],
  • "guardrails": [
    ],
  • "boost_start_date": "2019-08-24",
  • "boost_end_date": "2019-08-24"
}

Response samples

Content type
application/json
null

Delete (soft) a GMV Max automation

Soft-delete an automation (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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
null

GMV Max automation run history

Full run history for one automation (most recent first), including trigger source, start/finish timestamps, success/failure status, and per-run summary metrics. Single shop only.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1

Responses

Response samples

Content type
application/json
null

GMV Max automation activity log

Paginated per-event activity log for one automation (campaign boost / cancel events the automation produced), plus an aggregate summary across the full history. Supports the same status and search filters the portal does. Single shop only.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1
query Parameters
Status (string) or Status (null) (Status)

Filter by activity status (matches portal).

Search (string) or Search (null) (Search)

Free-text search across activity rows.

page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json
null

Stop a GMV Max automation

Mark an automation 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
automation_id
required
integer (Automation Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
null

Sync specific spark codes to TikTok

Synchronously authorise the listed spark codes against the shop's TikTok Business ad account. Each code fires one TikTok /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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
spark_codes
required
Array of strings (Spark Codes) [ 1 .. 100 ] items

Up to 100 spark codes to sync in one request. Each code fires one TikTok /tt_video/authorize/ call; rate-limited codes are left as pending so the offline CRJ picks them up. Whitespace is stripped; blank or duplicate entries are rejected with 422.

Responses

Request samples

Content type
application/json
{
  • "spark_codes": [
    ]
}

Response samples

Content type
application/json
null

Queue every unsynced spark code for sync

Queue every spark code for the shop that isn't already 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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
Any of
object (SparkCodeSyncAllRequestPublic)

POST /public/v1/gmv-max/spark-codes/sync-all — queue every unsynced code for the shop. Returns immediately with a queue count; the offline CRJ actually fires the TikTok calls.

Has no body fields (shop_id comes from x-shop-id); kept as a model so we can still extra="forbid" against accidental payloads.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
null

Search creators with natural language

Search the global TikTok creator universe with a natural-language query. Returns paginated creator results scored against the query, with optional browse mode when query is omitted (returns top creators in the shop's region). Requires a single x-shop-id — the shop's region determines which regional creator table is searched.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
Query (string) or Query (null) (Query)

Natural-language search query. Whitespace-only is treated as no query (browse mode).

page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "page": 1,
  • "page_size": 20
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Export creator search results as CSV

Export up to 50,000 matching creators as CSV. The response is a streaming attachment; the X-Creator-Row-Count response header reports the actual row count. CSV only — XLSX is not supported on the public API. Requires a single x-shop-id.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
Query (string) or Query (null) (Query)

Natural-language search query. Omit (or pass whitespace-only) to export the full browse universe for your shop's region.

Array of Creator Ids (strings) or Creator Ids (null) (Creator Ids)

Explicit list of creator IDs to export. Mutually exclusive with query.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "creator_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Creator Messages

Read the shop's creator DM inbox and reply to creators programmatically (e.g. from an AI agent). Replies require the read_write scope and only work in conversations a creator has already opened.

List creator conversations

The shop's creator DM inbox. Use unreplied_only=true to get conversations awaiting a reply (what an AI agent typically iterates).

Authorizations:
(ApiKeyAuthShopId)
query Parameters
offset
integer (Offset) >= 0
Default: 0
limit
integer (Limit) [ 1 .. 200 ]
Default: 50
unread_only
boolean (Unread Only)
Default: false
unreplied_only
boolean (Unreplied Only)
Default: false

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "offset": 0,
  • "limit": 0,
  • "has_more": true,
  • "total_count": 0
}

Get the message thread with a creator

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
query Parameters
page
integer (Page) >= 1
Default: 1

Responses

Response samples

Content type
application/json
{
  • "creator_handle": "string",
  • "data": [
    ],
  • "page": 0,
  • "has_more": true
}

Send a text reply to a creator

Sends a plain-text DM to the creator in an EXISTING conversation (the creator must have an open thread with the shop — TikTok does not allow cold-opening a DM). Idempotency-Key required. X-Dry-Run: true validates and echoes without contacting TikTok.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
message
required
string (Message) [ 1 .. 4000 ] characters

Plain-text reply body to send to the creator.

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "dry_run": true,
  • "would_send_to": "string",
  • "message": "string"
}

Send an image reply to a creator

Send a TikTok IMAGE message. Provide an HTTPS image_url; we fetch it server-side, upload to TikTok, and dispatch into the existing conversation. Same auth/scope/idempotency/rate-limit/X-Dry-Run semantics as the text reply. v1: no caption (send a text reply separately if you also want copy).

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
image_url
required
string (Image Url) [ 10 .. 2000 ] characters

HTTPS URL of an image to forward to the creator. We fetch it server-side (must resolve to a public IP, return Content-Type image/*, ≤ 5 MB), then upload to TikTok and dispatch.

Responses

Request samples

Content type
application/json
{
  • "image_url": "stringstri"
}

Response samples

Content type
application/json
{
  • "dry_run": true,
  • "would_send_to": "string",
  • "image_url": "string"
}

Send a product-card reply to a creator

Send a TikTok PRODUCT_CARD message linking one of THIS shop's products. We verify the product_id belongs to the shop's catalog. Same auth/scope/idempotency/rate-limit/X-Dry-Run semantics as the text reply. No caption (send a text reply separately for copy).

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
product_id
required
string (Product Id) [ 1 .. 64 ] characters

A TikTok product_id from THIS shop's catalog. Sending another shop's product_id is rejected with 400.

Responses

Request samples

Content type
application/json
{
  • "product_id": "string"
}

Response samples

Content type
application/json
{
  • "dry_run": true,
  • "would_send_to": "string",
  • "product_id": "string"
}

Stage a draft reply on a creator conversation

Persist a reply on the conversation WITHOUT delivering it to the creator. The draft surfaces in the Reacher inbox for a human to review and either send via the existing /reply* endpoints or discard via DELETE /drafts/{id}. Idempotency-Key required. X-Dry-Run: true validates and echoes without persisting.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
creator_handle
required
string (Creator Handle) [ 1 .. 255 ] characters

The creator's TikTok handle (with or without leading @). Must already have an open conversation with this shop — drafts can only be staged on existing conversations, the same prerequisite TikTok enforces on the live-send path.

Text (string) or Text (null) (Text)

Plain-text reply body. Set this OR image_url OR product_id (exactly one).

Image Url (string) or Image Url (null) (Image Url)

HTTPS URL of an image to send. Same SSRF + size + type constraints as the live /reply/image endpoint will apply when the human ships the draft — we do NOT fetch the URL at draft time (no outbound network call from this endpoint). Set this OR text OR product_id (exactly one).

Product Id (string) or Product Id (null) (Product Id)

A TikTok product_id from THIS shop's catalog. Ownership is verified ONLY when the human clicks Send in the inbox — the draft endpoint does not pre-check the catalog (the catalog can change between draft and send anyway). Set this OR text OR image_url (exactly one).

Responses

Request samples

Content type
application/json
{
  • "creator_handle": "string",
  • "text": "string",
  • "image_url": "stringstri",
  • "product_id": "string"
}

Response samples

Content type
application/json
{
  • "dry_run": true,
  • "would_create_for_handle": "string",
  • "content_type": "string",
  • "text": "string",
  • "image_url": "string",
  • "product_id": "string"
}

List staged drafts on a conversation

Drafts for the given creator on this shop, newest first. Drafts only — does NOT return sent messages (see GET /conversations/{handle}/messages for those).

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_handle
required
string (Creator Handle)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 25

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0,
  • "has_more": true
}

Discard a staged draft

Remove a draft by id. 404 if the id is unknown, 403 if the draft belongs to a different shop than the caller's x-shop-id. Idempotency-Key is NOT required for delete (delete is naturally idempotent — a second DELETE just returns 404).

Authorizations:
(ApiKeyAuthShopId)
path Parameters
draft_id
required
integer (Draft Id)
header Parameters
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Campaigns

Create and manage Creator Community Campaigns — Retainer, Challenge, Leaderboard, and Live GMV Challenge types. Full surface: CRUD, creator accept/reject/reactivate/remove, cross-shop add-to-campaign (move) with region + same-customer guards, content tracking, request-more-content, deposit-intent + settlement with full idempotency + dry-run + audit logging on the money-moving path.

List campaigns

Paginated list of the shop's creator campaigns with status/type filters and sortable columns. Returns counts per status tab (all/active/past/draft) and per type (retainer/challenge/leaderboard).

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20
Status (string) or Status (null) (Status)

UI alias: 'active' (= published), 'past' (= ended), 'draft' (= unpublished drafts), or 'archived'.

CampaignType (string) or Campaign Type (null) (Campaign Type)

Filter: retainer | challenge | leaderboard | live_gmv_challenge.

Search (string) or Search (null) (Search)
Date From (string) or Date From (null) (Date From)

YYYY-MM-DD; start_date >= date_from

Date To (string) or Date To (null) (Date To)

YYYY-MM-DD; end_date <= date_to

Sort By (string) or Sort By (null) (Sort By)

campaign_name | campaign_type | gmv | start_date | end_date | total_posts | total_views | created_at

sort_order
string (Sort Order) ^(asc|desc)$
Default: "desc"

Responses

Response samples

Content type
application/json
null

Create a 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.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
campaign_name
required
string (Campaign Name) <= 255 characters
campaign_type
required
string (CampaignType)
Enum: "retainer" "challenge" "leaderboard" "live_gmv_challenge"

Supported campaign types.

creator_source
required
string (CreatorSource)
Enum: "my_community" "social_army"

How creators are sourced for a campaign.

start_date
required
string (Start Date)
End Date (string) or End Date (null) (End Date)

YYYY-MM-DD. REQUIRED for challenge / leaderboard / live_gmv_challenge campaigns (the portal launch form requires an end date for these); optional only for retainer campaigns, which may run open-ended.

Description (string) or Description (null) (Description)

REQUIRED for launch. Rich-text (HTML) campaign description shown to creators. Must contain visible text — an empty string or HTML-only value like '

' is rejected, matching the portal launch form.

status
string (CampaignStatus)
Default: "published"
Enum: "published" "draft" "deleted" "archived"

DB-level campaign status. The frontend filter param 'active'/'past' are UI aliases — 'active' maps to published, 'past' maps to != published.

required
any (Pricing)
CampaignProducts (object) or null

REQUIRED for launch. The portal launch form needs at least one product: send products.all_selected=true to include every shop product, or products.items=[...] with 1-10 products.

Array of Creators (objects) or Creators (null) (Creators)

Optional list of creators to seed into the campaign. Mirrors the portal's contract exactly (see community.schemas.campaign.CampaignCreate.creators) so the public API doesn't fork from /api/marketplace/v2. Each dict is opaque to validation but is typically {"creator_id": int, "tier": str | None, "payout_override": int | None}. Pass null or omit for the common case of "no seeded creators" (production fixtures all do this; creators are added later via the accept/reject flow).

Window Url (string) or Window Url (null) (Window Url)

HTTPS URL — public landing/preview page for this campaign.

is_available_to_all
boolean (Is Available To All)
Default: false
requires_approval
boolean (Requires Approval)
Default: false
Array of Creator Level (strings) or Creator Level (string) or Creator Level (null) (Creator Level)

Creator tier filter (list or CSV string).

Support Email (string) or Support Email (null) (Support Email)
Short Header Message (string) or Short Header Message (null) (Short Header Message)

REQUIRED for launch. Short headline shown on the campaign card. Must be a non-empty string — the portal launch form rejects a blank value.

Content Guidelines (object) or Content Guidelines (null) (Content Guidelines)
Array of Inspiration Links (strings) or Inspiration Links (null) (Inspiration Links)

List of HTTPS URLs (inspiration videos, mood-boards, etc.).

has_tiered_payout
boolean (Has Tiered Payout)
Default: false
Payout Structure (object) or Payout Structure (null) (Payout Structure)
Grace Period (integer) or Grace Period (null) (Grace Period)
CampaignReminders (object) or null
CampaignEmailTemplates (object) or null

Responses

Request samples

Content type
application/json
{
  • "campaign_name": "string",
  • "campaign_type": "retainer",
  • "creator_source": "my_community",
  • "start_date": "string",
  • "end_date": "string",
  • "description": "string",
  • "status": "published",
  • "pricing": {
    },
  • "products": {
    },
  • "creators": [
    ],
  • "window_url": "string",
  • "is_available_to_all": false,
  • "requires_approval": false,
  • "creator_level": [
    ],
  • "support_email": "string",
  • "short_header_message": "string",
  • "content_guidelines": {
    },
  • "inspiration_links": [
    ],
  • "has_tiered_payout": false,
  • "payout_structure": { },
  • "grace_period": 365,
  • "reminders": {
    },
  • "email_templates": {
    }
}

Response samples

Content type
application/json
{
  • "campaign_id": 0,
  • "uuid_id": "string",
  • "status": "created",
  • "invite_link": "string"
}

List managed creators across all campaigns

All creators currently linked to the shop's campaigns. Includes overview metrics (total creators, multi-campaign creators, overall Return-On-Campaign-Spend) plus a paginated per-creator list.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20
Search (string) or Search (null) (Search)
Sort By (string) or Sort By (null) (Sort By)
sort_order
string (Sort Order) ^(asc|desc)$
Default: "desc"

Responses

Response samples

Content type
application/json
null

List shop-wide creator content

All videos posted by creators across the shop's campaigns. Returns overview metrics (total posts, views, orders, GMV, wallet balance) plus a paginated content list. Use the campaign-detail endpoint for a campaign-scoped view.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20
Search (string) or Search (null) (Search)
Sort By (string) or Sort By (null) (Sort By)
sort_order
string (Sort Order) ^(asc|desc)$
Default: "desc"

Responses

Response samples

Content type
application/json
null

Get marketplace wallet balance

Authorizations:
(ApiKeyAuthShopId)

Responses

Response samples

Content type
application/json
null

Payment / settlement history

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20
Search (string) or Search (null) (Search)
Sort By (string) or Sort By (null) (Sort By)
sort_order
string (Sort Order) ^(asc|desc)$
Default: "desc"

Responses

Response samples

Content type
application/json
null

Wallet deposit history

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page) >= 1
Default: 1
page_size
integer (Page Size) [ 1 .. 100 ]
Default: 20
Sort By (string) or Sort By (null) (Sort By)
sort_order
string (Sort Order) ^(asc|desc)$
Default: "desc"

Responses

Response samples

Content type
application/json
null

Get one campaign (edit-view shape)

Returns the campaign in the same shape PATCH /campaigns/{id} accepts.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1

Responses

Response samples

Content type
application/json
null

Update an existing campaign

Modify campaign fields. campaign_type and creator_source are immutable post-create — pass them and you'll get 400 IMMUTABLE_FIELD.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
Campaign Name (string) or Campaign Name (null) (Campaign Name)
Start Date (string) or Start Date (null) (Start Date)
End Date (string) or End Date (null) (End Date)
Description (string) or Description (null) (Description)
CampaignStatus (string) or null
Pricing (any) or Pricing (null) (Pricing)
CampaignProducts (object) or null
Array of Creators (objects) or Creators (null) (Creators)

Optional list of creators to seed into the campaign. Mirrors the portal's contract exactly (see community.schemas.campaign.CampaignCreate.creators) so the public API doesn't fork from /api/marketplace/v2. Each dict is opaque to validation but is typically {"creator_id": int, "tier": str | None, "payout_override": int | None}. Pass null or omit for the common case of "no seeded creators" (production fixtures all do this; creators are added later via the accept/reject flow).

Window Url (string) or Window Url (null) (Window Url)
Is Available To All (boolean) or Is Available To All (null) (Is Available To All)
Requires Approval (boolean) or Requires Approval (null) (Requires Approval)
Array of Creator Level (strings) or Creator Level (string) or Creator Level (null) (Creator Level)
Support Email (string) or Support Email (null) (Support Email)
Short Header Message (string) or Short Header Message (null) (Short Header Message)
Content Guidelines (object) or Content Guidelines (null) (Content Guidelines)
Array of Inspiration Links (strings) or Inspiration Links (null) (Inspiration Links)
Has Tiered Payout (boolean) or Has Tiered Payout (null) (Has Tiered Payout)
Payout Structure (object) or Payout Structure (null) (Payout Structure)
Grace Period (integer) or Grace Period (null) (Grace Period)
CampaignReminders (object) or null
CampaignEmailTemplates (object) or null

Responses

Request samples

Content type
application/json
{
  • "campaign_name": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "description": "string",
  • "status": "published",
  • "pricing": {
    },
  • "products": {
    },
  • "creators": [
    ],
  • "window_url": "string",
  • "is_available_to_all": true,
  • "requires_approval": true,
  • "creator_level": [
    ],
  • "support_email": "string",
  • "short_header_message": "string",
  • "content_guidelines": {
    },
  • "inspiration_links": [
    ],
  • "has_tiered_payout": true,
  • "payout_structure": { },
  • "grace_period": 365,
  • "reminders": {
    },
  • "email_templates": {
    }
}

Response samples

Content type
application/json
{
  • "campaign_id": 0,
  • "status": "updated"
}

Soft-delete a campaign

Sets status='deleted'. The row remains in the DB but is hidden from list/detail views. Idempotent.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "campaign_id": 0,
  • "status": "deleted"
}

Get the full campaign detail view

Full campaign detail: campaign metadata, applied/active creators with stage + payment-due + per-creator actions, aggregated stats (GMV, views, orders, payouts), and a content snippet. Equivalent to what the portal's campaign-detail page renders.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1

Responses

Response samples

Content type
application/json
null

Accept a creator into a campaign

Sets the creator's CampaignCreatorMapping.status='active'. Sends an acceptance email + SMS to the creator (fire-and-forget) — these are SKIPPED on X-Dry-Run: true.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
creator_id
required
integer (Creator Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
Any of
Message (string) or Message (null) (Message)

Optional custom message included in the creator's acceptance email/SMS. If omitted, the campaign's default acceptance template is used.

Responses

Request samples

Content type
application/json
Example
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "ok",
  • "data": { }
}

Reject a creator from a campaign

Sets CampaignCreatorMapping.status='rejected'. Sends a rejection email + SMS to the creator (fire-and-forget) — SKIPPED on dry-run.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
creator_id
required
integer (Creator Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
Any of
Message (string) or Message (null) (Message)

Optional custom message included in the creator's rejection email/SMS.

Responses

Request samples

Content type
application/json
Example
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "ok",
  • "data": { }
}

Reactivate a previously-rejected creator

Reverses a reject: status goes back to active. No new notification is sent.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
creator_id
required
integer (Creator Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "ok",
  • "data": { }
}

Remove a creator from a campaign

Removes the creator from ONE campaign (terminal 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_id
required
integer (Creator Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
Any of
campaign_id
required
integer (Campaign Id) > 0

Campaign (in the x-shop-id shop) to remove the creator from.

Message (string) or Message (null) (Message)

Optional SMS sent to the creator on removal. Removal is otherwise silent (no email, no default SMS). Length capped at 320 to match the service's SMS limit. SKIPPED on X-Dry-Run.

Responses

Request samples

Content type
application/json
Example
{
  • "campaign_id": 0,
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "ok",
  • "data": { }
}

Add a creator to another campaign (move)

Adds the creator to a target campaign — purely additive (never removes them from the source campaign). The SOURCE shop is your 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.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
creator_id
required
integer (Creator Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
target_campaign_id
required
integer (Target Campaign Id) > 0

Campaign the creator is being added to (lives in target_shop_id).

target_shop_id
required
integer (Target Shop Id) > 0

Shop that owns the target campaign. Must belong to the same customer as your API key (else 404).

notify
boolean (Notify)
Default: true

Send the creator an acceptance-style notification on add. SKIPPED on X-Dry-Run.

Responses

Request samples

Content type
application/json
{
  • "target_campaign_id": 0,
  • "target_shop_id": 0,
  • "notify": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "code": "ok",
  • "data": { }
}

Get a single video's full detail by id

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
video_id
required
string (Video Id) [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "video_id": "string"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "count": 0
}

List a creator-campaign mapping's posted videos

Used by the settlement screen to enumerate the videos a creator posted under a specific campaign.

Authorizations:
(ApiKeyAuthShopId)
Request Body schema: application/json
required
campaign_creator_mapping_id
required
integer (Campaign Creator Mapping Id) > 0

Responses

Request samples

Content type
application/json
{
  • "campaign_creator_mapping_id": 0
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": [
    ],
  • "count": 0
}

Archive a creator's content tracker

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

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
campaign_creator_mapping_id
required
integer (Campaign Creator Mapping Id) > 0

Responses

Request samples

Content type
application/json
{
  • "campaign_creator_mapping_id": 0
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string"
}

Request more content from a creator

Updates the creator's posts requirement and minimum GMV target on their CampaignCreatorMapping, then fires a notification (email + SMS) asking for additional posts — notifications SKIPPED on dry-run.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
creator_id
required
integer (Creator Id) > 0
campaign_creator_mapping_id
required
integer (Campaign Creator Mapping Id) > 0
campaign_id
required
integer (Campaign Id) > 0
additional_posts
required
integer (Additional Posts) [ 1 .. 100 ]
required
New Total Payout (number) or New Total Payout (string) (New Total Payout)

New total payout — number for cash campaigns, string label (e.g. 'free product') for custom-reward campaigns.

minimum_gmv_target
required
number (Minimum Gmv Target) > 0
Tiktok Username (string) or Tiktok Username (null) (Tiktok Username)
CreatorStatus (string) or null

Responses

Request samples

Content type
application/json
{
  • "creator_id": 0,
  • "campaign_creator_mapping_id": 0,
  • "campaign_id": 0,
  • "additional_posts": 1,
  • "new_total_payout": 0,
  • "minimum_gmv_target": 0,
  • "tiktok_username": "string",
  • "creator_status": "pending"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Create a Stripe Checkout session to top up the marketplace wallet

Returns a Stripe Checkout session_id + redirect_url. Creating the intent does NOT move money — money moves only when the user completes the hosted checkout. X-Dry-Run: true validates the body without calling Stripe.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
amount
required
number (Amount) ( 0 .. 100000 ]
currency
string (Currency) = 3 characters
Default: "USD"

ISO 4217 currency. The wallet's persisted currency overrides this for cross-currency safety.

success_url
required
string (Success Url) <= 2048 characters

URL Stripe redirects to on completion. Must use a Reacher-controlled host (app.reacherapp.com, portal.reacherapp.com, staging.reacherapp.com) or localhost/127.0.0.1 for development.

cancel_url
required
string (Cancel Url) <= 2048 characters

Responses

Request samples

Content type
application/json
{
  • "amount": 100000,
  • "currency": "USD",
  • "success_url": "string",
  • "cancel_url": "string"
}

Response samples

Content type
application/json
{
  • "session_id": "string",
  • "redirect_url": "string"
}

Settle a creator payment

Triggers a real Stripe transfer + wallet debit when reward_type='cash'. reward_type='custom' records the settlement only — no money moves. Idempotency-Key is REQUIRED and the inner PaymentService.settle runs claim/release semantics so a retry with the same key can never double-pay. Every successful settlement emits an audit.campaigns.settle log line for on-call reconciliation. X-Dry-Run: true skips the Stripe call entirely.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
creator_id
required
integer (Creator Id) > 0
campaign_id
required
integer (Campaign Id) > 0
amount
required
number (Amount) ( 0 .. 100000 ]

Settlement amount in the campaign's currency. Capped at $100,000 per call as a sanity guard.

currency
required
string (Currency) = 3 characters

ISO 4217 currency code (e.g. 'USD'). Informational — the shop's persisted wallet currency takes precedence at settlement time. If the wallet currency differs from this value, the transfer executes in the wallet currency without rejection. The response's currency field confirms the currency actually used for the transfer.

reward_type
required
string (Reward Type) ^(cash|custom)$

'cash' triggers a Stripe transfer + wallet debit; 'custom' records the settlement only (no money moves).

campaign_creator_mapping_id
required
integer (Campaign Creator Mapping Id) > 0

REQUIRED. The campaign-creator mapping id that the settlement is being recorded against. The portal surfaces this id on every creator row in GET /campaigns/{id}/detail and in the response to the accept endpoint, so callers always have it. Required because the underlying PaymentService.settle only runs its double-payment guard (claim_for_settlement_sync) when a mapping id is present — omitting it would leave the money-moving path with idempotency-only protection (a different Idempotency-Key per call could debit the wallet repeatedly with no DB-level guard).

Metadata (object) or Metadata (null) (Metadata)

Free-form metadata stored alongside the settlement (e.g. agent annotation, internal reference).

Responses

Request samples

Content type
application/json
{
  • "creator_id": 0,
  • "campaign_id": 0,
  • "amount": 100000,
  • "currency": "str",
  • "reward_type": "string",
  • "campaign_creator_mapping_id": 0,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "transfer_id": "string",
  • "amount": 0,
  • "currency": "string",
  • "paid_at": "string",
  • "wallet_balance": 0
}

Archive a campaign

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

Authorizations:
(ApiKeyAuthShopId)
path Parameters
campaign_id
required
integer (Campaign Id) >= 1
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
{
  • "campaign_id": 0,
  • "status": "archived"
}

Lists

Create a list

Upload a list of creator handles + emails. Two paths: JSON body OR multipart CSV (file field name file, columns creator_name required + email optional). Returned list_id is what callers pass to automations as lists_selected.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema:
required
name
required
string (Name) [ 1 .. 120 ] characters

Human-readable list name shown in the portal.

Description (string) or Description (null) (Description)
creator_handles
Array of strings (Creator Handles) <= 50000 items

TikTok handles, with or without leading '@'. Deduplicated case-insensitively at insert time.

creator_emails
Array of strings (Creator Emails) <= 50000 items

Email addresses. Deduplicated case-insensitively at insert time.

Responses

Request samples

Content type
{
  • "name": "string",
  • "description": "string",
  • "creator_handles": [
    ],
  • "creator_emails": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List the shop's lists

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page)
Default: 1
page_size
integer (Page Size)
Default: 50
Name Contains (string) or Name Contains (null) (Name Contains)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": null
}

Get a list with its members

Authorizations:
(ApiKeyAuthShopId)
path Parameters
list_id
required
integer (List Id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "creator_handles": [
    ],
  • "creator_emails": [
    ]
}

Delete a list (soft)

Sets state=archived. Idempotent — already-archived returns 200.

Authorizations:
(ApiKeyAuthShopId)
path Parameters
list_id
required
integer (List Id)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)

Responses

Response samples

Content type
application/json
null

CRM Groups

List CRM Groups

Paginated list of CRM Groups for this shop — creator cohorts you can target or exclude in automations. Membership is live for filter-built groups and frozen for groups built from a dashboard segment; see conditions on each group. Create segment-based groups with POST /crm-groups/from-segment; filter-built groups are still portal-only.

Authorizations:
(ApiKeyAuthShopId)
query Parameters
page
integer (Page)
Default: 1
page_size
integer (Page Size)
Default: 50
Name Contains (string) or Name Contains (null) (Name Contains)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": null
}

Create a CRM Group from a dashboard segment

Build a group from a Creators-tab segment — a GMV tier, an automation_id, and a date window — rather than from raw filter conditions. Use it to turn 'creators in tier L3 reached by automation 812 last month' into a reusable cohort you can target with an automation.

Membership is a snapshot. Members are materialized once at creation and do not update as creators enter or leave the segment. Re-post to refresh.

The window is always bounded. Omit start_date/end_date and the segment resolves over the trailing 28 days rather than the shop's whole history; the maximum span is 365 days. Pass both dates explicitly whenever the segment you have in mind is a specific period.

Creation upserts by name. Reusing an existing group_name in this shop overwrites that group's definition and replaces its members.

Expect fewer creators than the dashboard shows. Only CRM-tracked creators can be grouped, so DM-only and organic creators in the segment resolve to nothing. handles_resolved is what the segment matched; creator_count is what made it into the group. The gap between them is that drop-off — check it before treating the group as the segment.

X-Dry-Run: true reports the segment size and whether it exceeds the group limit, without writing. It cannot show the CRM drop-off: that is only known once the group is built.

Authorizations:
(ApiKeyAuthShopId)
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
X-Dry-Run (string) or X-Dry-Run (null) (X-Dry-Run)
Request Body schema: application/json
required
group_name
required
string (Group Name) [ 1 .. 255 ] characters

Name for the new group. Creation upserts by (shop, group_name) — reusing a name overwrites that group's definition and re-materializes its members.

Tier (string) or Tier (null) (Tier)

GMV tier code to narrow the segment, e.g. 'L3'. Omit for all tiers.

Automation Id (integer) or Automation Id (null) (Automation Id)

Restrict the segment to creators reached by this automation.

Start Date (string) or Start Date (null) (Start Date)

Segment window start (inclusive).

End Date (string) or End Date (null) (End Date)

Segment window end (inclusive).

Array of Group Tags (strings) or Group Tags (null) (Group Tags)

Optional tags to attach to the group.

Responses

Request samples

Content type
application/json
{
  • "group_name": "string",
  • "tier": "string",
  • "automation_id": 1,
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "group_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "dry_run": true
}

Get a CRM Group's filter conditions + member count

Authorizations:
(ApiKeyAuthShopId)
path Parameters
crm_group_id
required
string (Crm Group Id)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}