Reacher Data API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

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.

Base URLs:

• /public/v1

• https://api.reacherapp.com/public/v1

Authentication

• API Key (ApiKeyAuth)

  • Parameter Name: x-api-key, in: header. Your Reacher API key (starts with rk_live_)

• API Key (ShopId)

  • Parameter Name: x-shop-id, in: header. The shop ID to query. Accepts a single integer, a comma-separated list of integers (e.g. '101,202,303'), or 'all' to query every shop your API key has access to. Multi-shop responses include a 'shops_queried' field and use USD as the default currency. Detail endpoints (e.g. GET /creators/{handle}, GET /automations/{id}) require a single shop ID.

Shops

Discover your shops and their regions.

List your shops

GET /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.

Example responses

200 Response

{
  "data": [
    {
      "shop_id": 0,
      "shop_name": "string",
      "region": "string",
      "currency": "string",
      "status": "string",
      "primary_category": "string"
    }
  ]
}

Responses

Creators

Affiliates who have worked with your shop.

List creators

POST /creators/list

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.

Body parameter

{
  "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": [
    "string"
  ],
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "follower_count": 0,
      "status": "string",
      "shop_gmv": 0,
      "overall_gmv": 0,
      "overall_fulfillment_rate": 0,
      "shop_units_sold": 0,
      "shop_video_count": 0,
      "video_views": 0,
      "sample_received": 0,
      "commission_rate": 0,
      "est_commission": 0,
      "fulfillment_rate": 0,
      "tags": [
        "string"
      ],
      "product_id": "string",
      "product_title": "string",
      "updated_at": "string",
      "created_at": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Creator performance (date-filtered)

POST /creators/performance

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.

Body parameter

{
  "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
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_id": "string",
      "creator_handle": "string",
      "gmv": 0,
      "units_sold": 0,
      "order_count": 0,
      "est_commission": 0,
      "follower_count": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Creator activity totals for a window

POST /creators/summary

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.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": {
    "new_creators": 0,
    "gmv_generated": 0,
    "video_posts": 0,
    "orders": 0
  },
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  }
}

Responses

Daily series per creator

POST /creators/trends

Daily time series for up to 100 named creators — affiliate GMV, video GMV, videos posted, video views, units sold, and commission. Backs sparklines and per-creator trend comparisons.

Every series is aligned positionally with the days axis and zero-filled, so index i of any array corresponds to days[i]. Creators with no activity in the window appear with all-zero arrays rather than being omitted; handles that don't exist in this shop are listed in unresolved_handles instead.

Defaults to the trailing 28 days. Requires a single shop.

Body parameter

{
  "creator_handles": [
    "string"
  ],
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": {
    "property1": {
      "affiliate_gmv": [
        0
      ],
      "video_gmv": [
        0
      ],
      "videos_posted": [
        0
      ],
      "total_video_views": [
        0
      ],
      "units_sold": [
        0
      ],
      "commission": [
        0
      ]
    },
    "property2": {
      "affiliate_gmv": [
        0
      ],
      "video_gmv": [
        0
      ],
      "videos_posted": [
        0
      ],
      "total_video_views": [
        0
      ],
      "units_sold": [
        0
      ],
      "commission": [
        0
      ]
    }
  },
  "days": [
    "string"
  ],
  "unresolved_handles": [
    "string"
  ],
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  }
}

Responses

Creator distribution by GMV level

GET /creators/levels

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Get creator detail

GET /creators/{creator_handle}

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

Parameters

Example responses

200 Response

{
  "data": {
    "creator_handle": "string",
    "follower_count": 0,
    "status": "string",
    "shop_gmv": 0,
    "overall_gmv": 0,
    "overall_fulfillment_rate": 0,
    "shop_units_sold": 0,
    "shop_video_count": 0,
    "video_views": 0,
    "sample_received": 0,
    "commission_rate": 0,
    "est_commission": 0,
    "fulfillment_rate": 0,
    "tags": [
      "string"
    ],
    "product_id": "string",
    "product_title": "string",
    "updated_at": "string",
    "created_at": "string"
  },
  "groups": [],
  "products": [],
  "videos": [],
  "currency": "string"
}

Responses

List creator's videos

POST /creators/{creator_handle}/videos

Paginated list of videos by this creator in your shop.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "video_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

List creator's products

POST /creators/{creator_handle}/products

Products this creator is affiliated with in your shop.

Body parameter

{
  "page": 1,
  "page_size": 50
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_title": "string",
      "commission_rate": 0,
      "shop_units_sold": 0,
      "shop_gmv": 0,
      "status": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "shops_queried": [
    "string"
  ]
}

Responses

Products

Your products and their affiliate performance.

List products

POST /products/list

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.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "product_name": "string"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_name": "string",
      "gmv": 0,
      "units_sold": 0,
      "refund_units": 0,
      "video_count": 0,
      "sample_count": 0,
      "live_count": 0,
      "est_commission": 0,
      "product_status": "string",
      "sc_total_gmv": 0,
      "sc_orders": 0,
      "sc_units_sold": 0,
      "sc_customers": 0,
      "sc_aov": 0,
      "sc_impressions": 0,
      "sc_clicks": 0,
      "sc_ctr": 0,
      "sc_conversion": 0,
      "sc_gmv_per_1k_impr": 0,
      "sc_add_to_cart": 0,
      "sc_affiliate_gmv": 0,
      "sc_seller_video_gmv": 0,
      "sc_seller_live_gmv": 0,
      "sc_product_card_gmv": 0,
      "sc_shop_tab_gmv": 0,
      "sc_refunds": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

List product's creators

POST /products/{product_id}/creators

Creators affiliated with this product.

Body parameter

{
  "page": 1,
  "page_size": 50
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "follower_count": 0,
      "commission_rate": 0,
      "gmv": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "shops_queried": [
    "string"
  ]
}

Responses

List product's videos

POST /products/{product_id}/videos

Videos featuring this product.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "video_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Videos

Affiliate videos and performance metrics.

List videos

POST /videos/list

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.

Body parameter

{
  "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
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "video_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Top videos with creative breakdown

POST /videos/creative

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.

Body parameter

{
  "limit": 10,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "creator_handle": "string",
      "video_gmv": 0,
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "order_count": 0,
      "posted_date": "string",
      "rank": 0,
      "creative": {
        "analyzed": true,
        "hook": {
          "text": "string",
          "classification": "string",
          "reasoning": "string"
        },
        "sell_points": [
          "string"
        ],
        "product_niche": "string",
        "shot_style": [
          "string"
        ],
        "videography": {
          "locations": [
            "string"
          ],
          "lighting": [
            "string"
          ],
          "product_showcase": [
            "string"
          ],
          "notes": "string"
        },
        "missing_fields": [
          "string"
        ]
      }
    }
  ],
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "coverage": {
    "videos_returned": 0,
    "with_creative_analysis": 0
  },
  "total_count": 0,
  "message": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

Video performance (date-filtered)

POST /videos/performance

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.

Body parameter

{
  "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
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "creator_handle": "string",
      "video_gmv": 0,
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "order_count": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Samples

Sample request tracking and per-product breakdowns.

List sample requests

POST /samples/list

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.

Body parameter

{
  "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"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "product_id": "string",
      "product_title": "string",
      "status": "string",
      "gmv": 0,
      "units_sold": 0,
      "sample_received": 0,
      "updated_at": "string",
      "bio": "string",
      "categories": [
        "string"
      ],
      "email": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Sample metrics by product

POST /samples/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.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "total_requests",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_name": "string",
      "total_requests": 0,
      "approved": 0,
      "sample_gmv": 0,
      "videos_from_samples": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Automations

Automation performance and outreach metrics.

List automations

POST /automations/list

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.

Body parameter

{
  "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": [
    "string"
  ],
  "exclude_created_via": [
    "string"
  ]
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "automation_id": 0,
      "automation_name": "string",
      "automation_type": "string",
      "status": "string",
      "status_message": "string",
      "gmv": 0,
      "sample_requests": 0,
      "accepted_requests": 0,
      "videos_posted": 0,
      "videos_converted": 0,
      "creators_reached": 0,
      "dm_response_count": 0,
      "reply_rate": 0,
      "skipped": 0,
      "total_creators": 0,
      "creators_remaining": 0,
      "created_at": "string",
      "completed_at": "string",
      "created_via": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ],
  "aggregate": {
    "creators_reached": 0,
    "tc_invites": 0,
    "tc_invites_creator_count": 0,
    "creators_messaged": 0,
    "emails_sent": 0,
    "sample_request": 0,
    "sample_approved": 0,
    "videos_posted": 0,
    "videos_converted": 0,
    "spark_codes": 0,
    "added_showcase_affiliates": 0,
    "accepted_tc_count": 0,
    "tc_showcase_creator_count": 0,
    "tc_content_creator_count": 0,
    "tc_acceptance_rate": 0
  }
}

Responses

Region-specific filter options

GET /automations/filters

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).

Parameters

Example responses

200 Response

null

Responses

Response Schema

Outreach send capacity for this shop

GET /automations/outreach-capacity

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.

Example responses

200 Response

{
  "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
}

Responses

Get automation detail

GET /automations/{automation_id}

Detailed automation data with performance metrics.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "status": "string",
    "status_message": "string",
    "gmv": 0,
    "sample_requests": 0,
    "accepted_requests": 0,
    "videos_posted": 0,
    "videos_converted": 0,
    "creators_reached": 0,
    "dm_response_count": 0,
    "reply_rate": 0,
    "skipped": 0,
    "total_creators": 0,
    "creators_remaining": 0,
    "created_at": "string",
    "completed_at": "string",
    "created_via": "string"
  },
  "creators_remaining": 0,
  "currency": "string"
}

Responses

Update automation

PATCH /automations/{automation_id}

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

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "target_collab": {
    "invitation_name": "string",
    "valid_until": "2019-08-24",
    "message": "string",
    "products": [
      {
        "product_id": "string",
        "commission_rate": 1,
        "shop_min_commission": 1,
        "shop_ads_commission_rate": 1
      }
    ],
    "content_type": "no_preference",
    "sample_policy": {
      "offer_free_samples": true,
      "auto_approve": true,
      "send_to": "brand_recipient"
    },
    "support_contact": {
      "email": "string",
      "phone": "string"
    },
    "lock_receivers_profiles": true
  },
  "dm_config": {
    "spark_code": {
      "only_collect_creator_information": false,
      "spark_code_submission_url": "string"
    }
  },
  "sample_request": {
    "action": "approve",
    "rejection_reason": "NOT_MATCH",
    "approval_message": "string",
    "rejection_message": "string",
    "message_images": [
      "string"
    ],
    "products": {
      "include_all_products": false,
      "selected_products": [
        {
          "product_id": "string",
          "max_approvals_per_week": 10000
        }
      ],
      "weekly_auto_approval_per_product": 1
    },
    "minimum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "maximum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "auto_approval_settings": {
      "enabled": false,
      "total_weekly_approved_sample_limit": 1,
      "always_approve_status": "string",
      "always_approve_from_lists_ids": [
        0
      ]
    },
    "target_list": [
      0
    ]
  },
  "ai_enabled": true,
  "is_evergreen": true,
  "end_date": "2019-08-24",
  "business_hours_timezone": "string",
  "email_sent_per_day": 1,
  "subject": "string",
  "body": "string"
}

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Delete automation

DELETE /automations/{automation_id}

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

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Per-creator outcome ledger

GET /automations/{automation_id}/creators

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.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "outcome": "string",
      "status": "string",
      "detail": "string",
      "skip_reason": "string",
      "invitation_id": "string"
    }
  ],
  "summary": {
    "total": 0,
    "invite_submitted": 0,
    "outreach_sent": 0,
    "previously_invited": 0,
    "invite_removed": 0,
    "skipped": 0,
    "unknown": 0
  },
  "pagination": null
}

Responses

Automation message templates

GET /automations/{automation_id}/messages

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.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "automation_name": "string",
  "automation_type": "string",
  "tc_invite_message": "string",
  "message_sequence": [
    null
  ],
  "follow_up_steps": [
    null
  ],
  "ai_custom_qa": [
    null
  ],
  "personalization": {
    "enabled": false,
    "tone": "string",
    "fallback_message": "string",
    "offer_discussion": "string",
    "product_description": "string",
    "product_selling_points": "string"
  }
}

Responses

Exact sent message copy (grouped by creator)

GET /automations/{automation_id}/sent-messages

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.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "automation_name": "string",
  "automation_type": "string",
  "template": {
    "automation_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "tc_invite_message": "string",
    "message_sequence": [
      null
    ],
    "follow_up_steps": [
      null
    ],
    "ai_custom_qa": [
      null
    ],
    "personalization": {
      "enabled": false,
      "tone": "string",
      "fallback_message": "string",
      "offer_discussion": "string",
      "product_description": "string",
      "product_selling_points": "string"
    }
  },
  "dm_sent": {
    "exact_copy": true,
    "groups": [
      {
        "creator_name": "string",
        "creator_id": "string",
        "last_sent_at": "string",
        "messages": [
          {
            "content": "string",
            "sent_at": "string",
            "status": "string"
          }
        ]
      }
    ],
    "creators_returned": 0,
    "total_creators": 0,
    "total_messages": 0,
    "message": "string"
  },
  "tc_sent": {
    "exact_copy": false,
    "coverage_note": "string",
    "template_text": "string",
    "placeholders_present": false,
    "invitations": [
      {
        "sent_at": "string",
        "status": "string",
        "creator_count": 0,
        "creators": [
          "string"
        ],
        "creators_truncated": false,
        "expiration_date": "string"
      }
    ],
    "invitations_returned": 0,
    "total_invitations": 0,
    "total_creators_invited": 0,
    "status_breakdown": {
      "property1": 0,
      "property2": 0
    },
    "campaign": {
      "campaign_id": 0,
      "campaign_name": "string"
    },
    "message": "string"
  },
  "message": "string"
}

Responses

Create Target Collab automation

POST /automations/target-collab

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.

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "target_collab": {
    "invitation_name": "string",
    "valid_until": "2019-08-24",
    "message": "string",
    "products": [
      {
        "product_id": "string",
        "commission_rate": 1,
        "shop_min_commission": 1,
        "shop_ads_commission_rate": 1
      }
    ],
    "content_type": "no_preference",
    "sample_policy": {
      "offer_free_samples": false,
      "auto_approve": false,
      "send_to": "brand_recipient"
    },
    "support_contact": {
      "email": "string",
      "phone": "string"
    }
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "ai_enabled": false,
  "end_date": "2019-08-24",
  "auto_resolve_conflicts": "SKIP_ALL",
  "is_evergreen": false,
  "business_hours_timezone": "string"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create TC Cleanup automation

POST /automations/tc-cleanup

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.

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "products": [
    {
      "product_id": "string",
      "commission_rate": 1,
      "shop_min_commission": 1,
      "shop_ads_commission_rate": 1
    }
  ],
  "invite_start_before_days": 1,
  "invite_expire_after_days": 1,
  "end_date": "2019-08-24"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create DM automation

POST /automations/dm

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.

Body parameter

{
  "automation_name": "string",
  "mode": "vanilla",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "dm_config": {
    "spark_code": {
      "only_collect_creator_information": false,
      "spark_code_submission_url": "string"
    }
  },
  "personalization": {
    "enabled": true,
    "tone": "engaging",
    "fallback_message": "string",
    "offer_discussion": "",
    "product_description": "",
    "product_selling_points": ""
  },
  "ai_enabled": false,
  "end_date": "2019-08-24",
  "is_evergreen": false,
  "business_hours_timezone": "string"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create Email automation

POST /automations/email

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.

Body parameter

{
  "automation_name": "string",
  "email_account_id": 0,
  "subject": "string",
  "body": "string",
  "selection_mode": "mailing_list",
  "mailing_list": {
    "list_upload_emails": [
      "string"
    ],
    "lists_selected": [
      "string"
    ]
  },
  "filters": {
    "min_creator_gmv": 0,
    "min_followers": 0,
    "min_engagement_rate": 1,
    "min_avg_views": 0,
    "regions": [
      "string"
    ],
    "categories": [
      "string"
    ]
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "attachments": [
    {
      "name": "string",
      "url": "string"
    }
  ]
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create Sample Request auto-processing automation

POST /automations/sample-request

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.

Body parameter

{
  "automation_name": "string",
  "sample_request": {
    "action": "approve",
    "rejection_reason": "NOT_MATCH",
    "approval_message": "string",
    "rejection_message": "string",
    "message_images": [
      "string"
    ],
    "products": {
      "include_all_products": false,
      "selected_products": [
        {
          "product_id": "string",
          "max_approvals_per_week": 10000
        }
      ],
      "weekly_auto_approval_per_product": 1
    },
    "minimum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "maximum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "auto_approval_settings": {
      "enabled": false,
      "total_weekly_approved_sample_limit": 1,
      "always_approve_status": "string",
      "always_approve_from_lists_ids": [
        0
      ]
    },
    "target_list": [
      0
    ]
  },
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  }
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Start automation

POST /automations/{automation_id}/start

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.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Stop automation

POST /automations/{automation_id}/stop

Transition automation to stopped. Idempotent.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

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

POST /personalization/preview

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.

Body parameter

{
  "creator": {
    "creator_id": "string",
    "creator_handle": "string",
    "creator_first_name": ""
  },
  "message_body": "string",
  "tone": "engaging",
  "fallback_message": "string",
  "brand_name": "",
  "product_description": "",
  "product_selling_points": "",
  "offer_discussion": ""
}

Parameters

Example responses

200 Response

{
  "creator_id": "string",
  "message": "string",
  "is_fallback": true,
  "blocks_used": [
    "string"
  ]
}

Responses

Resolve product description + derive selling points

POST /personalization/product-blocks

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.

Body parameter

{
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "product_description": "",
  "product_selling_points": ""
}

Responses

Rewrite a message body in a new tone

POST /personalization/retone

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.

Body parameter

{
  "message_body": "string",
  "tone": "engaging"
}

Parameters

Example responses

200 Response

{
  "message": "string"
}

Responses

Personalization fallback usage for one automation

GET /personalization/automations/{automation_id}/fallback-stats

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.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "messages_sent": 0,
  "fallback_used": 0,
  "fallback_rate": 0
}

Responses

Personalized messages a creator was actually sent

GET /personalization/creators/{creator_id}/sent-messages

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.

Parameters

Example responses

200 Response

{
  "creator_id": "string",
  "count": 0,
  "messages": [
    {
      "automation_id": 0,
      "message": "string",
      "is_fallback": true,
      "tone": "string",
      "sent_at": "string"
    }
  ]
}

Responses

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

POST /target-collabs

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.

Body parameter

{
  "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": {
    "email": "string",
    "phone": "string"
  }
}

Parameters

Example responses

201 Response

{
  "automation_id": 0,
  "status": "string",
  "creator_id": "string",
  "creator_handle": "string",
  "shop_id": 0,
  "check_status_at": "string",
  "queued_at": "string",
  "dry_run": false
}

Responses

Get the shop's default Target Collab support contact

GET /target-collabs/support-contact-default

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).

Example responses

200 Response

{
  "shop_id": 0,
  "configured": true,
  "email": "string",
  "phone": "string",
  "updated_at": "string"
}

Responses

Set the shop's default Target Collab support contact

PUT /target-collabs/support-contact-default

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.

Body parameter

{
  "email": "string",
  "phone": "string"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "configured": true,
  "email": "string",
  "phone": "string",
  "updated_at": "string"
}

Responses

Metrics

Time-series metrics for dashboards and charts.

Time-series metrics

POST /metrics/timeseries

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).

Body parameter

{
  "metrics": [
    "gmv"
  ],
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "granularity": "day"
}

Parameters

Example responses

200 Response

{
  "data": {
    "property1": [
      {
        "date": "string",
        "value": 0
      }
    ],
    "property2": [
      {
        "date": "string",
        "value": 0
      }
    ]
  },
  "granularity": "string",
  "start_date": "string",
  "end_date": "string",
  "currency": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

Dashboard headline metrics

POST /metrics/summary

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).

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "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": [
    "string"
  ],
  "start_date": "string",
  "end_date": "string",
  "currency": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

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)

POST /shop-gmv/timeseries

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.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "currency_code": "string",
  "granularity": "daily",
  "start_date": "string",
  "end_date": "string",
  "series": [
    {
      "date": "string",
      "gmv": 0,
      "orders": 0,
      "items_sold": 0,
      "customers": 0,
      "aov": 0,
      "channels": {
        "video": {
          "gmv": 0,
          "affiliate": 0,
          "seller": 0
        },
        "live": {
          "gmv": 0,
          "affiliate": 0,
          "seller": 0
        },
        "product_card": {
          "gmv": 0,
          "shop_tab": 0,
          "search": 0
        }
      },
      "traffic": {
        "product_impressions": 0,
        "product_clicks": 0
      }
    }
  ]
}

Responses

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

POST /shop-gmv/summary

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.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "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": {
    "video": {
      "gmv": 0,
      "affiliate": 0,
      "seller": 0
    },
    "live": {
      "gmv": 0,
      "affiliate": 0,
      "seller": 0
    },
    "product_card": {
      "gmv": 0,
      "shop_tab": 0,
      "search": 0
    }
  },
  "traffic": {
    "product_impressions": 0,
    "product_clicks": 0
  }
}

Responses

Analytics

Affiliate funnel and creator level distributions.

Affiliate funnel overview

GET /funnel

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.

Example responses

200 Response

null

Responses

Response Schema

GMV Max

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

List GMV Max campaigns

GET /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).

Example responses

200 Response

{
  "data": [
    {
      "shop_id": 0,
      "campaign_id": "string",
      "campaign_name": "string",
      "status": "string",
      "shopping_ads_type": "string",
      "budget": 0,
      "roas_bid": 0,
      "last_synced_at": "string",
      "currency": "string"
    }
  ],
  "shops_queried": [
    "string"
  ]
}

Responses

Daily GMV Max campaign metrics

GET /gmv-max/campaigns/{campaign_id}/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.

Parameters

Example responses

200 Response

{
  "campaign_id": "string",
  "shop_id": 0,
  "data": [
    {
      "date": "string",
      "spend": 0,
      "impressions": 0,
      "clicks": 0,
      "orders": 0,
      "gross_revenue": 0,
      "cpc": 0,
      "cpm": 0,
      "ctr": 0,
      "roas": 0
    }
  ],
  "start_date": "string",
  "end_date": "string",
  "currency": "string"
}

Responses

GMV Max dashboard KPIs

GET /gmv-max/dashboard

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max campaign detail

GET /gmv-max/campaigns/{campaign_id}

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max creatives for a campaign

GET /gmv-max/creatives

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

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max spark code sync state

GET /gmv-max/spark-codes

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.

Example responses

200 Response

null

Responses

Response Schema

GMV Max automation quick-start templates

GET /gmv-max/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.

Example responses

200 Response

null

Responses

Response Schema

List GMV Max automations

GET /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.

Example responses

200 Response

null

Responses

Response Schema

Create a GMV Max automation

POST /gmv-max/automations

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.

Body parameter

{
  "name": "string",
  "template_type": "string",
  "trigger_frequency": "daily",
  "campaign_ids": [
    "string"
  ],
  "conditions": [
    {
      "metric": "creative_roi",
      "operator": "lt",
      "value": 0,
      "lookback_days": 3
    }
  ],
  "actions": [
    {
      "action_type": "set_up_creative_boost",
      "params": {}
    }
  ],
  "guardrails": [
    {
      "rule_type": "total_creative_boost_cost",
      "operator": "lt",
      "value": 0
    }
  ],
  "boost_start_date": "2019-08-24",
  "boost_end_date": "2019-08-24"
}

Parameters

Example responses

201 Response

null

Responses

Response Schema

GMV Max automation detail

GET /gmv-max/automations/{automation_id}

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

Parameters

Example responses

200 Response

null

Responses

Response Schema

Update a GMV Max automation

PUT /gmv-max/automations/{automation_id}

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.

Body parameter

{
  "name": "string",
  "trigger_frequency": "daily",
  "campaign_ids": [
    "string"
  ],
  "conditions": [
    {
      "metric": "creative_roi",
      "operator": "lt",
      "value": 0,
      "lookback_days": 3
    }
  ],
  "actions": [
    {
      "action_type": "set_up_creative_boost",
      "params": {}
    }
  ],
  "guardrails": [
    {
      "rule_type": "total_creative_boost_cost",
      "operator": "lt",
      "value": 0
    }
  ],
  "boost_start_date": "2019-08-24",
  "boost_end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

null

Responses

Response Schema

Delete (soft) a GMV Max automation

DELETE /gmv-max/automations/{automation_id}

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max automation run history

GET /gmv-max/automations/{automation_id}/runs

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max automation activity log

GET /gmv-max/automations/{automation_id}/activities

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Stop a GMV Max automation

POST /gmv-max/automations/{automation_id}/stop

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Sync specific spark codes to TikTok

POST /gmv-max/spark-codes/sync

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.

Body parameter

{
  "spark_codes": [
    "string"
  ]
}

Parameters

Example responses

200 Response

null

Responses

Response Schema

Queue every unsynced spark code for sync

POST /gmv-max/spark-codes/sync-all

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.

Body parameter

{}

Parameters

Example responses

200 Response

null

Responses

Response Schema

AI Search

Natural-language creator search backed by the same retrieval pipeline as the portal. Search and CSV export are both available, with a 50,000-row hard cap per export.

Search creators with natural language

POST /ai-search/creators

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.

Body parameter

{
  "query": "string",
  "page": 1,
  "page_size": 20
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_name": "string",
      "categories": [
        "string"
      ],
      "follower_count": 0,
      "gmv": 0,
      "post_rate": 0,
      "engagement_rate": 0,
      "bio": "string",
      "top_videos": [
        {
          "video_id": "string",
          "tiktok_url": "string",
          "views": 0
        }
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "page": 0,
    "page_size": 0
  }
}

Responses

Export creator search results as CSV

POST /ai-search/export

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.

Body parameter

{
  "query": "string",
  "creator_ids": [
    "string"
  ]
}

Parameters

Example responses

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

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

GET /creator-messages/conversations

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

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "last_message_text": "string",
      "last_message_time": "string",
      "last_message_sender": "string",
      "unread_count": 0
    }
  ],
  "offset": 0,
  "limit": 0,
  "has_more": true,
  "total_count": 0
}

Responses

Get the message thread with a creator

GET /creator-messages/conversations/{creator_handle}/messages

Parameters

Example responses

200 Response

{
  "creator_handle": "string",
  "data": [
    {
      "id": 0,
      "sender": "string",
      "content_type": "string",
      "text": "string",
      "sent_at": "string",
      "image": {
        "url": "string",
        "width": 0,
        "height": 0
      },
      "product_card": {
        "product_id": "string",
        "product_name": "string",
        "image_url": "string"
      },
      "target_collaboration_card": {
        "invitation_group_id": "string"
      },
      "free_sample_card": {
        "apply_id": "string"
      },
      "crm_text_with_image_card": {
        "title": "string",
        "content": "string",
        "url": "string"
      },
      "crm_text_with_products_card": {
        "title": "string",
        "content": "string",
        "products": [
          {
            "product_id": "string",
            "product_name": "string",
            "image_url": "string"
          }
        ]
      }
    }
  ],
  "page": 0,
  "has_more": true
}

Responses

Send a text reply to a creator

POST /creator-messages/conversations/{creator_handle}/reply

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.

Body parameter

{
  "message": "string"
}

Parameters

Example responses

200 Response

{
  "dry_run": true,
  "would_send_to": "string",
  "message": "string"
}

Responses

Send an image reply to a creator

POST /creator-messages/conversations/{creator_handle}/reply/image

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).

Body parameter

{
  "image_url": "stringstri"
}

Parameters

Example responses

200 Response

{
  "dry_run": true,
  "would_send_to": "string",
  "image_url": "string"
}

Responses

Send a product-card reply to a creator

POST /creator-messages/conversations/{creator_handle}/reply/product

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).

Body parameter

{
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "dry_run": true,
  "would_send_to": "string",
  "product_id": "string"
}

Responses

Stage a draft reply on a creator conversation

POST /creator-messages/draft

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.

Body parameter

{
  "creator_handle": "string",
  "text": "string",
  "image_url": "stringstri",
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "dry_run": true,
  "would_create_for_handle": "string",
  "content_type": "string",
  "text": "string",
  "image_url": "string",
  "product_id": "string"
}

Responses

List staged drafts on a conversation

GET /creator-messages/conversations/{creator_handle}/drafts

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

Parameters

Example responses

200 Response

{
  "data": [
    {
      "id": 0,
      "conversation_id": 0,
      "content_type": "string",
      "text_content": "string",
      "payload": {},
      "created_at": "string",
      "expires_at": "string",
      "created_by_api_key_id": 0
    }
  ],
  "page": 0,
  "page_size": 0,
  "total": 0,
  "has_more": true
}

Responses

Discard a staged draft

DELETE /creator-messages/drafts/{draft_id}

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).

Parameters

Example responses

422 Response

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Responses

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

GET /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).

Parameters

Example responses

200 Response

null

Responses

Response Schema

Create a campaign

POST /campaigns

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.

Body parameter

{
  "campaign_name": "string",
  "campaign_type": "retainer",
  "creator_source": "my_community",
  "start_date": "string",
  "end_date": "string",
  "description": "string",
  "status": "published",
  "pricing": {
    "campaign_type": "retainer",
    "posts": 1,
    "payment_per_creator": 0,
    "reward_type": "cash",
    "metric_type": "gmv",
    "minimum_gmv_required": 0,
    "minimum_gmv_required_enabled": false,
    "minimum_views_required": 0,
    "minimum_views_required_enabled": false,
    "minimum_videos_required": 0
  },
  "products": {
    "all_selected": false,
    "items": [
      {
        "product_id": "string",
        "tap_link": "string",
        "product_name": "string"
      }
    ],
    "use_first_product_image": true,
    "custom_image": "string",
    "campaign_image": "string"
  },
  "creators": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "window_url": "string",
  "is_available_to_all": false,
  "requires_approval": false,
  "creator_level": [
    "string"
  ],
  "support_email": "string",
  "short_header_message": "string",
  "content_guidelines": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "inspiration_links": [
    "string"
  ],
  "has_tiered_payout": false,
  "payout_structure": {},
  "grace_period": 365,
  "reminders": {
    "enabled": false,
    "message_before_3_days": "string",
    "message_before_1_day": "string"
  },
  "email_templates": {
    "enabled": true,
    "application": {},
    "acceptance": {},
    "rejection": {}
  }
}

Parameters

Example responses

201 Response

{
  "campaign_id": 0,
  "uuid_id": "string",
  "status": "created",
  "invite_link": "string"
}

Responses

List managed creators across all campaigns

GET /campaigns/creators

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

List shop-wide creator content

GET /campaigns/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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Get marketplace wallet balance

GET /campaigns/payments/wallet-balance

Example responses

200 Response

null

Responses

Response Schema

Payment / settlement history

GET /campaigns/payments/history

Parameters

Example responses

200 Response

null

Responses

Response Schema

Wallet deposit history

GET /campaigns/payments/deposits

Parameters

Example responses

200 Response

null

Responses

Response Schema

Get one campaign (edit-view shape)

GET /campaigns/{campaign_id}

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

Parameters

Example responses

200 Response

null

Responses

Response Schema

Update an existing campaign

PATCH /campaigns/{campaign_id}

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

Body parameter

{
  "campaign_name": "string",
  "start_date": "string",
  "end_date": "string",
  "description": "string",
  "status": "published",
  "pricing": {
    "campaign_type": "retainer",
    "posts": 1,
    "payment_per_creator": 0,
    "reward_type": "cash",
    "metric_type": "gmv",
    "minimum_gmv_required": 0,
    "minimum_gmv_required_enabled": false,
    "minimum_views_required": 0,
    "minimum_views_required_enabled": false,
    "minimum_videos_required": 0
  },
  "products": {
    "all_selected": false,
    "items": [
      {
        "product_id": "string",
        "tap_link": "string",
        "product_name": "string"
      }
    ],
    "use_first_product_image": true,
    "custom_image": "string",
    "campaign_image": "string"
  },
  "creators": [
    {
      "property1": "string",
      "property2": "string"
    }
  ],
  "window_url": "string",
  "is_available_to_all": true,
  "requires_approval": true,
  "creator_level": [
    "string"
  ],
  "support_email": "string",
  "short_header_message": "string",
  "content_guidelines": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "inspiration_links": [
    "string"
  ],
  "has_tiered_payout": true,
  "payout_structure": {},
  "grace_period": 365,
  "reminders": {
    "enabled": false,
    "message_before_3_days": "string",
    "message_before_1_day": "string"
  },
  "email_templates": {
    "enabled": true,
    "application": {},
    "acceptance": {},
    "rejection": {}
  }
}

Parameters

Example responses

200 Response

{
  "campaign_id": 0,
  "status": "updated"
}

Responses

Soft-delete a campaign

DELETE /campaigns/{campaign_id}

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

Parameters

Example responses

200 Response

{
  "campaign_id": 0,
  "status": "deleted"
}

Responses

Get the full campaign detail view

GET /campaigns/{campaign_id}/detail

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.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Accept a creator into a campaign

POST /campaigns/{campaign_id}/creators/{creator_id}/accept

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.

Body parameter

{
  "message": "string"
}

Parameters

Example responses

200 Response

{
  "success": true,
  "code": "ok",
  "data": {}
}

Responses

Reject a creator from a campaign

POST /campaigns/{campaign_id}/creators/{creator_id}/reject

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

Body parameter

{
  "message": "string"
}

Parameters

Example responses

200 Response

{
  "success": true,
  "code": "ok",
  "data": {}
}

Responses

Reactivate a previously-rejected creator

POST /campaigns/{campaign_id}/creators/{creator_id}/reactivate

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

Parameters

Example responses

200 Response

{
  "success": true,
  "code": "ok",
  "data": {}
}

Responses

Remove a creator from a campaign

POST /campaigns/creators/{creator_id}/remove

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.

Body parameter

{
  "campaign_id": 0,
  "message": "string"
}

Parameters

Example responses

200 Response

{
  "success": true,
  "code": "ok",
  "data": {}
}

Responses

Add a creator to another campaign (move)

POST /campaigns/creators/{creator_id}/add-to-campaign

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.

Body parameter

{
  "target_campaign_id": 0,
  "target_shop_id": 0,
  "notify": true
}

Parameters

Example responses

200 Response

{
  "success": true,
  "code": "ok",
  "data": {}
}

Responses

Get a single video's full detail by id

POST /campaigns/content/view

Body parameter

{
  "video_id": "string"
}

Parameters

Example responses

200 Response

{
  "status": "success",
  "data": [
    {}
  ],
  "count": 0
}

Responses

List a creator-campaign mapping's posted videos

POST /campaigns/content/tracker-vids

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

Body parameter

{
  "campaign_creator_mapping_id": 0
}

Parameters

Example responses

200 Response

{
  "status": "success",
  "data": [
    {}
  ],
  "count": 0
}

Responses

Archive a creator's content tracker

POST /campaigns/content/archive

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

Body parameter

{
  "campaign_creator_mapping_id": 0
}

Parameters

Example responses

200 Response

{
  "status": "string",
  "message": "string"
}

Responses

Request more content from a creator

POST /campaigns/content/request-more

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.

Body parameter

{
  "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"
}

Parameters

Example responses

200 Response

{
  "status": "success"
}

Responses

Create a Stripe Checkout session to top up the marketplace wallet

POST /campaigns/payments/deposit-intent

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.

Body parameter

{
  "amount": 100000,
  "currency": "USD",
  "success_url": "string",
  "cancel_url": "string"
}

Parameters

Example responses

201 Response

{
  "session_id": "string",
  "redirect_url": "string"
}

Responses

Settle a creator payment

POST /campaigns/payments/settle

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.

Body parameter

{
  "creator_id": 0,
  "campaign_id": 0,
  "amount": 100000,
  "currency": "str",
  "reward_type": "string",
  "campaign_creator_mapping_id": 0,
  "metadata": {}
}

Parameters

Example responses

201 Response

{
  "success": true,
  "transfer_id": "string",
  "amount": 0,
  "currency": "string",
  "paid_at": "string",
  "wallet_balance": 0
}

Responses

Archive a campaign

POST /campaigns/{campaign_id}/archive

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

Parameters

Example responses

200 Response

{
  "campaign_id": 0,
  "status": "archived"
}

Responses

Lists

Create a list

POST /lists

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.

Body parameter

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

name: string
description: string
creator_handles:
  - string
creator_emails:
  - string

Parameters

Example responses

201 Response

{
  "data": {
    "list_id": "string",
    "name": "string",
    "description": "string",
    "creator_count": 0,
    "email_count": 0,
    "state": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

Responses

List the shop's lists

GET /lists

Parameters

Example responses

200 Response

{
  "data": [
    {
      "list_id": "string",
      "name": "string",
      "description": "string",
      "creator_count": 0,
      "email_count": 0,
      "state": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "pagination": null
}

Responses

Get a list with its members

GET /lists/{list_id}

Parameters

Example responses

200 Response

{
  "data": {
    "list_id": "string",
    "name": "string",
    "description": "string",
    "creator_count": 0,
    "email_count": 0,
    "state": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "creator_handles": [
    "string"
  ],
  "creator_emails": [
    "string"
  ]
}

Responses

Delete a list (soft)

DELETE /lists/{list_id}

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

Parameters

Example responses

200 Response

null

Responses

Response Schema

CRM Groups

List CRM Groups

GET /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.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "crm_group_id": "string",
      "name": "string",
      "description": "string",
      "conditions": [
        {
          "field": "string",
          "operator": "string",
          "value": null,
          "value_count": 0
        }
      ],
      "creator_count": 0,
      "last_synced_at": "string"
    }
  ],
  "pagination": null
}

Responses

Create a CRM Group from a dashboard segment

POST /crm-groups/from-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.

Body parameter

{
  "group_name": "string",
  "tier": "string",
  "automation_id": 1,
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "group_tags": [
    "string"
  ]
}

Parameters

Example responses

200 Response

{
  "data": {
    "crm_group_id": "string",
    "name": "string",
    "creator_count": 0,
    "handles_resolved": 0,
    "group_tags": [
      "string"
    ]
  },
  "dry_run": true
}

Responses

Get a CRM Group's filter conditions + member count

GET /crm-groups/{crm_group_id}

Parameters

Example responses

200 Response

{
  "data": {
    "crm_group_id": "string",
    "name": "string",
    "description": "string",
    "conditions": [
      {
        "field": "string",
        "operator": "string",
        "value": null,
        "value_count": 0
      }
    ],
    "creator_count": 0,
    "last_synced_at": "string"
  }
}

Responses

Schemas

AISearchCreator

{
  "creator_name": "string",
  "categories": [
    "string"
  ],
  "follower_count": 0,
  "gmv": 0,
  "post_rate": 0,
  "engagement_rate": 0,
  "bio": "string",
  "top_videos": [
    {
      "video_id": "string",
      "tiktok_url": "string",
      "views": 0
    }
  ]
}

AISearchCreator

Properties

anyOf

or

continued

anyOf

or

continued

anyOf

or

continued

anyOf

or

continued

anyOf

or

continued

anyOf

or

continued

anyOf

or

continued

AISearchCreatorsRequest

{
  "query": "string",
  "page": 1,
  "page_size": 20
}

AISearchCreatorsRequest

Properties

anyOf

or

continued

AISearchCreatorsResponse

{
  "data": [
    {
      "creator_name": "string",
      "categories": [
        "string"
      ],
      "follower_count": 0,
      "gmv": 0,
      "post_rate": 0,
      "engagement_rate": 0,
      "bio": "string",
      "top_videos": [
        {
          "video_id": "string",
          "tiktok_url": "string",
          "views": 0
        }
      ]
    }
  ],
  "pagination": {
    "total": 0,
    "page": 0,
    "page_size": 0
  }
}

AISearchCreatorsResponse

Properties

AISearchExportRequest

{
  "query": "string",
  "creator_ids": [
    "string"
  ]
}

AISearchExportRequest

Properties