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:
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ShopsListResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CreatorsListRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorsListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CreatorPerformanceRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorPerformanceResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CreatorsSummaryRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorsSummaryResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | CreatorTrendsRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorTrendsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| start_date | query | any | false | Start date (YYYY-MM-DD). Defaults to 30 days ago. |
| end_date | query | any | false | End date (YYYY-MM-DD). Defaults to the shop's newest settled day. |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorDetailResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| body | body | CreatorVideosRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideosListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| body | body | CreatorProductsRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorProductsPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | ProductsListRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ProductsListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
List product's creators
POST /products/{product_id}/creators
Creators affiliated with this product.
Body parameter
{
"page": 1,
"page_size": 50
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| product_id | path | string | true | none |
| body | body | ProductCreatorsRequest | true | none |
Example responses
200 Response
{
"data": [
{
"creator_handle": "string",
"follower_count": 0,
"commission_rate": 0,
"gmv": 0
}
],
"currency": "string",
"pagination": null,
"shops_queried": [
"string"
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ProductCreatorsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| product_id | path | string | true | none |
| body | body | ProductVideosRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideosListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | VideosListRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideosListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | VideosCreativeRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideosCreativeResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | VideoPerformanceRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideoPerformanceResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | SamplesListRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | SamplesListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | SamplesByProductRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | SamplesByProductPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | AutomationsListRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationsListPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| shop_region | query | string | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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_usedcounts actual sends only (skipped/creator_not_foundinvites do not count). The daily ceiling is plan/TikTok-dependent and is not returned as a single number;daily_limit_throttledflags 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_throttledflags 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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | OutreachCapacityResponse |
Get automation detail
GET /automations/{automation_id}
Detailed automation data with performance metrics.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationDetailResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | AutomationUpdateRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| page | query | integer | false | none |
| page_size | query | integer | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationCreatorsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationMessagesTemplateResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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 withcreator_handle; page depth withcreator_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: falseandcoverage_notestate this explicitly. When the automation is a campaign's TC automation,campaigncarries 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| creator_limit | query | integer | false | none |
| messages_per_creator | query | integer | false | none |
| creator_handle | query | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationSentMessagesResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| X-Created-Via | header | any | false | none |
| body | body | AutomationTargetCollabRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| X-Created-Via | header | any | false | none |
| body | body | AutomationTcCleanupRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| X-Created-Via | header | any | false | none |
| body | body | AutomationDmRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| X-Created-Via | header | any | false | none |
| body | body | AutomationEmailRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| X-Created-Via | header | any | false | none |
| body | body | AutomationSampleRequestRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Automation cannot run as configured — no schedule day with maxCreators > 0, or valid_until/end_date already passed (AUTOMATION_NOT_STARTABLE). |
WriteErrorResponse |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
Stop automation
POST /automations/{automation_id}/stop
Transition automation to stopped. Idempotent.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AutomationWriteResponseV2 |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or forbidden update field. | WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | Automation/list/group not in this shop. | WriteErrorResponse |
| 409 | Conflict | Idempotency conflict, archived row, or email-account already linked. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit (10/min, 50/hr, 100/day) exceeded. | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | PersonalizationPreviewRequest | true | none |
Example responses
200 Response
{
"creator_id": "string",
"message": "string",
"is_fallback": true,
"blocks_used": [
"string"
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | PersonalizationPreviewResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | PersonalizationProductBlocksRequest | true | none |
Example responses
200 Response
{
"product_description": "",
"product_selling_points": ""
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | PersonalizationProductBlocksResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | PersonalizationRetoneRequest | true | none |
Example responses
200 Response
{
"message": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | PersonalizationRetoneResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
Example responses
200 Response
{
"automation_id": 0,
"messages_sent": 0,
"fallback_used": 0,
"fallback_rate": 0
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | PersonalizationFallbackStatsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_id | path | string | true | none |
| limit | query | integer | false | none |
Example responses
200 Response
{
"creator_id": "string",
"count": 0,
"messages": [
{
"automation_id": 0,
"message": "string",
"is_fallback": true,
"tone": "string",
"sent_at": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | PersonalizationCreatorSentMessagesResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | TargetCollabDirectRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | TargetCollabDirectResponse |
| 400 | Bad Request | Validation, missing/invalid Idempotency-Key, or multi-shop scope (x-shop-id=all). |
WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 404 | Not Found | creator_handle could not be resolved in this shop's region (CREATOR_NOT_FOUND). |
WriteErrorResponse |
| 409 | Conflict | Idempotency conflict — same key, different body. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit exceeded. | WriteErrorResponse |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ShopSupportContactDefaultResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| body | body | ShopSupportContactDefaultRequest | true | none |
Example responses
200 Response
{
"shop_id": 0,
"configured": true,
"email": "string",
"phone": "string",
"updated_at": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ShopSupportContactDefaultResponse |
| 400 | Bad Request | Multi-shop scope (x-shop-id=all or CSV) — requires a single shop. |
WriteErrorResponse |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
WriteErrorResponse |
| 409 | Conflict | Idempotency conflict — same key, different body. | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write-tier rate limit exceeded. | WriteErrorResponse |
| 503 | Service Unavailable | Storage not yet available (migration 053 not applied). | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | TimeseriesRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | TimeseriesResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | MetricsSummaryResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | ShopGmvTimeseriesRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ShopGmvTimeseriesResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ShopGmvSummaryResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | GmvMaxCampaignsResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | string | true | none |
| start_date | query | any | false | none |
| end_date | query | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | GmvMaxCampaignMetricsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| days | query | integer | false | Window size in days (default 7). |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | string | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | query | string | true | GMV Max campaign ID. |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | AutomationCreateRequestPublic | true | none |
Example responses
201 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run echo (no automation created). | None |
| 201 | Created | Automation created. | Inline |
| 400 | Bad Request | Invalid request. | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation error (cap missing, campaign conflict, etc.). | None |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | AutomationUpdateRequestPublic | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Automation updated (or dry-run echo). | Inline |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | Automation not found in this shop. | None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation error / automation not editable. | None |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Automation deleted (or already deleted). | Inline |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | Automation not found in this shop. | None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| status | query | any | false | Filter by activity status (matches portal). |
| search | query | any | false | Free-text search across activity rows. |
| page | query | integer | false | none |
| page_size | query | integer | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| automation_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Automation stopped (or already stopped). | Inline |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | Automation not found in this shop. | None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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_statusflips tosynced. - On TikTok QPS / rate-limit → code is left
pendingso the offline CRJ retries it; the response counts this inqueued. - On hard error →
failedwith 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | SparkCodeSyncRequestPublic | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Sync attempted; see results for per-code outcome. |
Inline |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Shop not connected to TikTok Business. | None |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | any | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Codes queued for async sync. | Inline |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Shop not connected to TikTok Business. | None |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | AISearchCreatorsRequest | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | AISearchCreatorsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | AISearchExportRequest | true | none |
Example responses
422 Response
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| offset | query | integer | false | none |
| limit | query | integer | false | none |
| unread_only | query | boolean | false | none |
| unreplied_only | query | boolean | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorConversationsResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Get the message thread with a creator
GET /creator-messages/conversations/{creator_handle}/messages
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| page | query | integer | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorMessagesResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CreatorReplyRequest | true | none |
Example responses
200 Response
{
"dry_run": true,
"would_send_to": "string",
"message": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run — validated and echoed, nothing sent. | CreatorReplyDryRunResponse |
| 201 | Created | Reply sent to the creator. | CreatorReplyResponse |
| 400 | Bad Request | Invalid request. | None |
| 403 | Forbidden | API key lacks read_write scope (WRITE_NOT_PERMITTED). |
None |
| 404 | Not Found | No existing conversation with this creator for the shop. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
| 502 | Bad Gateway | TikTok rejected or failed the send. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CreatorReplyImageRequest | true | none |
Example responses
200 Response
{
"dry_run": true,
"would_send_to": "string",
"image_url": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run — validated and echoed, nothing fetched or sent. | CreatorReplyImageDryRunResponse |
| 201 | Created | Image uploaded to TikTok and reply sent to the creator. | CreatorReplyImageResponse |
| 400 | Bad Request | Invalid image_url (scheme, IP, content-type, or size). | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | No existing conversation with this creator. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
| 502 | Bad Gateway | Image fetch failed, or TikTok rejected the send. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CreatorReplyProductRequest | true | none |
Example responses
200 Response
{
"dry_run": true,
"would_send_to": "string",
"product_id": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run — validated and echoed, nothing sent. | CreatorReplyProductDryRunResponse |
| 201 | Created | Product card sent to the creator. | CreatorReplyProductResponse |
| 400 | Bad Request | Invalid request, or product_id not in this shop's catalog. | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | No existing conversation with this creator. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
| 502 | Bad Gateway | TikTok rejected or failed the send. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CreateDraftRequest | true | none |
Example responses
200 Response
{
"dry_run": true,
"would_create_for_handle": "string",
"content_type": "string",
"text": "string",
"image_url": "string",
"product_id": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run — validated and echoed, nothing persisted. | CreateDraftDryRunResponse |
| 201 | Created | Draft staged on the conversation. | CreateDraftResponse |
| 400 | Bad Request | Invalid body (multiple content fields set, none set, etc.). | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | No existing conversation with this creator for the shop. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_handle | path | string | true | none |
| page | query | integer | false | none |
| page_size | query | integer | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | DraftListResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| draft_id | path | integer | true | none |
| X-Dry-Run | header | any | false | none |
Example responses
422 Response
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run — validated and echoed, nothing deleted. | None |
| 204 | No Content | Draft removed. | None |
| 403 | Forbidden | API key lacks read_write scope, or draft belongs to a different shop. |
None |
| 404 | Not Found | Draft not found. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| status | query | any | false | UI alias: 'active' (= published), 'past' (= ended), 'draft' (= unpublished drafts), or 'archived'. |
| campaign_type | query | any | false | Filter: retainer |
| search | query | any | false | none |
| date_from | query | any | false | YYYY-MM-DD; start_date >= date_from |
| date_to | query | any | false | YYYY-MM-DD; end_date <= date_to |
| sort_by | query | any | false | campaign_name |
| sort_order | query | string | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CampaignCreateRequest | true | none |
Example responses
201 Response
{
"campaign_id": 0,
"uuid_id": "string",
"status": "created",
"invite_link": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run echo (no campaign created). | None |
| 201 | Created | Successful Response | CampaignCreatedResponse |
| 400 | Bad Request | Invalid request. | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 409 | Conflict | Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| search | query | any | false | none |
| sort_by | query | any | false | none |
| sort_order | query | string | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| search | query | any | false | none |
| sort_by | query | any | false | none |
| sort_order | query | string | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Response Schema
Get marketplace wallet balance
GET /campaigns/payments/wallet-balance
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
Response Schema
Payment / settlement history
GET /campaigns/payments/history
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| search | query | any | false | none |
| sort_by | query | any | false | none |
| sort_order | query | string | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Response Schema
Wallet deposit history
GET /campaigns/payments/deposits
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| sort_by | query | any | false | none |
| sort_order | query | string | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Response Schema
Get one campaign (edit-view shape)
GET /campaigns/{campaign_id}
Returns the campaign in the same shape PATCH /campaigns/{id} accepts.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CampaignUpdateRequest | true | none |
Example responses
200 Response
{
"campaign_id": 0,
"status": "updated"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CampaignUpdatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
{
"campaign_id": 0,
"status": "deleted"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CampaignDeletedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| creator_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | any | false | none |
Example responses
200 Response
{
"success": true,
"code": "ok",
"data": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorStateChangeResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| creator_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | any | false | none |
Example responses
200 Response
{
"success": true,
"code": "ok",
"data": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorStateChangeResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| creator_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
{
"success": true,
"code": "ok",
"data": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CreatorStateChangeResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | any | false | none |
Example responses
200 Response
{
"success": true,
"code": "ok",
"data": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Removed (or idempotent already-removed). | RemoveCreatorResponse |
| 400 | Bad Request | Invalid request / missing single shop. | None |
| 403 | Forbidden | API key lacks read_write scope. |
None |
| 404 | Not Found | Mapping/campaign not in this shop, or shop not owned by the key's customer. | None |
| 409 | Conflict | Paid/completed creator (ledger preserved), or Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
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_lockguards it; apaid_atrow 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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| creator_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | AddToCampaignRequest | true | none |
Example responses
200 Response
{
"success": true,
"code": "ok",
"data": {}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Added or upgraded to active. | AddToCampaignResponse |
| 400 | Bad Request | Invalid request / missing single shop / target campaign not available. | None |
| 403 | Forbidden | API key lacks read_write scope, or creator not on the source shop's roster. |
None |
| 404 | Not Found | Target shop/campaign not found, or not owned by the key's customer. | None |
| 409 | Conflict | Region mismatch, already-active in target, or Idempotency-Key conflict. | None |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Write rate limit exceeded. | None |
Get a single video's full detail by id
POST /campaigns/content/view
Body parameter
{
"video_id": "string"
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | ViewVideoContentRequest | true | none |
Example responses
200 Response
{
"status": "success",
"data": [
{}
],
"count": 0
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | VideoContentResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| body | body | TrackerVideosRequest | true | none |
Example responses
200 Response
{
"status": "success",
"data": [
{}
],
"count": 0
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | TrackerVideosResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | ArchiveTrackerRequest | true | none |
Example responses
200 Response
{
"status": "string",
"message": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ArchiveTrackerResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | RequestMoreContentRequest | true | none |
Example responses
200 Response
{
"status": "success"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | RequestMoreContentResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CreateDepositIntentRequest | true | none |
Example responses
201 Response
{
"session_id": "string",
"redirect_url": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | DepositIntentResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | SettlePaymentRequest | true | none |
Example responses
201 Response
{
"success": true,
"transfer_id": "string",
"amount": 0,
"currency": "string",
"paid_at": "string",
"wallet_balance": 0
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | SettlementResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| campaign_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
{
"campaign_id": 0,
"status": "archived"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CampaignArchivedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | object | true | none |
| » name | body | string | true | Human-readable list name shown in the portal. |
| » description | body | any | false | none |
| »» anonymous | body | string | false | none |
| »» anonymous | body | null | false | none |
| » creator_handles | body | [string] | false | TikTok handles, with or without leading '@'. Deduplicated case-insensitively at insert time. |
| » creator_emails | body | [string] | false | Email addresses. Deduplicated case-insensitively at insert time. |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Successful Response | ListResponse |
| 400 | Bad Request | Bad Request | WriteErrorResponse |
| 403 | Forbidden | Forbidden | WriteErrorResponse |
| 404 | Not Found | Not Found | WriteErrorResponse |
| 409 | Conflict | Conflict | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Too Many Requests | WriteErrorResponse |
List the shop's lists
GET /lists
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| name_contains | query | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ListsPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Get a list with its members
GET /lists/{list_id}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| list_id | path | integer | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | ListMembersResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
Delete a list (soft)
DELETE /lists/{list_id}
Sets state=archived. Idempotent — already-archived returns 200.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| list_id | path | integer | true | none |
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
Example responses
200 Response
null
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | Inline |
| 400 | Bad Request | Bad Request | WriteErrorResponse |
| 403 | Forbidden | Forbidden | WriteErrorResponse |
| 404 | Not Found | Not Found | WriteErrorResponse |
| 409 | Conflict | Conflict | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Too Many Requests | WriteErrorResponse |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| page | query | integer | false | none |
| page_size | query | integer | false | none |
| name_contains | query | any | false | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CrmGroupsPaginatedResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| Idempotency-Key | header | any | false | none |
| X-Dry-Run | header | any | false | none |
| body | body | CrmGroupFromSegmentRequest | true | none |
Example responses
200 Response
{
"data": {
"crm_group_id": "string",
"name": "string",
"creator_count": 0,
"handles_resolved": 0,
"group_tags": [
"string"
]
},
"dry_run": true
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Dry-run result (X-Dry-Run: true). Nothing was written. | CrmGroupFromSegmentResponse |
| 201 | Created | Successful Response | CrmGroupFromSegmentResponse |
| 400 | Bad Request | Bad Request | WriteErrorResponse |
| 403 | Forbidden | Forbidden | WriteErrorResponse |
| 404 | Not Found | Not Found | WriteErrorResponse |
| 409 | Conflict | Conflict | WriteErrorResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
| 429 | Too Many Requests | Too Many Requests | WriteErrorResponse |
| 500 | Internal Server Error | Internal Server Error | WriteErrorResponse |
Get a CRM Group's filter conditions + member count
GET /crm-groups/{crm_group_id}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| crm_group_id | path | string | true | none |
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
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Successful Response | CrmGroupResponse |
| 422 | Unprocessable Entity | Validation Error | HTTPValidationError |
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
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_name | any | false | none | Creator's TikTok handle. Stable identifier for cross-referencing. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| categories | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Estimated overall GMV (USD-normalized). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| post_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| engagement_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| bio | any | false | none | Creator bio. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| top_videos | [AISearchVideo] | false | none | none |
AISearchCreatorsRequest
{
"query": "string",
"page": 1,
"page_size": 20
}
AISearchCreatorsRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| query | any | false | none | Natural-language search query. Whitespace-only is treated as no query (browse mode). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
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
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [AISearchCreator] | true | none | none |
| pagination | AISearchPagination | true | none | none |
AISearchExportRequest
{
"query": "string",
"creator_ids": [
"string"
]
}
AISearchExportRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| query | any | false | none | Natural-language search query. Omit (or pass whitespace-only) to export the full browse universe for your shop's region. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_ids | any | false | none | Explicit list of creator IDs to export. Mutually exclusive with query. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AISearchPagination
{
"total": 0,
"page": 0,
"page_size": 0
}
AISearchPagination
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| total | integer | true | none | none |
| page | integer | true | none | none |
| page_size | integer | true | none | none |
AISearchVideo
{
"video_id": "string",
"tiktok_url": "string",
"views": 0
}
AISearchVideo
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_id | string | true | none | none |
| tiktok_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AcceptCreatorRequest
{
"message": "string"
}
AcceptCreatorRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | any | false | none | Optional custom message included in the creator's acceptance email/SMS. If omitted, the campaign's default acceptance template is used. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ActionRulePublic
{
"action_type": "set_up_creative_boost",
"params": {}
}
ActionRulePublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| action_type | ActionType | true | none | What the action does. Currently only set_up_creative_boost is wired up to the execution engine. |
| params | object | false | none | Action-specific parameters. For set_up_creative_boost: {"maxCapPerDay": <float>} is the per-day spend cap (mirrors the portal Create-Automation form). |
ActionType
"set_up_creative_boost"
ActionType
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ActionType | string | false | none | Side effect the automation performs when its conditions fire. Only set_up_creative_boost is wired up to the offline executionengine today. The other portal-side enum values ( budget_adjust,material_status_update, etc.) are template-preview-only and willnot actually execute; they are intentionally not exposed here so callers don't silently create no-op automations. |
Enumerated Values
| Property | Value |
|---|---|
| ActionType | set_up_creative_boost |
AddToCampaignRequest
{
"target_campaign_id": 0,
"target_shop_id": 0,
"notify": true
}
AddToCampaignRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| target_campaign_id | integer | true | none | Campaign the creator is being added to (lives in target_shop_id). |
| target_shop_id | integer | true | none | Shop that owns the target campaign. Must belong to the same customer as your API key (else 404). |
| notify | boolean | false | none | Send the creator an acceptance-style notification on add. SKIPPED on X-Dry-Run. |
AddToCampaignResponse
{
"success": true,
"code": "ok",
"data": {}
}
AddToCampaignResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | false | none | none |
| code | string | false | none | none |
| data | object | false | none | {campaign_creator_mapping_id, campaign_id, status='active'}. |
ArchiveTrackerRequest
{
"campaign_creator_mapping_id": 0
}
ArchiveTrackerRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_creator_mapping_id | integer | true | none | none |
ArchiveTrackerResponse
{
"status": "string",
"message": "string"
}
ArchiveTrackerResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | true | none | none |
| message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationCreateRequestPublic
{
"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"
}
AutomationCreateRequestPublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | true | none | none |
| template_type | any | false | none | Optional reference to one of the /templates template_type values the automation was scaffolded from. Free-form — does not affect execution. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| trigger_frequency | TriggerFrequency | false | none | How often the automation evaluates. Only daily is wired up today. |
| campaign_ids | [string] | false | none | TikTok GMV Max campaign IDs the automation acts on. Each campaign_id can only be assigned to one active automation at a time — the controller rejects conflicts with a 422. |
| conditions | [ConditionRulePublic] | false | none | [One condition row in an automation's trigger logic.] |
| actions | [ActionRulePublic] | false | none | [One side-effect the automation performs when its conditions fire.] |
| guardrails | [GuardrailRulePublic] | false | none | [A safety cap that prevents the automation from spending past a limit.] |
| boost_start_date | any | false | none | First day boosts may fire. Must be paired with boost_end_date. Window cannot exceed 90 days. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| boost_end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationCreatorOutcome
{
"creator_handle": "string",
"outcome": "string",
"status": "string",
"detail": "string",
"skip_reason": "string",
"invitation_id": "string"
}
AutomationCreatorOutcome
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | string | true | none | TikTok handle as submitted. |
| outcome | string | true | none | Machine-stable outcome: invite_submitted (TC invite queued to the worker), outreach_sent (DM submitted), previously_invited (already invited for this product), invite_removed (invitation was withdrawn/edited), skipped (worker evaluated but did not send — see skip_reason), or unknown. |
| status | string | true | none | Human-readable status label, e.g. 'Outreach Sent'. |
| detail | string | true | none | Human-readable explanation of the outcome/status. |
| skip_reason | any | false | none | Machine skip-reason code, present only when outcome='skipped'. One of the CreatorSkipReason values: creator_not_found, creator_ineligible, five_message_limit_hit, previously_invited, previously_messaged, blocked_by_outreach_limit, performance_criteria_not_met, already_accepted_invite, conflicting_invitation, agency_sample_request_blocked, sample_request_expired, unknown. Branch on this rather than parsing detail. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| invitation_id | any | false | none | TikTok target_collaboration_id for this creator's Target Collab invite — the id used to reference or look up the collaboration. Populated only for creators invited via Target Collab (outcomes invite_submitted / previously_invited / invite_removed); null for DM outreach, skipped creators, and TC invites the worker has not submitted to TikTok yet (it is written asynchronously after the invite lands). This is an identifier, not a link: TikTok's TC-details API returns no shareable invite URL, so there is no ready-made link to hand to the creator. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationCreatorsResponse
{
"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
}
AutomationCreatorsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [AutomationCreatorOutcome] | true | none | [One creator's outcome under an automation, assembled from the Messages / target_collabs / skipped_creators tables the worker writes. IMPORTANT — queued vs 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 — it is not a confirmed "landed in the creator's TikTok inbox" event.] |
| summary | AutomationCreatorsSummary | true | none | Outcome counts across the FULL result set (not just the page). |
| pagination | any | true | none | none |
AutomationCreatorsSummary
{
"total": 0,
"invite_submitted": 0,
"outreach_sent": 0,
"previously_invited": 0,
"invite_removed": 0,
"skipped": 0,
"unknown": 0
}
AutomationCreatorsSummary
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| total | integer | false | none | none |
| invite_submitted | integer | false | none | none |
| outreach_sent | integer | false | none | none |
| previously_invited | integer | false | none | none |
| invite_removed | integer | false | none | none |
| skipped | integer | false | none | none |
| unknown | integer | false | none | none |
AutomationDetailResponse
{
"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"
}
AutomationDetailResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | AutomationListItem | true | none | none |
| creators_remaining | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency | string | true | none | none |
AutomationDmRequest
{
"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"
}
AutomationDmRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | string | true | none | none |
| mode | string | false | none | none |
| schedule | AutomationSchedule | true | none | Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema. |
| creators_to_include | CreatorsToInclude | false | none | Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A): * lists mode — list_upload and/or lists_selected populated* filters mode — filters populated (dynamic by attribute)* crm_group mode — crm_group_id populated (saved predicate)The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derivedfrom which mode is set — callers don't need to set it explicitly. |
| creators_to_exclude | CreatorsToExclude | false | none | Outreach-paradigm recipient exclusion. Mirrors creators_to_omit inthe legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel. |
| messages | [MessageAddon] | true | none | Initial-outreach addons — text + optional image / product card / spark_code form. ALL items are sent immediately together when the automation engages a creator. Use follow_ups for delayed steps. |
| follow_ups | [FollowUpStep] | false | none | Delayed follow-up steps — same shape as TC. |
| dm_config | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DmConfig | false | none | DM type-specific config blob, populated based on mode. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| personalization | any | false | none | CORE-4857: enable AI personalization of the initial-outreach DM. Omit to send the message exactly as written. When set, the send engine rewrites the DM per creator from the [Block] tokens in your message text and falls back to fallback_message for low-signal creators. See DmPersonalizationConfig. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DmPersonalizationConfig | false | none | CORE-4857 — enable AI personalization of the initial-outreach DM. When set on POST /automations/dm, the send engine rewrites the DM bodyper creator using the [Block] tokens in your message text: Content Discussion and Product Discussion are AI-generated from the creator's own signals, while Product Description / Selling Points / Offer are the fixed strings you provide here. A creator with too little signal to personalize receives fallback_message instead.All copy fields are stored verbatim — there is NO server-side AI at create time — so the create is deterministic and idempotent, and the send path's reuse hash stays stable. Resolve the product blocks beforehand via POST /personalization/product-blocks and preview any creator viaPOST /personalization/preview so what ships is what you approved. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ai_enabled | boolean | false | none | none |
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| is_evergreen | boolean | false | none | When true, the automation continuously re-evaluates its creators_to_include.filters for new qualifying creators on each run. No effect when creators_to_include.crm_group_id is set (CRM groups are inherently evergreen). Maps to top-level Automations.is_evergreen column. |
| business_hours_timezone | any | false | none | When set, the runtime restricts outbound message delivery (initial outreach + follow-ups) to 9am–9pm in this IANA timezone (e.g. America/Los_Angeles). Null disables the restriction. The 9–9 window is fixed; only the timezone is configurable. Distinct from schedule.timezone. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| mode | vanilla |
| mode | with_image |
| mode | with_product_card |
| mode | spark_code |
AutomationEmailRequest
{
"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"
}
]
}
AutomationEmailRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | string | true | none | none |
| email_account_id | integer | true | none | Pre-connected email account. Each account links to at most ONE active email automation per shop. |
| subject | string | true | none | none |
| body | string | true | none | HTML or plaintext. |
| selection_mode | string | true | none | none |
| mailing_list | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | EmailMailingList | false | none | selection_mode=mailing_list — recipients via uploaded emails or existing Lists (vault_files with non-empty creator_emails).NOTE: lists referenced by lists_selected MUST contain at least oneemail address — the vault_files.creator_emails JSONB column must benon-empty. Targeting requires emails to send to. The route validates this at create time and returns 400 LIST_MISSING_EMAILS for anylist that lacks emails. Per architecture review 2026-05-01. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| filters | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | EmailFilters | false | none | selection_mode=filters — recipients via creator search filters. Subset of the saved_searches.filters JSONB shape — fields that make sense for email outreach. Backend translates this into the legacy filters JSON. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_exclude | CreatorsToExclude | false | none | Outreach-paradigm recipient exclusion. Mirrors creators_to_omit inthe legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel. |
| attachments | [EmailAttachment] | false | none | Email attachments — [{name, url}] shape. URL must be a hosted HTTPS URL (no file uploads). Server fetches at create time and re-hosts internally. |
Enumerated Values
| Property | Value |
|---|---|
| selection_mode | mailing_list |
| selection_mode | filters |
AutomationListItem
{
"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"
}
AutomationListItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | integer | true | none | none |
| automation_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | Display status from map_automation_status() |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status_message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_requests | any | false | none | DB: automation_metrics.sample_request (singular) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| accepted_requests | any | false | none | DB: automation_metrics.accepted_request (singular) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_posted | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_converted | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_reached | any | false | none | Per-automation distinct creators reached by THIS automation. Lifetime when the request has no start_date/end_date; windowed when a date filter is supplied. For the shop-wide windowed total that matches the portal's Outreach Metrics dashboard, use the top-level aggregate.creators_reached field — it's a different number computed from the agency rollup table and won't equal the sum of these per-row values. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dm_response_count | any | false | none | DB: automation_metrics.dm_response_count — unique creators who replied to DMs (30-day rolling) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reply_rate | any | false | none | Computed: (dm_response_count / creators_reached) * 100. Populated for Running, Stopped, and Completed automations. Null when creators_reached is 0. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| skipped | any | false | none | Per-automation creators the worker evaluated but did NOT reach (handle unresolved, outreach-limit blocked, previously invited, below criteria, etc.). Sourced from the same stats view as creators_reached / total_creators: that view only retains rows for automations with recent activity, so all three read null (not 0) for automations idle for more than ~a day — null means 'no stats row', not 'zero skips'. For the always-available, per-creator breakdown of WHO was skipped and WHY, call GET /public/v1/automations/{automation_id}/creators. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| total_creators | any | false | none | Per-automation creators processed (reached + skipped) — NOT the audience size. 0 until sending begins; see creators_remaining for the resolved audience.Note: this is a per-row number scoped to ONE automation. Summing across rows will exceed the portal's shop-wide 'Total Creators' headline because the dashboard counts distinct creators-per-day across the whole shop, then sums days. For that headline number, read aggregate.tc_invites_creator_count on the top-level response. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_remaining | any | false | none | Resolved audience still to be processed. This is what confirms the audience resolved (e.g. your uploaded/CRM-group creators). Populated right after the automation is started. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| completed_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_via | any | false | none | Surface that created this automation. Always populated: rows with NULL/empty created_via (predating migration 020) surface as portal. Common values: portal |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationMessagesTemplateResponse
{
"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"
}
}
AutomationMessagesTemplateResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | integer | true | none | none |
| automation_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_invite_message | any | false | none | config.TARGET_COLLAB_MESSAGE — TC invite template (TC types only) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message_sequence | [any] | false | none | config.addons — ordered DM sequence; array order is send order |
| follow_up_steps | [any] | false | none | none |
| ai_custom_qa | [any] | false | none | none |
| personalization | any | false | none | CORE-4857 AI personalization config, when the automation has it (DM types only). Null otherwise. Configure via POST /automations/dm; use POST /personalization/* to preview. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | AutomationPersonalizationConfig | false | none | CORE-4857 — the AI-personalization config on a DM automation, read back. Projected from config.PERSONALIZATION (the block the send engine reads).Present only when personalization was configured — via the portal composer or via POST /automations/dm with a personalization object. nullon automations that don't use it. Product/offer strings are the fixed values the brand approved; the Content/Product-Discussion blocks are AI-generated per creator at send time and so aren't stored here. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationPersonalizationConfig
{
"enabled": false,
"tone": "string",
"fallback_message": "string",
"offer_discussion": "string",
"product_description": "string",
"product_selling_points": "string"
}
AutomationPersonalizationConfig
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| enabled | boolean | false | none | Whether the send engine personalizes this automation's DM. |
| tone | any | false | none | AI rewrite tone (engaging |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| fallback_message | any | false | none | Sent verbatim (name/product blocks filled) to creators with too little signal to personalize. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| offer_discussion | any | false | none | [Offer Discussion] block value. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_description | any | false | none | [Product Description] block value. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_selling_points | any | false | none | [Product Selling Points] block value. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationResourceV2
{
"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": {}
}
AutomationResourceV2
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | any | false | none | None on dry-run. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| automation_name | string | true | none | none |
| automation_type | string | true | none | One of: target_collab |
| automation_status | string | true | none | none |
| state | string | true | none | none |
| config | object | false | none | Full config as stored. Type-specific. |
| schedule | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_include | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_exclude | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ai_enabled | boolean | false | none | none |
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_via | any | false | none | Surface that created the automation. Always populated on response: rows with NULL or empty created_via (predating migration 020) are surfaced as portal since the portal was historically the only writer. Common values: portal |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| side_effects | any | false | none | Backend side-effects, e.g. {'crm_group_created': ' |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationSampleRequestRequest
{
"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
}
}
AutomationSampleRequestRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | string | true | none | none |
| sample_request | SampleRequestPayload | true | none | Inner sample_request config — mirrors the legacysample_request_config shape exactly (the worker reads from it). |
| schedule | any | false | none | Optional — sample_request can run continuously. If set, the automation only auto-approves/rejects during scheduled hours. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | AutomationSchedule | false | none | Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_exclude | CreatorsToExclude | false | none | Optional creator exclusion. Persists as config.excluded_creators (sibling of sample_request_config) using {excluded_lists_ids, excluded_crm_groups_ids, excluded_creator_ids} shape — matches reacher-web-react formDataTransformer.ts. |
AutomationSchedule
{
"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"
}
AutomationSchedule
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| Monday_maxCreators | integer | false | none | none |
| Tuesday_maxCreators | integer | false | none | none |
| Wednesday_maxCreators | integer | false | none | none |
| Thursday_maxCreators | integer | false | none | none |
| Friday_maxCreators | integer | false | none | none |
| Saturday_maxCreators | integer | false | none | none |
| Sunday_maxCreators | integer | false | none | none |
| start_time | any | false | none | HH:MM 24-hour, in timezone. Hours 00-23, minutes 00-59. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_time | any | false | none | HH:MM 24-hour, in timezone. Hours 00-23, minutes 00-59. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| timezone | any | false | none | IANA timezone name, e.g. America/Los_Angeles |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationSentMessagesResponse
{
"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"
}
AutomationSentMessagesResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | integer | true | none | none |
| automation_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| template | AutomationMessagesTemplateResponse | true | none | Message templates configured on one automation (CORE-5593). This is the configured copy — placeholders like {{creators username}}or {creator_name} are not substituted. For the exact per-creator textthat was actually sent, use GET /automations/{id}/sent-messages. |
| dm_sent | SentDmSection | true | none | none |
| tc_sent | SentTcSection | true | none | none |
| message | any | false | none | Explicit empty state when the automation has sent nothing at all |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationTargetCollabRequest
{
"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"
}
AutomationTargetCollabRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | string | true | none | none |
| schedule | AutomationSchedule | true | none | Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema. |
| creators_to_include | CreatorsToInclude | false | none | Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A): * lists mode — list_upload and/or lists_selected populated* filters mode — filters populated (dynamic by attribute)* crm_group mode — crm_group_id populated (saved predicate)The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derivedfrom which mode is set — callers don't need to set it explicitly. |
| creators_to_exclude | CreatorsToExclude | false | none | Outreach-paradigm recipient exclusion. Mirrors creators_to_omit inthe legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel. |
| target_collab | TargetCollabConfig | true | none | TC-specific config — invitation metadata, commission rates, sample policy, content type, support contact. Maps to the legacy TC config blob shape (UPPERCASE root keys: BASE_INVITATION_NAME, VALID_UNTIL, TARGET_COLLAB_MESSAGE, EMAIL, PHONE_NUMBER, OFFER_FREE_SAMPLES, AUTO_APPROVE, PRODUCTS) — the worker reads from those, so the translator flattens this nested model accordingly. |
| messages | [MessageAddon] | false | none | Initial-outreach addons — text, images, product cards, etc. ALL items in this list are sent immediately together when the automation engages a creator. Use follow_ups for delayed follow-up steps. Empty messages = invite-only TC. |
| follow_ups | [FollowUpStep] | false | none | Delayed follow-up steps. Each step has delay_days after the prior step (or after the initial outreach for the first follow-up) and one or more addons that fire together. Use this to build a multi-touch sequence. |
| ai_enabled | boolean | false | none | none |
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| auto_resolve_conflicts | string | false | none | How the runtime handles creators who already have a pending TC invite from another automation. SKIP_ALL leaves them untouched; MOVE_NOT_ACCEPTED (default — matches portal-created automations) re-targets creators whose prior invite was never accepted; MOVE_ALL re-targets regardless of prior invite state. Maps to config.AUTO_RESOLVE_CONFLICTS. |
| is_evergreen | boolean | false | none | When true, the automation continuously re-evaluates its creators_to_include.filters and queues newly-qualifying creators on each run. Has no effect for lists mode (lists are static) or crm_group mode (CRM groups are inherently evergreen). Maps to top-level Automations.is_evergreen column. |
| business_hours_timezone | any | false | none | When set, the runtime restricts outbound message delivery (initial outreach + follow-ups) to 9am–9pm in this IANA timezone (e.g. America/Los_Angeles). Null disables the restriction — messages can fire at any time within the schedule's daily window. The 9–9 window is fixed; only the timezone is configurable. Distinct from schedule.timezone, which governs when the automation evaluates its queue (per CORE-3031). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| auto_resolve_conflicts | SKIP_ALL |
| auto_resolve_conflicts | MOVE_NOT_ACCEPTED |
| auto_resolve_conflicts | MOVE_ALL |
AutomationTcCleanupRequest
{
"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"
}
AutomationTcCleanupRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | string | true | none | none |
| schedule | AutomationSchedule | true | none | Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema. |
| creators_to_include | CreatorsToInclude | false | none | Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A): * lists mode — list_upload and/or lists_selected populated* filters mode — filters populated (dynamic by attribute)* crm_group mode — crm_group_id populated (saved predicate)The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derivedfrom which mode is set — callers don't need to set it explicitly. |
| creators_to_exclude | CreatorsToExclude | false | none | Outreach-paradigm recipient exclusion. Mirrors creators_to_omit inthe legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel. |
| products | [TargetCollabProduct] | true | none | Products to re-invite the matching creators for. Cleanup uses the same TargetCollabProduct shape (product_id + commission rates) as a regular TC. Required — runtime needs at least one product to issue the re-invite. |
| invite_start_before_days | any | false | none | Re-target only creators whose original TC invite was sent at least N days ago. Null = no lower bound on invite age. Persists as config.INVITE_START_BEFORE_DAYS. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| invite_expire_after_days | any | false | none | Re-target only creators whose original TC invite expires within the next N days. Null = no upper bound on time-to-expiry. Persists as config.INVITE_EXPIRE_AFTER_DAYS. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationUpdateRequest
{
"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"
}
AutomationUpdateRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| schedule | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | AutomationSchedule | false | none | Per-day creator-outreach caps + run window. Stored into Automations.schedule JSONB. Same shape as the existing portal payload — keeps the portal and Public API agreeing on schema. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_include | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CreatorsToInclude | false | none | Outreach-paradigm recipient inclusion. Three mutually-exclusive modes (cf. INTERNAL-design-review.md §11A): * lists mode — list_upload and/or lists_selected populated* filters mode — filters populated (dynamic by attribute)* crm_group mode — crm_group_id populated (saved predicate)The validator below rejects any request that mixes modes. The creator_source_type discriminator written to config is derivedfrom which mode is set — callers don't need to set it explicitly. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_to_exclude | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CreatorsToExclude | false | none | Outreach-paradigm recipient exclusion. Mirrors creators_to_omit inthe legacy DB column / frontend payload, plus the boolean exclude_previously_messaged flag from the portal's Exclude Creators panel. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| messages | any | false | none | Replace the initial-outreach addon set. ALL items are sent immediately together when the automation engages a creator. Pass [] to clear messages (invite-only). Use follow_ups for delayed sequencing. Only valid for target_collab and dm automations. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [MessageAddon] | false | none | [One element of a messages[].addons array — a single content blockinside a follow-up step. Polymorphic by type.Per PR #1513 round-3 review (coderabbitai): each type has requiredfields validated below. Without this, {"type": "image"} (noimage_url) slipped through and was persisted to the config blob, leaving the runtime with an addon that advertised a type but had no payload to render.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follow_ups | any | false | none | Replace the delayed follow-up sequence. Pass [] to clear. Only valid for target_collab and dm automations. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [FollowUpStep] | false | none | [One delayed follow-up after the initial outreach. Each step has a delay (days after the prior step / initial outreach for the first follow-up) and one or more addons that run together when the step fires. Per architecture review 2026-05-01 the API was refactored from a single messages: List[MessageStep] array (with step discriminator)into TWO arrays: messages for initial outreach, follow_ups fordelayed steps. Mirrors the runtime config shape ( config.addons[]vs config.FOLLOW_UP_STEPS[]) — the previous translator wasflattening follow-up addons into config.addons[] where theruntime never reads them, silently dropping follow-up sends.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| target_collab | any | false | none | Partial update for the TC-specific config. Send only the keys you want to change — supported sub-keys mirror TargetCollabConfig: invitation_name, valid_until, message, products, content_type, sample_policy, support_contact, lock_receivers_profiles. Unknown keys are rejected with 422 (extra='forbid'). The translator merges into the existing config blob and dual-writes to the legacy UPPERCASE root. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollabPatchPayload | false | none | All-Optional companion to TargetCollabConfig for PATCH bodies.extra="forbid" rejects typos so a PATCH like {invitatoin_name:<br>"..."} returns 422 instead of silently no-op'ing. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dm_config | any | false | none | Partial update for the DM-specific config. Currently supports spark_code only (other dm_config keys were removed 2026-05-01). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DmConfigPatchPayload | false | none | All-Optional companion to DmConfig for PATCH bodies. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_request | any | false | none | Partial update for the sample-request config. Send only the keys you want to change — supported sub-keys mirror SampleRequestPayload: action, rejection_reason, approval_message, rejection_message, message_images, products, minimum_performance_criteria, maximum_performance_criteria, auto_approval_settings, target_list. Unknown keys (top-level OR nested) are rejected with 422 (extra='forbid'). The translator routes both criteria blocks through the V2 prefix + percent-scale helper. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | SampleRequestPatchPayload | false | none | All-Optional companion to SampleRequestPayload for PATCH bodies.Reuses the create-time nested types ( SampleRequestProducts,SampleRequestPerformanceCriteria, SampleRequestAutoApprovalSettings)which already have extra="forbid". |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ai_enabled | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| is_evergreen | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| business_hours_timezone | any | false | none | Set or change the 9am–9pm send-window timezone (CORE-3031). Pass an IANA name to enable, or the empty string "" to disable. Only valid for target_collab and dm automations. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| email_sent_per_day | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| subject | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| body | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationUpdateRequestPublic
{
"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"
}
AutomationUpdateRequestPublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| trigger_frequency | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TriggerFrequency | false | none | How often the automation evaluates its conditions. Only daily is honoured by the offline execution engine today; theportal FE submits this value exclusively. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_ids | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conditions | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [ConditionRulePublic] | false | none | [One condition row in an automation's trigger logic.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| actions | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [ActionRulePublic] | false | none | [One side-effect the automation performs when its conditions fire.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| guardrails | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [GuardrailRulePublic] | false | none | [A safety cap that prevents the automation from spending past a limit.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| boost_start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| boost_end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationWriteResponseV2
{
"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": {}
}
AutomationWriteResponseV2
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | AutomationResourceV2 | true | none | Canonical write-endpoint response. Replaces the v1 AutomationResource (which mirrored the legacy single-shape body). Now reflects the four-type taxonomy — automation_type is the public-API type, not theDB string. The DB string is in _internal_type for debugging only. |
| dry_run | boolean | false | none | none |
| side_effects | any | false | none | Backend side-effects, e.g. {'crm_group_created': 'uuid-...'} for sample_request creates. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationsListAggregate
{
"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
}
AutomationsListAggregate
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_reached | any | false | none | Shop-wide distinct creators reached, summed across daily rollups in the window. Matches the portal's 'Creators Reached' column. NOT a global distinct count — a creator reached on multiple days is counted on each. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_invites | any | false | none | Shop-wide count of Target Collab invitations sent, summed across daily rollups in the window. Matches the portal's 'Target Collabs' column. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_invites_creator_count | any | false | none | Shop-wide distinct creators in Target Collab creator-list arrays, computed per day and summed across the window. Matches the portal dashboard's 'Total Creators' sub-label under Target Collabs — this is the field that customers comparing API to UI most commonly expect. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_messaged | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| emails_sent | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_request | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_approved | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_posted | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_converted | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| spark_codes | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| added_showcase_affiliates | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| accepted_tc_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_showcase_creator_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_content_creator_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_acceptance_rate | any | false | none | Average TC acceptance rate across the daily rollups in the window (mean of daily rates, not creator-weighted). Mirrors the portal dashboard's computation. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationsListPaginatedResponse
{
"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
}
}
AutomationsListPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [AutomationListItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| aggregate | any | false | none | Shop-wide windowed metric totals — populated only when a date filter is supplied. These are NOT sums of the per-row fields above; they come from the same agency rollup the portal Outreach Metrics dashboard reads. Use this object when you want numbers that match the portal UI exactly. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | AutomationsListAggregate | false | none | Shop-wide windowed metric totals matching the portal's Outreach Metrics dashboard. Sourced from customers.agency_dashboard_table(a daily pre-aggregated rollup) and SUMmed across the daily rows inside the requested window — same computation the portal UI does. SHOP-WIDE — NOT per-automation. Counted DISTINCT per day, then summed across days; a creator reached on Tue AND Wed counts twice. Populated only when start_date and/or end_date is suppliedon the request (the aggregate is window-scoped by design). Noneon unfiltered calls. Mapping to the portal's "Outreach Metrics" card columns: - creators_reached → "Creators Reached"- tc_invites → "Target Collabs"- tc_invites_creator_count → "Total Creators" sub-labelunder Target Collabs |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
AutomationsListRequest
{
"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"
]
}
AutomationsListRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | Inclusive window start (YYYY-MM-DD). When supplied (alone or with end_date), creators_reached / skipped / total_creators switch from LIFETIME materialized-view values to in-window DISTINCT counts against the raw event tables. Filters the row set on Automation.created_at as well. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Inclusive window end (YYYY-MM-DD). When supplied (alone or with start_date), see start_date for the creator-metric semantic change. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_via | any | false | none | Include only automations created by these surfaces. Common values: portal |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| exclude_created_via | any | false | none | Exclude automations created by these surfaces. Applied after created_via. Example: ["api_direct"] hides the API direct invite — {handle} rows produced by POST /public/v1/target-collabs so the list shows only your managed automations. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | gmv |
| anonymous | created_at |
| anonymous | completed_at |
| anonymous | creators_reached |
| anonymous | dm_response_count |
| sort_dir | asc |
| sort_dir | desc |
CampaignArchivedResponse
{
"campaign_id": 0,
"status": "archived"
}
CampaignArchivedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | none |
| status | string | false | none | none |
CampaignCreateRequest
{
"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": {}
}
}
CampaignCreateRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_name | string | true | none | none |
| campaign_type | CampaignType | true | none | Supported campaign types. |
| creator_source | CreatorSource | true | none | How creators are sourced for a campaign. |
| start_date | string | true | none | none |
| end_date | any | false | none | YYYY-MM-DD. REQUIRED for challenge / leaderboard / live_gmv_challenge campaigns (the portal launch form requires an end date for these); optional only for retainer campaigns, which may run open-ended. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| description | any | false | none | REQUIRED for launch. Rich-text (HTML) campaign description shown to creators. Must contain visible text — an empty string or HTML-only value like '' is rejected, matching the portal launch form. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | CampaignStatus | false | none | DB-level campaign status. The frontend filter param 'active'/'past' are UI aliases — 'active' maps to published, 'past' maps to != published. |
| pricing | any | true | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | RetainerPricing | false | none | Pricing configuration for retainer campaigns. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | ChallengePricing | false | none | Pricing configuration for challenge campaigns. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | LeaderboardPricing | false | none | Pricing configuration for leaderboard campaigns. Extra keys are IGNORED (the codebase default, matching every sibling pricing class): the brand FE sends UI-only toggles like minimum_gmv_required_enabled that are not modelled here. Thesmuggling protection the materializer needs comes from re-parsing the stored template pricing through this model, which drops unknown keys so they never reach a materialized instance — not from extra="forbid",which would break the live create/edit path. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | LiveGMVChallengePricing | false | none | Pricing configuration for live GMV challenge campaigns. |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| products | any | false | none | REQUIRED for launch. The portal launch form needs at least one product: send products.all_selected=true to include every shop product, or products.items=[...] with 1-10 products. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignProducts | false | none | Product configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators | any | false | none | Optional list of creators to seed into the campaign. Mirrors the portal's contract exactly (see community.schemas.campaign.CampaignCreate.creators) so the public API doesn't fork from /api/marketplace/v2. Each dict is opaque to validation but is typically `{"creator_id": int, "tier": str |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [object] | false | none | none |
| »» additionalProperties | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | null | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| window_url | any | false | none | HTTPS URL — public landing/preview page for this campaign. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| is_available_to_all | boolean | false | none | none |
| requires_approval | boolean | false | none | none |
| creator_level | any | false | none | Creator tier filter (list or CSV string). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| support_email | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| short_header_message | any | false | none | REQUIRED for launch. Short headline shown on the campaign card. Must be a non-empty string — the portal launch form rejects a blank value. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content_guidelines | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
| »» additionalProperties | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| inspiration_links | any | false | none | List of HTTPS URLs (inspiration videos, mood-boards, etc.). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| has_tiered_payout | boolean | false | none | none |
| payout_structure | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| grace_period | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reminders | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignReminders | false | none | Reminder configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| email_templates | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignEmailTemplates | false | none | Email template configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignCreatedResponse
{
"campaign_id": 0,
"uuid_id": "string",
"status": "created",
"invite_link": "string"
}
CampaignCreatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | none |
| uuid_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | false | none | none |
| invite_link | any | false | none | Public invite URL the caller can share with creators to join this campaign. Subdomain is picked by creator_source: social_army campaigns (legacy partnership) use https://soco.reacherapp.com; every other source — my_community and the rest — uses https://creator.reacherapp.com. Full pattern: {base}/campaigns/{shop_id}/{uuid_id}. Always populated on a successful 201. Falsy only in the unexpected case where the service returned without setting uuid_id. Available on every campaign endpoint that returns a campaign payload: POST /campaigns, GET /campaigns, GET /campaigns/{id}, GET /campaigns/{id}/detail — uniform contract. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignDeletedResponse
{
"campaign_id": 0,
"status": "deleted"
}
CampaignDeletedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | none |
| status | string | false | none | none |
CampaignEmailTemplates
{
"enabled": true,
"application": {},
"acceptance": {},
"rejection": {}
}
CampaignEmailTemplates
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| enabled | boolean | false | none | none |
| application | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| acceptance | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rejection | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignProducts
{
"all_selected": false,
"items": [
{
"product_id": "string",
"tap_link": "string",
"product_name": "string"
}
],
"use_first_product_image": true,
"custom_image": "string",
"campaign_image": "string"
}
CampaignProducts
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| all_selected | boolean | false | none | Whether all shop products are selected |
| items | [ProductItem] | false | none | Selected product list |
| use_first_product_image | any | false | none | Use first product image as campaign image |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| custom_image | any | false | none | Custom campaign image (base64 or URL) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_image | any | false | none | Resolved campaign image URL (read-only) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignReminders
{
"enabled": false,
"message_before_3_days": "string",
"message_before_1_day": "string"
}
CampaignReminders
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| enabled | boolean | false | none | none |
| message_before_3_days | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message_before_1_day | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignStatus
"published"
CampaignStatus
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| CampaignStatus | string | false | none | DB-level campaign status. The frontend filter param 'active'/'past' are UI aliases — 'active' maps to published, 'past' maps to != published. |
Enumerated Values
| Property | Value |
|---|---|
| CampaignStatus | published |
| CampaignStatus | draft |
| CampaignStatus | deleted |
| CampaignStatus | archived |
CampaignType
"retainer"
CampaignType
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| CampaignType | string | false | none | Supported campaign types. |
Enumerated Values
| Property | Value |
|---|---|
| CampaignType | retainer |
| CampaignType | challenge |
| CampaignType | leaderboard |
| CampaignType | live_gmv_challenge |
CampaignUpdateRequest
{
"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": {}
}
}
CampaignUpdateRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| description | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignStatus | false | none | DB-level campaign status. The frontend filter param 'active'/'past' are UI aliases — 'active' maps to published, 'past' maps to != published. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| pricing | any | false | none | none |
anyOf - discriminator: campaign_type
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | any | false | none | none |
oneOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »» anonymous | RetainerPricing | false | none | Pricing configuration for retainer campaigns. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »» anonymous | ChallengePricing | false | none | Pricing configuration for challenge campaigns. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »» anonymous | LeaderboardPricing | false | none | Pricing configuration for leaderboard campaigns. Extra keys are IGNORED (the codebase default, matching every sibling pricing class): the brand FE sends UI-only toggles like minimum_gmv_required_enabled that are not modelled here. Thesmuggling protection the materializer needs comes from re-parsing the stored template pricing through this model, which drops unknown keys so they never reach a materialized instance — not from extra="forbid",which would break the live create/edit path. |
xor
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »» anonymous | LiveGMVChallengePricing | false | none | Pricing configuration for live GMV challenge campaigns. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| products | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignProducts | false | none | Product configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators | any | false | none | Optional list of creators to seed into the campaign. Mirrors the portal's contract exactly (see community.schemas.campaign.CampaignCreate.creators) so the public API doesn't fork from /api/marketplace/v2. Each dict is opaque to validation but is typically `{"creator_id": int, "tier": str |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [object] | false | none | none |
| »» additionalProperties | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| »»» anonymous | null | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| window_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| is_available_to_all | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| requires_approval | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_level | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| support_email | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| short_header_message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content_guidelines | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
| »» additionalProperties | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| inspiration_links | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| has_tiered_payout | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| payout_structure | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| grace_period | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reminders | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignReminders | false | none | Reminder configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| email_templates | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CampaignEmailTemplates | false | none | Email template configuration for a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CampaignUpdatedResponse
{
"campaign_id": 0,
"status": "updated"
}
CampaignUpdatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | none |
| status | string | false | none | none |
ChallengePricing
{
"campaign_type": "challenge",
"payment_tiers": [
{
"threshold": 0,
"compensation": 0,
"videos_required": 0
}
],
"reward_type": "cash",
"metric_type": "gmv",
"minimum_gmv_required": 0,
"minimum_gmv_required_enabled": false,
"minimum_views_required": 0,
"minimum_videos_required": 0,
"ranking_priority": "gmv"
}
ChallengePricing
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_type | string | false | none | none |
| payment_tiers | [PaymentTier] | true | none | At least one tier required |
| reward_type | RewardType | true | none | Cash or custom reward |
| metric_type | string | false | none | Performance metric to evaluate |
| minimum_gmv_required | any | false | none | Minimum GMV floor (gmv_videos gate) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_gmv_required_enabled | boolean | false | none | Whether the minimum GMV floor is active |
| minimum_views_required | any | false | none | Minimum views floor (when metric is views) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_videos_required | any | false | none | Minimum videos floor (videos_posted / gmv_videos gate) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ranking_priority | any | false | none | Primary ranking metric for gmv_videos contests; the other is a per-tier requirement |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| metric_type | gmv |
| metric_type | views |
| metric_type | videos_posted |
| metric_type | gmv_videos |
| anonymous | gmv |
| anonymous | videos |
ConditionMetric
"creative_roi"
ConditionMetric
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ConditionMetric | string | false | none | Metric a condition evaluates against the campaign / creative window. The first nine values are what the portal FE exposes in the Create-Automation form. The trailing four ( roi, spend, ctr,spend_pacing) appear in /templates payloads — accepted so acaller that round-trips a template through POST /automations isnot rejected by validation. |
Enumerated Values
| Property | Value |
|---|---|
| ConditionMetric | creative_roi |
| ConditionMetric | creative_revenue |
| ConditionMetric | campaign_roi |
| ConditionMetric | campaign_revenue |
| ConditionMetric | campaign_cost |
| ConditionMetric | click_through_rate |
| ConditionMetric | organic_engagement_rate |
| ConditionMetric | product_ad_clicks |
| ConditionMetric | 2s_video_view_rate |
| ConditionMetric | roi |
| ConditionMetric | spend |
| ConditionMetric | ctr |
| ConditionMetric | spend_pacing |
ConditionOperator
"lt"
ConditionOperator
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ConditionOperator | string | false | none | Comparison operator. Both the FE's short form (lt, gte) andthe legacy symbol form ( >=, <) are accepted — the controllertreats them as synonyms. |
Enumerated Values
| Property | Value |
|---|---|
| ConditionOperator | lt |
| ConditionOperator | gte |
| ConditionOperator | >= |
| ConditionOperator | <= |
| ConditionOperator | > |
| ConditionOperator | < |
| ConditionOperator | == |
ConditionRulePublic
{
"metric": "creative_roi",
"operator": "lt",
"value": 0,
"lookback_days": 3
}
ConditionRulePublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| metric | ConditionMetric | true | none | Metric to evaluate. See ConditionMetric for the full set. |
| operator | ConditionOperator | true | none | Comparison operator. lt / gte are the FE forms; >= / < etc. are legacy and equally accepted. |
| value | number | true | none | Threshold the metric is compared against. |
| lookback_days | integer | false | none | How many days of history the metric is computed over. Default 3. |
CreateDepositIntentRequest
{
"amount": 100000,
"currency": "USD",
"success_url": "string",
"cancel_url": "string"
}
CreateDepositIntentRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| amount | number | true | none | none |
| currency | string | false | none | ISO 4217 currency. The wallet's persisted currency overrides this for cross-currency safety. |
| success_url | string | true | none | URL Stripe redirects to on completion. Must use a Reacher-controlled host (app.reacherapp.com, portal.reacherapp.com, staging.reacherapp.com) or localhost/127.0.0.1 for development. |
| cancel_url | string | true | none | none |
CreateDraftDryRunResponse
{
"dry_run": true,
"would_create_for_handle": "string",
"content_type": "string",
"text": "string",
"image_url": "string",
"product_id": "string"
}
CreateDraftDryRunResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dry_run | boolean | false | none | none |
| would_create_for_handle | string | true | none | none |
| content_type | string | true | none | none |
| text | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreateDraftRequest
{
"creator_handle": "string",
"text": "string",
"image_url": "stringstri",
"product_id": "string"
}
CreateDraftRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | string | true | none | The creator's TikTok handle (with or without leading @). Must already have an open conversation with this shop — drafts can only be staged on existing conversations, the same prerequisite TikTok enforces on the live-send path. |
| text | any | false | none | Plain-text reply body. Set this OR image_url OR product_id (exactly one). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | any | false | none | HTTPS URL of an image to send. Same SSRF + size + type constraints as the live /reply/image endpoint will apply when the human ships the draft — we do NOT fetch the URL at draft time (no outbound network call from this endpoint). Set this OR text OR product_id (exactly one). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | A TikTok product_id from THIS shop's catalog. Ownership is verified ONLY when the human clicks Send in the inbox — the draft endpoint does not pre-check the catalog (the catalog can change between draft and send anyway). Set this OR text OR image_url (exactly one). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreateDraftResponse
{
"id": 0,
"conversation_id": 0,
"content_type": "string",
"text_content": "string",
"payload": {},
"created_at": "string",
"expires_at": "string",
"created_by_api_key_id": 0
}
CreateDraftResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer | true | none | none |
| conversation_id | integer | true | none | none |
| content_type | string | true | none | 'text' |
| text_content | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| payload | object | false | none | none |
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| expires_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_by_api_key_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorConversationItem
{
"creator_handle": "string",
"last_message_text": "string",
"last_message_time": "string",
"last_message_sender": "string",
"unread_count": 0
}
CreatorConversationItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | Creator username (no leading @). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| last_message_text | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| last_message_time | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| last_message_sender | any | false | none | 'creator' or 'shop'. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| unread_count | integer | false | none | none |
CreatorConversationsResponse
{
"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
}
CreatorConversationsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CreatorConversationItem] | true | none | none |
| offset | integer | true | none | none |
| limit | integer | true | none | none |
| has_more | boolean | true | none | none |
| total_count | integer | true | none | none |
CreatorDetailResponse
{
"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"
}
CreatorDetailResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | CreatorListItem | true | none | none |
| groups | [CreatorGroupItem] | false | none | none |
| products | [CreatorProductItem] | false | none | none |
| videos | [VideoItem] | false | none | none |
| currency | string | true | none | none |
CreatorFilters
{
"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"
]
}
CreatorFilters
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_categories | any | false | none | TikTok Shop product category names (e.g. 'Beauty & Personal Care'). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_ethnicity | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gender | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| age_range | any | false | none | Age buckets, e.g. ['18-24', '25-34']. Buckets are platform-defined. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| languages | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Creator GMV in USD. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| average_views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| engagement_rate | any | false | none | 0.0-1.0 fraction (e.g. 0.05 = 5%). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| post_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_gpm | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| live_gpm | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FilterRange | false | none | Inclusive numeric range. At least one of min / max must be set;the other is open-ended. Used by CreatorFilters for every range-style filter (GMV, followercount, average views, engagement rate, etc.). API exposes {min, max}objects; the translator converts to the legacy ["custom:min-max"]string form config.Filters expects. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_age | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_gender | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| face_visibility | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content_style | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| production_quality | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| personality_tone | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| body_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| hair_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorGroupItem
{
"group_id": "string",
"group_name": "string"
}
CreatorGroupItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| group_id | string | true | none | none |
| group_name | string | true | none | none |
CreatorListItem
{
"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"
}
CreatorListItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_count | any | false | none | DB: follower_num |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | Display status from rev_status_mapping() |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_gmv | any | false | none | Lifetime shop-specific GMV. DB: crm_creators.gmv |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| overall_gmv | any | false | none | Overall GMV from regional creator table. DB: Creator.gmv_num |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| overall_fulfillment_rate | any | false | none | Overall fulfillment rate from regional creator table |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_units_sold | any | false | none | DB: item_sold |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_video_count | any | false | none | DB: video_num |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_views | any | false | none | DB: content_video_views |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_received | any | false | none | DB: sample_received_num |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| commission_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| est_commission | any | false | none | DB: estimate_commission |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| fulfillment_rate | any | false | none | Shop-specific fulfillment rate from crm_creators |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tags | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorMessageDraft
{
"id": 0,
"conversation_id": 0,
"content_type": "string",
"text_content": "string",
"payload": {},
"created_at": "string",
"expires_at": "string",
"created_by_api_key_id": 0
}
CreatorMessageDraft
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer | true | none | none |
| conversation_id | integer | true | none | none |
| content_type | string | true | none | 'text' |
| text_content | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| payload | object | false | none | none |
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| expires_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| created_by_api_key_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorMessageItem
{
"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"
}
]
}
}
CreatorMessageItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | integer | true | none | none |
| sender | string | true | none | 'creator' (inbound) or 'shop' (outbound). |
| content_type | string | true | none | none |
| text | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | ImageContent | false | none | Image-specific content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_card | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | ProductCardContent | false | none | Product card-specific content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| target_collaboration_card | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollaborationCardContent | false | none | Target collaboration card-specific content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| free_sample_card | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | FreeSampleCardContent | false | none | Free sample card-specific content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_text_with_image_card | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CrmTextWithImageCardContent | false | none | CRM text with image card content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_text_with_products_card | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CrmTextWithProductsCardContent | false | none | CRM text with products card content fields. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorMessagesResponse
{
"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
}
CreatorMessagesResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | string | true | none | none |
| data | [CreatorMessageItem] | true | none | [A single creator-conversation message. The text field is populated for plain-text messages. For richer types(image, product card, target-collab card, free-sample card, CRM cards) the matching nested object below carries the type-specific payload — only the one matching content_type is populated; the rest are null.AI agents need these payloads to understand what was actually sent (image URL, product_id, invitation_group_id, etc.); without them a non-text content_type leaves the caller blind.] |
| page | integer | true | none | none |
| has_more | boolean | true | none | none |
CreatorPerformanceItem
{
"creator_id": "string",
"creator_handle": "string",
"gmv": 0,
"units_sold": 0,
"order_count": 0,
"est_commission": 0,
"follower_count": 0
}
CreatorPerformanceItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | string | true | none | none |
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | GMV earned in the date range (not lifetime) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| est_commission | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_count | any | false | none | Latest follower count in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorPerformanceRequest
{
"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
}
CreatorPerformanceRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | gmv |
| anonymous | units_sold |
| anonymous | order_count |
| anonymous | est_commission |
| anonymous | follower_count |
| sort_dir | asc |
| sort_dir | desc |
CreatorPerformanceResponse
{
"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"
]
}
CreatorPerformanceResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CreatorPerformanceItem] | true | none | [Creator with period-specific metrics from creator_info (daily table).] |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorProductItem
{
"product_id": "string",
"product_title": "string",
"commission_rate": 0,
"shop_units_sold": 0,
"shop_gmv": 0,
"status": "string"
}
CreatorProductItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| product_title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| commission_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_units_sold | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorProductsPaginatedResponse
{
"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"
]
}
CreatorProductsPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CreatorProductItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorProductsRequest
{
"page": 1,
"page_size": 50
}
CreatorProductsRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
CreatorReplyDryRunResponse
{
"dry_run": true,
"would_send_to": "string",
"message": "string"
}
CreatorReplyDryRunResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dry_run | boolean | false | none | none |
| would_send_to | string | true | none | none |
| message | string | true | none | none |
CreatorReplyImageDryRunResponse
{
"dry_run": true,
"would_send_to": "string",
"image_url": "string"
}
CreatorReplyImageDryRunResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dry_run | boolean | false | none | none |
| would_send_to | string | true | none | none |
| image_url | string | true | none | none |
CreatorReplyImageInfo
{
"url": "string",
"width": 0,
"height": 0
}
CreatorReplyImageInfo
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| url | string | true | none | none |
| width | integer | false | none | none |
| height | integer | false | none | none |
CreatorReplyImageRequest
{
"image_url": "stringstri"
}
CreatorReplyImageRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | string | true | none | HTTPS URL of an image to forward to the creator. We fetch it server-side (must resolve to a public IP, return Content-Type image/*, ≤ 5 MB), then upload to TikTok and dispatch. |
CreatorReplyImageResponse
{
"conversation_id": 0,
"message_id": 0,
"message_index": 0,
"sent_at": "string",
"image": {
"url": "string",
"width": 0,
"height": 0
},
"dry_run": false
}
CreatorReplyImageResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conversation_id | integer | true | none | none |
| message_id | integer | true | none | none |
| message_index | integer | true | none | none |
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image | CreatorReplyImageInfo | true | none | none |
| dry_run | boolean | false | none | none |
CreatorReplyProductDryRunResponse
{
"dry_run": true,
"would_send_to": "string",
"product_id": "string"
}
CreatorReplyProductDryRunResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dry_run | boolean | false | none | none |
| would_send_to | string | true | none | none |
| product_id | string | true | none | none |
CreatorReplyProductRequest
{
"product_id": "string"
}
CreatorReplyProductRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | A TikTok product_id from THIS shop's catalog. Sending another shop's product_id is rejected with 400. |
CreatorReplyProductResponse
{
"conversation_id": 0,
"message_id": 0,
"message_index": 0,
"sent_at": "string",
"product_id": "string",
"dry_run": false
}
CreatorReplyProductResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conversation_id | integer | true | none | none |
| message_id | integer | true | none | none |
| message_index | integer | true | none | none |
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| dry_run | boolean | false | none | none |
CreatorReplyRequest
{
"message": "string"
}
CreatorReplyRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | Plain-text reply body to send to the creator. |
CreatorReplyResponse
{
"conversation_id": 0,
"message_id": 0,
"message_index": 0,
"text": "string",
"sent_at": "string",
"dry_run": false
}
CreatorReplyResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conversation_id | integer | true | none | none |
| message_id | integer | true | none | none |
| message_index | integer | true | none | none |
| text | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dry_run | boolean | false | none | none |
CreatorSource
"my_community"
CreatorSource
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| CreatorSource | string | false | none | How creators are sourced for a campaign. |
Enumerated Values
| Property | Value |
|---|---|
| CreatorSource | my_community |
| CreatorSource | social_army |
CreatorStateChangeResponse
{
"success": true,
"code": "ok",
"data": {}
}
CreatorStateChangeResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | none |
| code | string | false | none | none |
| data | object | false | none | none |
CreatorStatus
"pending"
CreatorStatus
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| CreatorStatus | string | false | none | Lifecycle status of a creator within a campaign. |
Enumerated Values
| Property | Value |
|---|---|
| CreatorStatus | pending |
| CreatorStatus | invited |
| CreatorStatus | applied |
| CreatorStatus | active |
| CreatorStatus | rejected |
| CreatorStatus | Paid/Settled |
| CreatorStatus | archived |
| CreatorStatus | completed |
| CreatorStatus | removed |
CreatorTrendSeries
{
"affiliate_gmv": [
0
],
"video_gmv": [
0
],
"videos_posted": [
0
],
"total_video_views": [
0
],
"units_sold": [
0
],
"commission": [
0
]
}
CreatorTrendSeries
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| affiliate_gmv | [number] | true | none | none |
| video_gmv | [number] | true | none | none |
| videos_posted | [integer] | true | none | none |
| total_video_views | [integer] | true | none | none |
| units_sold | [integer] | true | none | none |
| commission | [number] | true | none | none |
CreatorTrendsRequest
{
"creator_handles": [
"string"
],
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
CreatorTrendsRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handles | [string] | true | none | Creator handles to fetch series for. Max 100 per call — this mirrors the internal per-page cap and keeps the response bounded. Handles that don't resolve in this shop are reported in unresolved_handles. |
| start_date | any | false | none | Window start (inclusive). Omit for a trailing 28-day window ending at end_date. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Window end (inclusive). Defaults to today. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorTrendsResponse
{
"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"
}
}
CreatorTrendsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | object | true | none | Keyed by creator handle. Creators with no activity are zero-filled, not omitted. |
| » additionalProperties | CreatorTrendSeries | false | none | Six parallel daily series. Every array has one entry per day in the window, ordered oldest → newest, aligned positionally with days. |
| days | [string] | true | none | ISO date axis for every series in data. |
| unresolved_handles | [string] | false | none | Requested handles with no creator record in this shop. Absent from data. |
| currency | string | true | none | none |
| date_range | ResolvedDateRange | true | none | The window the server actually used, after defaults were applied. |
CreatorVideosRequest
{
"page": 1,
"page_size": 50,
"sort_by": "video_gmv",
"sort_dir": "asc",
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
CreatorVideosRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | video_gmv |
| anonymous | views |
| anonymous | units_sold |
| anonymous | posted_date |
| anonymous | like_count |
| sort_dir | asc |
| sort_dir | desc |
CreatorsListPaginatedResponse
{
"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"
]
}
CreatorsListPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CreatorListItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorsListRequest
{
"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"
}
CreatorsListRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_shop_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_overall_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_videos | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_followers | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| group_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tags | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | shop_gmv |
| anonymous | follower_count |
| anonymous | shop_video_count |
| anonymous | shop_units_sold |
| anonymous | video_views |
| anonymous | updated_at |
| anonymous | created_at |
| sort_dir | asc |
| sort_dir | desc |
CreatorsSummaryRequest
{
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
CreatorsSummaryRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | Window start (inclusive). Omit for a trailing 28-day window ending at end_date. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Window end (inclusive). Defaults to today. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CreatorsSummaryResponse
{
"data": {
"new_creators": 0,
"gmv_generated": 0,
"video_posts": 0,
"orders": 0
},
"currency": "string",
"date_range": {
"start_date": "string",
"end_date": "string"
}
}
CreatorsSummaryResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | CreatorsSummaryTotals | true | none | none |
| currency | string | true | none | none |
| date_range | ResolvedDateRange | true | none | The window the server actually used, after defaults were applied. |
CreatorsSummaryTotals
{
"new_creators": 0,
"gmv_generated": 0,
"video_posts": 0,
"orders": 0
}
CreatorsSummaryTotals
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| new_creators | integer | true | none | Creators whose first-ever CRM record falls inside the window. |
| gmv_generated | number | true | none | Affiliate-attributed GMV earned in the window. |
| video_posts | integer | true | none | Distinct videos posted in the window. |
| orders | integer | true | none | Affiliate orders placed in the window. |
CreatorsToExclude
{
"list_upload": [
"string"
],
"lists_selected": [
"string"
],
"crm_groups": [
"string"
],
"exclude_previously_messaged": false
}
CreatorsToExclude
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_upload | [string] | false | none | none |
| lists_selected | [string] | false | none | none |
| crm_groups | [string] | false | none | UUIDs of existing CRM Groups whose current members should be excluded. Use GET /crm-groups to discover. |
| exclude_previously_messaged | boolean | false | none | Skip creators this shop has DM'd before in any prior automation. Maps to config.exclude_previously_messaged. |
CreatorsToInclude
{
"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"
}
CreatorsToInclude
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_upload | [string] | false | none | Ad-hoc creator handles (TikTok @-names) to include in this automation only. NOT persisted as a Lists row. |
| lists_selected | [string] | false | none | IDs of existing Lists (vault_files.resource_id) whose creators should be included. Use POST /lists to upload reusable lists. |
| filters | any | false | none | Dynamic creator selection by attribute. When set, the parent automation's is_evergreen=true flag re-evaluates the filter on every run. Mutually exclusive with list_upload/lists_selected and crm_group_id. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CreatorFilters | false | none | Dynamic creator selection by attribute. When is_evergreen=true onthe parent automation, the filter is re-evaluated on every run. Mirrors the portal's "Filters" tab (formDataTransformer.ts:735-824 buildFilters for the legacy config.Filters shape, andbuildAISearchFilters for the AI-search variant). The translatorsplits AI-only fields out into config.ai_search_filters and setsconfig.uses_ai_filters=true accordingly.All fields are optional — set only the ones you care about. An empty CreatorFilters({}) is invalid (use lists mode instead). |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_id | any | false | none | Single CRM group ID (UUID string). Membership is dynamic — the runtime re-evaluates on every send. Mutually exclusive with the other two modes. Use GET /crm-groups to discover available groups (returns the canonical IDs to pass here). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_entered_after | any | false | none | Optional CRM-group filter — only include members who entered the group ON or AFTER this date. Ignored unless crm_group_id is set. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_entered_before | any | false | none | Optional CRM-group filter — only include members who entered the group ON or BEFORE this date. Ignored unless crm_group_id is set. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmGroupCondition
{
"field": "string",
"operator": "string",
"value": null,
"value_count": 0
}
CrmGroupCondition
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| field | string | true | none | e.g. 'status', 'products', 'shop_gmv'. |
| operator | string | true | none | e.g. 'is_one_of', 'gte'. |
| value | any | true | none | none |
| value_count | any | false | none | Set only when value is a long list that has been sampled down. It is the true length; value holds the first 50 entries. Groups built from a dashboard segment store their whole membership inline, so this is common on those. Read the group's creator_count for its size, not len(value). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmGroupFromSegmentRequest
{
"group_name": "string",
"tier": "string",
"automation_id": 1,
"start_date": "2019-08-24",
"end_date": "2019-08-24",
"group_tags": [
"string"
]
}
CrmGroupFromSegmentRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| group_name | string | true | none | Name for the new group. Creation upserts by (shop, group_name) — reusing a name overwrites that group's definition and re-materializes its members. |
| tier | any | false | none | GMV tier code to narrow the segment, e.g. 'L3'. Omit for all tiers. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | any | false | none | Restrict the segment to creators reached by this automation. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | Segment window start (inclusive). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Segment window end (inclusive). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| group_tags | any | false | none | Optional tags to attach to the group. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmGroupFromSegmentResponse
{
"data": {
"crm_group_id": "string",
"name": "string",
"creator_count": 0,
"handles_resolved": 0,
"group_tags": [
"string"
]
},
"dry_run": true
}
CrmGroupFromSegmentResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | CrmGroupFromSegmentResult | true | none | none |
| dry_run | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmGroupFromSegmentResult
{
"crm_group_id": "string",
"name": "string",
"creator_count": 0,
"handles_resolved": 0,
"group_tags": [
"string"
]
}
CrmGroupFromSegmentResult
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_id | any | false | none | UUID of the created group. Null on a dry run. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | true | none | none |
| creator_count | integer | true | none | Creators actually materialized into the group — those that mapped to a CRM record. This is the group's real size. |
| handles_resolved | integer | true | none | Creators the segment matched before CRM mapping. Always >= creator_count; the gap between the two is the drop-off from creators that have no CRM record (DM-only and organic creators cannot be grouped). |
| group_tags | [string] | false | none | none |
CrmGroupResource
{
"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"
}
CrmGroupResource
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| crm_group_id | string | true | none | UUID — stable across creator membership changes. |
| name | string | true | none | none |
| description | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conditions | [CrmGroupCondition] | false | none | Filter conditions joined with AND. Membership semantics depend on how the group was built: filter-built groups are dynamic and creators flow in/out as their attributes change, while groups created from a dashboard segment (POST /crm-groups/from-segment) are snapshots whose members were fixed at creation. A single creatorNames condition is the signal for the latter. |
| creator_count | integer | true | none | Current member count. |
| last_synced_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmGroupResponse
{
"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"
}
}
CrmGroupResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | CrmGroupResource | true | none | none |
CrmGroupsPaginatedResponse
{
"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
}
CrmGroupsPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CrmGroupResource] | true | none | none |
| pagination | any | true | none | none |
CrmProductCardItem
{
"product_id": "string",
"product_name": "string",
"image_url": "string"
}
CrmProductCardItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmTextWithImageCardContent
{
"title": "string",
"content": "string",
"url": "string"
}
CrmTextWithImageCardContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
CrmTextWithProductsCardContent
{
"title": "string",
"content": "string",
"products": [
{
"product_id": "string",
"product_name": "string",
"image_url": "string"
}
]
}
CrmTextWithProductsCardContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| products | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [CrmProductCardItem] | false | none | [Single product within a CRM text with products card.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
DateRange
{
"start_date": "string",
"end_date": "string"
}
DateRange
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
DepositIntentResponse
{
"session_id": "string",
"redirect_url": "string"
}
DepositIntentResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| session_id | string | true | none | Stripe Checkout session ID. |
| redirect_url | string | true | none | URL to redirect the user to in order to complete the deposit. No money moves until the user finishes Stripe's hosted checkout. |
DmConfig
{
"spark_code": {
"only_collect_creator_information": false,
"spark_code_submission_url": "string"
}
}
DmConfig
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| spark_code | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DmSparkCodeConfig | false | none | dm-mode=spark_code — TikTok spark code collection form. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
DmConfigPatchPayload
{
"spark_code": {
"only_collect_creator_information": false,
"spark_code_submission_url": "string"
}
}
DmConfigPatchPayload
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| spark_code | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DmSparkCodeConfig | false | none | dm-mode=spark_code — TikTok spark code collection form. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
DmPersonalizationConfig
{
"enabled": true,
"tone": "engaging",
"fallback_message": "string",
"offer_discussion": "",
"product_description": "",
"product_selling_points": ""
}
DmPersonalizationConfig
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| enabled | boolean | false | none | Master switch. Set false to persist the config without personalizing sends (e.g. staging copy for later). |
| tone | any | false | none | AI rewrite tone. Null uses the engine default (engaging). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| fallback_message | string | true | none | Sent when a creator has too little signal to personalize. Required — personalization must always have a safe fallback. |
| offer_discussion | string | false | none | [Offer Discussion] block value — your offer text. |
| product_description | string | false | none | [Product Description] block value. Pre-resolve via POST /personalization/product-blocks. |
| product_selling_points | string | false | none | [Product Selling Points] block value. Pre-resolve via POST /personalization/product-blocks. |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | engaging |
| anonymous | bold |
| anonymous | inspirational |
DmSparkCodeConfig
{
"only_collect_creator_information": false,
"spark_code_submission_url": "string"
}
DmSparkCodeConfig
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| only_collect_creator_information | boolean | false | none | none |
| spark_code_submission_url | string | true | none | Portal-hosted form URL. Auto-generated if not provided by the route. |
DraftListResponse
{
"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
}
DraftListResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [CreatorMessageDraft] | true | none | [One draft row, as returned by create / list / delete echo paths. Mirrors the column shape in conversation_message_drafts. Only thefield matching content_type is populated — for text drafts,text_content is set and payload is {}; for image draftspayload = {"image_url": "..."}; for product draftspayload = {"product_id": "..."}. Keeping the response shape tightmeans an agent caller can render the draft without parsing more than necessary.] |
| page | integer | true | none | none |
| page_size | integer | true | none | none |
| total | integer | true | none | none |
| has_more | boolean | true | none | none |
EmailAttachment
{
"name": "string",
"url": "string"
}
EmailAttachment
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | true | none | Display name for the attachment (e.g. deck.pdf). |
| url | string | true | none | Hosted HTTPS URL of the attachment. Reacher fetches the file from this URL at create time, runs the standard upload validation pipeline (size, MIME type, virus scan), and re-hosts to internal storage. The provided URL is NOT used at send time — only at create time. |
EmailFilters
{
"min_creator_gmv": 0,
"min_followers": 0,
"min_engagement_rate": 1,
"min_avg_views": 0,
"regions": [
"string"
],
"categories": [
"string"
]
}
EmailFilters
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_creator_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_followers | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_engagement_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_avg_views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| regions | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| categories | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
EmailMailingList
{
"list_upload_emails": [
"string"
],
"lists_selected": [
"string"
]
}
EmailMailingList
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_upload_emails | [string] | false | none | none |
| lists_selected | [string] | false | none | none |
FilterRange
{
"min": 0,
"max": 0
}
FilterRange
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| max | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
FollowUpStep
{
"delay_days": 30,
"addons": [
{
"type": "message",
"body": "string",
"image_url": "string",
"product_id": "string",
"submission_url_slug": "string"
}
]
}
FollowUpStep
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| delay_days | integer | true | none | Days to wait after the prior step (or after initial outreach for the first follow-up). |
| addons | [MessageAddon] | true | none | Addons sent together when this follow-up step fires. Only message and image addon types are supported in follow-ups; product_card, spark_code_form, and target_invite are initial-outreach-only — use messages for those. |
FreeSampleCardContent
{
"apply_id": "string"
}
FreeSampleCardContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| apply_id | string | true | none | none |
GmvMaxCampaignItem
{
"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"
}
GmvMaxCampaignItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| campaign_id | string | true | none | none |
| campaign_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shopping_ads_type | any | false | none | GMV Max objective / ads type. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| budget | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| roas_bid | any | false | none | Target ROAS bid set on the campaign. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| last_synced_at | any | false | none | ISO 8601 UTC of the most recent TikTok sync. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency | any | false | none | ISO currency code for the shop's region. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
GmvMaxCampaignMetricItem
{
"date": "string",
"spend": 0,
"impressions": 0,
"clicks": 0,
"orders": 0,
"gross_revenue": 0,
"cpc": 0,
"cpm": 0,
"ctr": 0,
"roas": 0
}
GmvMaxCampaignMetricItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| date | string | true | none | ISO 8601 date (YYYY-MM-DD) for this metric row. |
| spend | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| impressions | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| clicks | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| orders | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gross_revenue | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| cpc | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| cpm | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ctr | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| roas | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
GmvMaxCampaignMetricsResponse
{
"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"
}
GmvMaxCampaignMetricsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | string | true | none | none |
| shop_id | integer | true | none | none |
| data | [GmvMaxCampaignMetricItem] | true | none | none |
| start_date | string | true | none | none |
| end_date | string | true | none | none |
| currency | string | true | none | none |
GmvMaxCampaignsResponse
{
"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"
]
}
GmvMaxCampaignsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [GmvMaxCampaignItem] | true | none | none |
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
GuardrailRulePublic
{
"rule_type": "total_creative_boost_cost",
"operator": "lt",
"value": 0
}
GuardrailRulePublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rule_type | GuardrailRuleType | true | none | Which limit this guardrail enforces. total_creative_boost_cost is the lifetime spend cap and is required on every set_up_creative_boost automation. |
| operator | any | false | none | Comparison operator. Optional — defaults to < for spend-cap-style guardrails when omitted. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | ConditionOperator | false | none | Comparison operator. Both the FE's short form (lt, gte) andthe legacy symbol form ( >=, <) are accepted — the controllertreats them as synonyms. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| value | number | true | none | Threshold value. |
GuardrailRuleType
"total_creative_boost_cost"
GuardrailRuleType
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| GuardrailRuleType | string | false | none | What a guardrail enforces.total_creative_boost_cost is the lifetime spend cap and ismandatory on every set_up_creative_boost automation (enforcedby AutomationCreateRequest.validate_total_budget_cap). Theremaining values are metric-name guardrails that cap a specific metric per evaluation window. |
Enumerated Values
| Property | Value |
|---|---|
| GuardrailRuleType | total_creative_boost_cost |
| GuardrailRuleType | creative_roi |
| GuardrailRuleType | creative_revenue |
| GuardrailRuleType | campaign_roi |
| GuardrailRuleType | campaign_revenue |
| GuardrailRuleType | campaign_cost |
| GuardrailRuleType | max_budget_daily |
| GuardrailRuleType | cooldown_hours |
HTTPValidationError
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}
HTTPValidationError
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| detail | [ValidationError] | false | none | none |
ImageContent
{
"url": "string",
"width": 0,
"height": 0
}
ImageContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| url | string | true | none | none |
| width | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| height | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
LeaderboardPricing
{
"campaign_type": "leaderboard",
"leaderboard_ranks": [
{
"rank": 1,
"reward": 0
}
],
"reward_type": "cash",
"metric_type": "gmv",
"scoring_mode": "single",
"weighted_metrics": [
{
"metric_type": "gmv",
"weight": 100
}
],
"minimum_gmv_required": 0,
"minimum_views_required": 0,
"minimum_videos_required": 0
}
LeaderboardPricing
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_type | string | false | none | none |
| leaderboard_ranks | [LeaderboardRank] | true | none | At least one rank required |
| reward_type | RewardType | true | none | Cash or custom reward |
| metric_type | MetricType | false | none | Performance metric to evaluate |
| scoring_mode | string | false | none | Rank by a single metric or by a weighted composite score |
| weighted_metrics | any | false | none | Metric weights (must sum to 100) when scoring_mode is weighted |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [WeightedMetricItem] | false | none | [One metric + weight entry in a weighted leaderboard.extra="forbid": template pricing JSONB round-trips through themicro-challenge materializer — unknown keys must not smuggle through.] |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_gmv_required | any | false | none | Minimum GMV threshold (when metric includes gmv) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_views_required | any | false | none | Minimum views threshold (when metric is views) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_videos_required | any | false | none | Minimum videos floor (gmv_videos gate; ranking stays by GMV) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| scoring_mode | single |
| scoring_mode | weighted |
LeaderboardRank
{
"rank": 1,
"reward": 0
}
LeaderboardRank
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rank | integer | true | none | Rank position (1-indexed) |
| reward | any | true | none | Reward for this rank |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
ListMembersResponse
{
"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"
]
}
ListMembersResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | ListResource | true | none | A Lists row (vault_files). Used across all 4 automation types. |
| creator_handles | [string] | true | none | none |
| creator_emails | [string] | true | none | none |
ListResource
{
"list_id": "string",
"name": "string",
"description": "string",
"creator_count": 0,
"email_count": 0,
"state": "string",
"created_at": "string",
"updated_at": "string"
}
ListResource
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| list_id | string | true | none | vault_files.resource_id |
| name | string | true | none | none |
| description | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_count | integer | true | none | none |
| email_count | integer | true | none | none |
| state | string | true | none | active |
| created_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ListResponse
{
"data": {
"list_id": "string",
"name": "string",
"description": "string",
"creator_count": 0,
"email_count": 0,
"state": "string",
"created_at": "string",
"updated_at": "string"
}
}
ListResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | ListResource | true | none | A Lists row (vault_files). Used across all 4 automation types. |
ListsPaginatedResponse
{
"data": [
{
"list_id": "string",
"name": "string",
"description": "string",
"creator_count": 0,
"email_count": 0,
"state": "string",
"created_at": "string",
"updated_at": "string"
}
],
"pagination": null
}
ListsPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [ListResource] | true | none | [A Lists row (vault_files). Used across all 4 automation types.] |
| pagination | any | true | none | none |
LiveGMVChallengePricing
{
"campaign_type": "live_gmv_challenge",
"payment_tiers": [
{
"threshold": 0,
"compensation": 0,
"videos_required": 0,
"sessions_required": 0
}
],
"reward_type": "cash",
"metric_type": "live_gmv",
"minimum_live_gmv_required": 0,
"minimum_sessions_required": 0,
"ranking_priority": "live_gmv"
}
LiveGMVChallengePricing
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_type | string | false | none | none |
| payment_tiers | [LivePaymentTier] | true | none | At least one tier required |
| reward_type | RewardType | true | none | Cash or custom reward |
| metric_type | string | false | none | Live performance metric to evaluate |
| minimum_live_gmv_required | any | false | none | Minimum LIVE GMV floor (sessions_and_live_gmv gate) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_sessions_required | any | false | none | Minimum sessions floor (sessions_and_live_gmv gate) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ranking_priority | any | false | none | Primary ranking metric for sessions_and_live_gmv contests; the other is a per-tier requirement |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| metric_type | live_gmv |
| metric_type | sessions |
| metric_type | sessions_and_live_gmv |
| anonymous | live_gmv |
| anonymous | sessions |
LivePaymentTier
{
"threshold": 0,
"compensation": 0,
"videos_required": 0,
"sessions_required": 0
}
LivePaymentTier
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| threshold | number | true | none | Metric threshold for this tier |
| compensation | any | true | none | Payout at this tier |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_required | any | false | none | Number of videos required for this tier |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sessions_required | any | false | none | Number of live sessions required for this tier (sessions_and_live_gmv metric) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
MessageAddon
{
"type": "message",
"body": "string",
"image_url": "string",
"product_id": "string",
"submission_url_slug": "string"
}
MessageAddon
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| type | string | true | none | none |
| body | any | false | none | Message body (REQUIRED for type=message). Supports {creator_name} placeholder. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | any | false | none | Hosted HTTPS URL of the image (REQUIRED for type=image). Reacher fetches this URL server-side and re-hosts on the internal CDN — file uploads (multipart) are NOT accepted. Reject if http://, data:, blob:, or scheme-relative. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | Product ID (REQUIRED for type=product_card; OPTIONAL for type=target_invite). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| submission_url_slug | any | false | none | Spark code form slug (REQUIRED for type=spark_code_form). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| type | message |
| type | image |
| type | product_card |
| type | spark_code_form |
| type | target_invite |
MetricType
"gmv"
MetricType
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| MetricType | string | false | none | Performance metric used for evaluation. |
Enumerated Values
| Property | Value |
|---|---|
| MetricType | gmv |
| MetricType | views |
| MetricType | videos_posted |
| MetricType | gmv_videos |
| MetricType | live_gmv |
| MetricType | sessions |
| MetricType | sessions_and_live_gmv |
| MetricType | avg_views_per_post |
| MetricType | units_sold |
MetricsSummaryRequest
{
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
MetricsSummaryRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
MetricsSummaryResponse
{
"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"
]
}
MetricsSummaryResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Affiliate-attributed GMV for the period — Reacher's view of creator-driven sales. This is NOT the shop's full GMV. For the headline number that matches the customer's TikTok Seller Center dashboard (which includes ads / Smart+ and organic), use total_gmv or the dedicated POST /shop-gmv/* endpoints. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| total_gmv | any | false | none | Full shop GMV for the period — includes ads / Smart+ and organic revenue, not just affiliate-attributed sales. Sourced from the TikTok Seller Center scrape. Coverage is rolling out per-shop; shops not yet covered return 0. For per-day breakdown by channel (video / live / product_card) and explicit per-shop currency handling, use POST /shop-gmv/* instead. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| active_creators | any | false | none | Distinct creators with activity in the period (not summed daily counts) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_views | any | false | none | Total video views in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_posted | any | false | none | New videos posted in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| samples_approved | any | false | none | Samples approved in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv_per_video | any | false | none | Avg GMV per video posted in the period. Matches dashboard 'GMV per Video' |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv_per_sample | any | false | none | Avg GMV per sample. Matches dashboard 'GMV per Sample' |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_requests | any | false | none | Total sample requests in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv_driving_videos | any | false | none | Videos that generated sales in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| new_creators_posting | any | false | none | First-time creators who posted in the period |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| open_collabs | any | false | none | Open collaboration affiliates added |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| accepted_tc_count | any | false | none | Accepted target collaborations |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_reached | any | false | none | Creators reached via outreach |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creators_messaged | any | false | none | Creators messaged |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| tc_invites_sent | any | false | none | Target collaboration invites sent |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| emails_sent | any | false | none | Emails sent |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| dm_responses | any | false | none | Sum of daily unique DM responses (not deduplicated across the period) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reply_rate | any | false | none | DM reply rate: (dm_responses / dm_messages_sent) * 100 |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| orders | any | false | none | Whole-shop orders for the period across all sales channels, from TikTok Seller Center. Shops not yet on the Seller Center daily sync return 0. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | Whole-shop units sold for the period across all sales channels, from TikTok Seller Center. 0 for shops not yet covered. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| aov | any | false | none | Average order value for the period (total GMV / total orders over the date range, not an average of daily AOV). 0 when the shop has no orders or is not yet covered. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| ctr | any | false | none | Click-through rate as a percent for the period (total clicks / total impressions over the date range). 0 when uncovered or no impressions. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| conversion_rate | any | false | none | Conversion rate as a percent for the period (total orders / total clicks over the date range). 0 when uncovered or no clicks. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| errors | any | false | none | Metric keys that failed (null values in response) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | string | true | none | none |
| end_date | string | true | none | none |
| currency | string | true | none | none |
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
OutreachCapacityResponse
{
"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
}
OutreachCapacityResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| daily_creators_used | integer | true | none | Distinct (creator, automation) outreach sends counted for this shop in the current UTC day. Counts actual sends only — invites that were skipped (e.g. creator_not_found) do not count. |
| daily_window_resets_at | string | true | none | ISO-8601 UTC timestamp of the next daily-window reset (next 00:00 UTC). |
| concurrent_automations_running | integer | true | none | Outreach automations currently in a running/paused-but-live state. |
| max_concurrent_automations | integer | true | none | Plan ceiling for concurrent automations. |
| daily_limit_throttled | boolean | true | none | True when a live automation is currently paused by the daily outreach limit. |
| weekly_limit_throttled | boolean | true | none | True when a live automation is currently paused by TikTok's weekly outreach limit. When true, daily capacity is moot until the weekly window resets (start of next week). |
PaymentTier
{
"threshold": 0,
"compensation": 0,
"videos_required": 0
}
PaymentTier
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| threshold | number | true | none | Metric threshold for this tier |
| compensation | any | true | none | Payout at this tier |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_required | any | false | none | Number of videos required for this tier |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
PersonalizationCreatorSentMessage
{
"automation_id": 0,
"message": "string",
"is_fallback": true,
"tone": "string",
"sent_at": "string"
}
PersonalizationCreatorSentMessage
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | any | false | none | The automation that sent this message (null for legacy/pre-save rows). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | The exact personalized copy sent to this creator. |
| is_fallback | boolean | true | none | none |
| tone | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sent_at | any | false | none | ISO 8601 UTC send time. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
PersonalizationCreatorSentMessagesResponse
{
"creator_id": "string",
"count": 0,
"messages": [
{
"automation_id": 0,
"message": "string",
"is_fallback": true,
"tone": "string",
"sent_at": "string"
}
]
}
PersonalizationCreatorSentMessagesResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | string | true | none | none |
| count | integer | true | none | Number of messages returned (after the limit cap). |
| messages | [PersonalizationCreatorSentMessage] | false | none | none |
PersonalizationFallbackStatsResponse
{
"automation_id": 0,
"messages_sent": 0,
"fallback_used": 0,
"fallback_rate": 0
}
PersonalizationFallbackStatsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | integer | true | none | none |
| messages_sent | integer | true | none | Personalized outreach messages this automation has sent (lifetime, all runs). |
| fallback_used | integer | true | none | How many of those used the brand fallback (creator had too little signal). |
| fallback_rate | number | true | none | fallback_used / messages_sent (0.0 when nothing has been sent). |
PersonalizationPreviewCreator
{
"creator_id": "string",
"creator_handle": "string",
"creator_first_name": ""
}
PersonalizationPreviewCreator
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | string | true | none | TikTok creator id (as returned by GET /automations/{id}/creators). |
| creator_handle | string | true | none | TikTok handle without the @. |
| creator_first_name | string | false | none | Optional known first name; the engine resolves the real one when omitted. |
PersonalizationPreviewRequest
{
"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": ""
}
PersonalizationPreviewRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator | PersonalizationPreviewCreator | true | none | The single creator to generate a preview for. |
| message_body | string | true | none | The DM template with [Block] tokens (mirrors the automation's CREATOR_MESSAGE). |
| tone | string | false | none | none |
| fallback_message | string | true | none | Sent (name/product blocks filled) when the creator has too little signal to personalize. Required — matches the DM config contract: personalization must always have a safe fallback, so a low-signal preview never returns an empty message. |
| brand_name | string | false | none | Brand display name used in the copy. Defaults to the shop name when omitted. |
| product_description | string | false | none | Pre-resolved [Product Description]. Get it from POST /personalization/product-blocks. |
| product_selling_points | string | false | none | Pre-resolved [Product Selling Points]. Get it from POST /personalization/product-blocks. |
| offer_discussion | string | false | none | [Offer Discussion] block value — the brand's offer text. |
Enumerated Values
| Property | Value |
|---|---|
| tone | engaging |
| tone | bold |
| tone | inspirational |
PersonalizationPreviewResponse
{
"creator_id": "string",
"message": "string",
"is_fallback": true,
"blocks_used": [
"string"
]
}
PersonalizationPreviewResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | string | true | none | none |
| message | string | true | none | The fully assembled message this creator would receive. |
| is_fallback | boolean | true | none | True when the creator had too little signal to personalize, so the brand fallback message was used instead of AI-generated blocks. |
| blocks_used | [string] | false | none | Which [Block] tokens were filled (e.g. content_discussion, product_discussion, product_description, offer_discussion). |
PersonalizationProductBlocksRequest
{
"product_id": "string"
}
PersonalizationProductBlocksRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | A product id in this shop's catalog. Blocks resolve empty if it isn't. |
PersonalizationProductBlocksResponse
{
"product_description": "",
"product_selling_points": ""
}
PersonalizationProductBlocksResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_description | string | false | none | [Product Description] resolved from this shop's product catalog. Empty when the product isn't in this shop or has no description. |
| product_selling_points | string | false | none | [Product Selling Points] derived from the product's real title/description/attributes. Empty when there's too little grounded product info to derive them. |
PersonalizationRetoneRequest
{
"message_body": "string",
"tone": "engaging"
}
PersonalizationRetoneRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message_body | string | true | none | The message body to rewrite. Every [Block] token is preserved. |
| tone | string | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| tone | engaging |
| tone | bold |
| tone | inspirational |
PersonalizationRetoneResponse
{
"message": "string"
}
PersonalizationRetoneResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | The rewritten message body, with every [Block] token preserved. |
ProductCardContent
{
"product_id": "string",
"product_name": "string",
"image_url": "string"
}
ProductCardContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| image_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductCreatorItem
{
"creator_handle": "string",
"follower_count": 0,
"commission_rate": 0,
"gmv": 0
}
ProductCreatorItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | DB: crm_creators.creator_name |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| follower_count | any | false | none | DB: follower_num |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| commission_rate | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductCreatorsRequest
{
"page": 1,
"page_size": 50
}
ProductCreatorsRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
ProductCreatorsResponse
{
"data": [
{
"creator_handle": "string",
"follower_count": 0,
"commission_rate": 0,
"gmv": 0
}
],
"currency": "string",
"pagination": null,
"shops_queried": [
"string"
]
}
ProductCreatorsResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [ProductCreatorItem] | true | none | none |
| currency | string | true | none | ISO 4217 currency code for monetary values |
| pagination | any | true | none | none |
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductItem
{
"product_id": "string",
"tap_link": "string",
"product_name": "string"
}
ProductItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| tap_link | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductListItem
{
"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
}
ProductListItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | SUM of product_info.gmv_amount, normalized to float |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | SUM of item_sold_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| refund_units | any | false | none | SUM of refund_item_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_count | any | false | none | SUM of video_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_count | any | false | none | SUM of sample_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| live_count | any | false | none | SUM of live_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| est_commission | any | false | none | SUM of est_commission_amount, normalized |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_status | any | false | none | From product_catalog. NULL for unofficial shops. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_total_gmv | any | false | none | Total product GMV across all sales channels, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_orders | any | false | none | Number of orders for this product, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_units_sold | any | false | none | Units sold for this product, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_customers | any | false | none | Distinct buyers for this product, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_aov | any | false | none | Average order value (total GMV / total orders over the date range); null if no orders. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_impressions | any | false | none | Product impressions, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_clicks | any | false | none | Product clicks, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_ctr | any | false | none | Click-through rate as a percent (total clicks / total impressions over the date range); null if no impressions. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_conversion | any | false | none | Conversion rate as a percent (total orders / total clicks over the date range); null if no clicks. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_gmv_per_1k_impr | any | false | none | GMV per 1,000 impressions (total GMV / total impressions x 1,000 over the date range); null if no impressions. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_add_to_cart | any | false | none | Add-to-cart count for this product, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_affiliate_gmv | any | false | none | GMV from the affiliate channel. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_seller_video_gmv | any | false | none | GMV from the seller's own videos. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_seller_live_gmv | any | false | none | GMV from the seller's own live streams. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_product_card_gmv | any | false | none | GMV from product cards. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_shop_tab_gmv | any | false | none | GMV from the shop tab. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sc_refunds | any | false | none | Refund amount for this product, from TikTok Seller Center. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductVideosRequest
{
"page": 1,
"page_size": 50,
"sort_by": "video_gmv",
"sort_dir": "asc",
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
ProductVideosRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | video_gmv |
| anonymous | views |
| anonymous | units_sold |
| anonymous | posted_date |
| anonymous | like_count |
| sort_dir | asc |
| sort_dir | desc |
ProductsListPaginatedResponse
{
"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"
]
}
ProductsListPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [ProductListItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ProductsListRequest
{
"page": 1,
"page_size": 50,
"sort_by": "gmv",
"sort_dir": "asc",
"start_date": "2019-08-24",
"end_date": "2019-08-24",
"product_name": "string"
}
ProductsListRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | gmv |
| anonymous | units_sold |
| anonymous | video_count |
| anonymous | sample_count |
| anonymous | est_commission |
| sort_dir | asc |
| sort_dir | desc |
RejectCreatorRequest
{
"message": "string"
}
RejectCreatorRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | any | false | none | Optional custom message included in the creator's rejection email/SMS. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
RemoveCreatorRequest
{
"campaign_id": 0,
"message": "string"
}
RemoveCreatorRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | Campaign (in the x-shop-id shop) to remove the creator from. |
| message | any | false | none | Optional SMS sent to the creator on removal. Removal is otherwise silent (no email, no default SMS). Length capped at 320 to match the service's SMS limit. SKIPPED on X-Dry-Run. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
RemoveCreatorResponse
{
"success": true,
"code": "ok",
"data": {}
}
RemoveCreatorResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | false | none | none |
| code | string | false | none | ok on a real removal; already_removed on an idempotent no-op replay of an already-removed mapping. |
| data | object | false | none | {campaign_creator_mapping_id, status='removed'}. |
RequestMoreContentRequest
{
"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"
}
RequestMoreContentRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | integer | true | none | none |
| campaign_creator_mapping_id | integer | true | none | none |
| campaign_id | integer | true | none | none |
| additional_posts | integer | true | none | none |
| new_total_payout | any | true | none | New total payout — number for cash campaigns, string label (e.g. 'free product') for custom-reward campaigns. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_gmv_target | number | true | none | none |
| tiktok_username | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | CreatorStatus | false | none | Lifecycle status of a creator within a campaign. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
RequestMoreContentResponse
{
"status": "success"
}
RequestMoreContentResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | false | none | none |
ResolvedDateRange
{
"start_date": "string",
"end_date": "string"
}
ResolvedDateRange
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | string | true | none | none |
| end_date | string | true | none | none |
RetainerPricing
{
"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
}
RetainerPricing
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_type | string | false | none | none |
| posts | integer | true | none | Required posts per creator |
| payment_per_creator | any | true | none | Payment amount (float for cash, str for custom) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reward_type | RewardType | true | none | Cash or custom reward |
| metric_type | MetricType | false | none | Performance metric to evaluate |
| minimum_gmv_required | any | false | none | Minimum GMV threshold |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_gmv_required_enabled | boolean | false | none | Whether minimum GMV requirement is active |
| minimum_views_required | any | false | none | Minimum views threshold |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_views_required_enabled | boolean | false | none | Whether minimum views requirement is active |
| minimum_videos_required | any | false | none | Minimum videos threshold (for videos_posted/gmv_videos metric) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
RewardType
"cash"
RewardType
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| RewardType | string | false | none | Reward payout mechanism. |
Enumerated Values
| Property | Value |
|---|---|
| RewardType | cash |
| RewardType | custom |
SampleByProductItem
{
"product_id": "string",
"product_name": "string",
"total_requests": 0,
"approved": 0,
"sample_gmv": 0,
"videos_from_samples": 0
}
SampleByProductItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | none |
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| total_requests | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| approved | any | false | none | DB: shipped_sample_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_from_samples | any | false | none | DB: received_sample_and_posted_video_cnt |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SampleListItem
{
"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"
}
SampleListItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | Display status from rev_status_mapping() |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_received | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| bio | any | false | none | Creator bio text. Sourced from the per-region creators table — the same field exposed by the AI Creator Search API. Null when the creator has no regional row. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| categories | any | false | none | Creator categories / niches. Parsed via the same helper the AI Creator Search API uses (handles JSON-array and comma-separated stored values). Null when the creator has no regional row. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| any | false | none | Creator contact email when known on the regional creators table. Null when the creator has no regional row or no email captured. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SampleRequestAutoApprovalSettings
{
"enabled": false,
"total_weekly_approved_sample_limit": 1,
"always_approve_status": "string",
"always_approve_from_lists_ids": [
0
]
}
SampleRequestAutoApprovalSettings
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| enabled | boolean | false | none | none |
| total_weekly_approved_sample_limit | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| always_approve_status | any | false | none | Auto-approve creators whose top-level automation_status matches this value (e.g. APPROVED, LIVE_CREATOR). Null = no status-based bypass. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| always_approve_from_lists_ids | [integer] | false | none | Vault list IDs whose members bypass criteria gates and are always approved. |
SampleRequestPatchPayload
{
"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
]
}
SampleRequestPatchPayload
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| action | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rejection_reason | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| approval_message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rejection_message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message_images | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| products | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | SampleRequestProducts | false | none | Sample-request product targeting. Two modes: * include_all_products=True → all shop products eligible; supplyweekly_auto_approval_per_product for the global per-product cap.* include_all_products=False → enumerate selected_products withper-product max_approvals_per_week caps.Mirrors the legacy sample_request_config.products shape exactly soFE-built and API-built automations are interchangeable to the worker. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| minimum_performance_criteria | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | SampleRequestPerformanceCriteria | false | none | Min/max performance gate for sample-request approval. All fields are optional — omit a field to skip that side of the bound. API contract uses unprefixed field names + decimal 0-1 scale for rates ( engagement_rate=0.05 for 5%). The translator emits the V2 backend'sasymmetric prefix names + 0-100 percent scale at persistence. See modules/automations/SampleRequestConfigModels.py for the V2 shape: - min side → min_followers, min_avg_views, min_engagement_rate,min_post_rate, min_creator_gmv_30_days, min_gmv_per_sample- max side → maximum_followers, maximum_avg_views,maximum_engagement_rate, maximum_post_rate,maximum_creator_gmv, maximum_gmv_per_sample |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| maximum_performance_criteria | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | SampleRequestPerformanceCriteria | false | none | Min/max performance gate for sample-request approval. All fields are optional — omit a field to skip that side of the bound. API contract uses unprefixed field names + decimal 0-1 scale for rates ( engagement_rate=0.05 for 5%). The translator emits the V2 backend'sasymmetric prefix names + 0-100 percent scale at persistence. See modules/automations/SampleRequestConfigModels.py for the V2 shape: - min side → min_followers, min_avg_views, min_engagement_rate,min_post_rate, min_creator_gmv_30_days, min_gmv_per_sample- max side → maximum_followers, maximum_avg_views,maximum_engagement_rate, maximum_post_rate,maximum_creator_gmv, maximum_gmv_per_sample |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| auto_approval_settings | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | SampleRequestAutoApprovalSettings | false | none | Optional auto-approval gating beyond the min/max criteria. * enabled=False → manual review for every request that passes theperformance gate. Other fields ignored. * enabled=True + always_approve_status set → auto-approve anycreator whose automation_status matches; bypass criteria.* total_weekly_approved_sample_limit → hard ceiling on weeklyauto-approvals across all creators (not per-product). * always_approve_from_lists_ids → approve members of these vaultlists regardless of criteria. Mirrors sample_request_config.auto_approval_settings. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| target_list | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [integer] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | approve |
| anonymous | reject |
| anonymous | NOT_MATCH |
| anonymous | OFFLINE |
| anonymous | OUT_OF_STOCK |
| anonymous | OTHER |
SampleRequestPayload
{
"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
]
}
SampleRequestPayload
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| action | string | true | none | none |
| rejection_reason | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| approval_message | any | false | none | DM body sent to the creator on approval. Only meaningful when action='approve' — rejected with reject. Persists as sample_request_config.approval_message. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rejection_message | any | false | none | DM body sent to the creator on rejection. Only meaningful when action='reject'. Persists as sample_request_config.rejection_message. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message_images | [string] | false | none | Optional HTTPS image URLs to attach to the approval / rejection DM. Same URL contract as MessageAddon.image_url — server fetches + re-hosts. |
| products | SampleRequestProducts | true | none | Sample-request product targeting. Two modes: * include_all_products=True → all shop products eligible; supplyweekly_auto_approval_per_product for the global per-product cap.* include_all_products=False → enumerate selected_products withper-product max_approvals_per_week caps.Mirrors the legacy sample_request_config.products shape exactly soFE-built and API-built automations are interchangeable to the worker. |
| minimum_performance_criteria | SampleRequestPerformanceCriteria | false | none | Min/max performance gate for sample-request approval. All fields are optional — omit a field to skip that side of the bound. API contract uses unprefixed field names + decimal 0-1 scale for rates ( engagement_rate=0.05 for 5%). The translator emits the V2 backend'sasymmetric prefix names + 0-100 percent scale at persistence. See modules/automations/SampleRequestConfigModels.py for the V2 shape: - min side → min_followers, min_avg_views, min_engagement_rate,min_post_rate, min_creator_gmv_30_days, min_gmv_per_sample- max side → maximum_followers, maximum_avg_views,maximum_engagement_rate, maximum_post_rate,maximum_creator_gmv, maximum_gmv_per_sample |
| maximum_performance_criteria | SampleRequestPerformanceCriteria | false | none | Min/max performance gate for sample-request approval. All fields are optional — omit a field to skip that side of the bound. API contract uses unprefixed field names + decimal 0-1 scale for rates ( engagement_rate=0.05 for 5%). The translator emits the V2 backend'sasymmetric prefix names + 0-100 percent scale at persistence. See modules/automations/SampleRequestConfigModels.py for the V2 shape: - min side → min_followers, min_avg_views, min_engagement_rate,min_post_rate, min_creator_gmv_30_days, min_gmv_per_sample- max side → maximum_followers, maximum_avg_views,maximum_engagement_rate, maximum_post_rate,maximum_creator_gmv, maximum_gmv_per_sample |
| auto_approval_settings | SampleRequestAutoApprovalSettings | false | none | Optional auto-approval gating beyond the min/max criteria. * enabled=False → manual review for every request that passes theperformance gate. Other fields ignored. * enabled=True + always_approve_status set → auto-approve anycreator whose automation_status matches; bypass criteria.* total_weekly_approved_sample_limit → hard ceiling on weeklyauto-approvals across all creators (not per-product). * always_approve_from_lists_ids → approve members of these vaultlists regardless of criteria. Mirrors sample_request_config.auto_approval_settings. |
| target_list | [integer] | true | none | List IDs (vault_files.resource_id, integer form). Required (≥1) — sample_request type uses target_list for creator selection, NOT creators_to_include. |
Enumerated Values
| Property | Value |
|---|---|
| action | approve |
| action | reject |
| anonymous | NOT_MATCH |
| anonymous | OFFLINE |
| anonymous | OUT_OF_STOCK |
| anonymous | OTHER |
SampleRequestPerformanceCriteria
{
"followers": 0,
"avg_views": 0,
"engagement_rate": 1,
"post_rate": 1,
"creator_gmv_30_days": 0,
"gmv_per_sample": 0
}
SampleRequestPerformanceCriteria
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| followers | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| avg_views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| engagement_rate | any | false | none | Decimal 0-1 (e.g. 0.05 = 5%). Translator scales to 0-100 percent at persistence. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| post_rate | any | false | none | Decimal 0-1 (e.g. 0.5 = 50%). Translator scales to 0-100 percent at persistence. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_gmv_30_days | any | false | none | Creator GMV over the trailing 30 days. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv_per_sample | any | false | none | GMV per sample sent — gates whether the creator's prior samples drove enough revenue. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SampleRequestProductCap
{
"product_id": "string",
"max_approvals_per_week": 10000
}
SampleRequestProductCap
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | TikTok Shop product ID (numeric string). |
| max_approvals_per_week | integer | true | none | Per-product weekly auto-approval cap. Matches the V2 backend field name (SampleRequestConfigModels.SelectedProduct.max_approvals_per_week); 0 = no auto-approvals for this product. |
SampleRequestProducts
{
"include_all_products": false,
"selected_products": [
{
"product_id": "string",
"max_approvals_per_week": 10000
}
],
"weekly_auto_approval_per_product": 1
}
SampleRequestProducts
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| include_all_products | boolean | false | none | none |
| selected_products | [SampleRequestProductCap] | false | none | none |
| weekly_auto_approval_per_product | any | false | none | Per-product weekly cap that applies to ALL shop products (only meaningful when include_all_products=True). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SamplesByProductPaginatedResponse
{
"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"
]
}
SamplesByProductPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [SampleByProductItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SamplesByProductRequest
{
"page": 1,
"page_size": 50,
"sort_by": "total_requests",
"sort_dir": "asc",
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
SamplesByProductRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | total_requests |
| anonymous | approved |
| anonymous | sample_gmv |
| sort_dir | asc |
| sort_dir | desc |
SamplesListPaginatedResponse
{
"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"
]
}
SamplesListPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [SampleListItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SamplesListRequest
{
"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"
}
SamplesListRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | updated_at |
| anonymous | created_at |
| anonymous | gmv |
| sort_dir | asc |
| sort_dir | desc |
SentDmGroup
{
"creator_name": "string",
"creator_id": "string",
"last_sent_at": "string",
"messages": [
{
"content": "string",
"sent_at": "string",
"status": "string"
}
]
}
SentDmGroup
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| last_sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| messages | [SentDmMessage] | false | none | none |
SentDmMessage
{
"content": "string",
"sent_at": "string",
"status": "string"
}
SentDmMessage
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content | string | true | none | Exact rendered text as sent (placeholders substituted) |
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | Send-log role, e.g. BOT_INITIAL_MESSAGE / follow-up statuses |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SentDmSection
{
"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"
}
SentDmSection
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| exact_copy | boolean | false | none | True — DM copy is the rendered per-creator sent text |
| groups | [SentDmGroup] | false | none | none |
| creators_returned | integer | true | none | none |
| total_creators | integer | true | none | none |
| total_messages | integer | true | none | none |
| message | any | false | none | Explicit empty state when nothing was sent |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SentTcSection
{
"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"
}
SentTcSection
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| exact_copy | boolean | false | none | False — TC per-creator rendered copy is not stored; template is the sent copy |
| coverage_note | string | true | none | none |
| template_text | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| placeholders_present | boolean | false | none | none |
| invitations | [TcInvitationBatch] | false | none | none |
| invitations_returned | integer | true | none | none |
| total_invitations | integer | true | none | Batches with a sent status (NEW_INVITATION / EDITED_INVITATION); excludes skipped/failed. |
| total_creators_invited | integer | true | none | Creators across sent-status batches only. See status_breakdown for skipped/failed. |
| status_breakdown | object | false | none | Batch count per target_collabs status across ALL rows (sent, skipped=PREVIOUS_INVITATION, INVALID_CREATORS, etc.). |
| » additionalProperties | integer | false | none | none |
| campaign | any | false | none | Campaign linked via campaigns.tc_automation_id, when one exists |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TcCampaignLink | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | any | false | none | Explicit empty state when nothing was sent |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SettlePaymentRequest
{
"creator_id": 0,
"campaign_id": 0,
"amount": 100000,
"currency": "str",
"reward_type": "string",
"campaign_creator_mapping_id": 0,
"metadata": {}
}
SettlePaymentRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | integer | true | none | none |
| campaign_id | integer | true | none | none |
| amount | number | true | none | Settlement amount in the campaign's currency. Capped at $100,000 per call as a sanity guard. |
| currency | string | true | none | ISO 4217 currency code (e.g. 'USD'). Informational — the shop's persisted wallet currency takes precedence at settlement time. If the wallet currency differs from this value, the transfer executes in the wallet currency without rejection. The response's currency field confirms the currency actually used for the transfer. |
| reward_type | string | true | none | 'cash' triggers a Stripe transfer + wallet debit; 'custom' records the settlement only (no money moves). |
| campaign_creator_mapping_id | integer | true | none | REQUIRED. The campaign-creator mapping id that the settlement is being recorded against. The portal surfaces this id on every creator row in GET /campaigns/{id}/detail and in the response to the accept endpoint, so callers always have it. Required because the underlying PaymentService.settle only runs its double-payment guard (claim_for_settlement_sync) when a mapping id is present — omitting it would leave the money-moving path with idempotency-only protection (a different Idempotency-Key per call could debit the wallet repeatedly with no DB-level guard). |
| metadata | any | false | none | Free-form metadata stored alongside the settlement (e.g. agent annotation, internal reference). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | object | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
SettlementResponse
{
"success": true,
"transfer_id": "string",
"amount": 0,
"currency": "string",
"paid_at": "string",
"wallet_balance": 0
}
SettlementResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| success | boolean | true | none | none |
| transfer_id | any | false | none | Stripe transfer id for cash settlements. Null for custom-reward settlements (no Stripe call). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| amount | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| currency | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| paid_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| wallet_balance | any | false | none | Remaining wallet balance after the settlement. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvChannels
{
"video": {
"gmv": 0,
"affiliate": 0,
"seller": 0
},
"live": {
"gmv": 0,
"affiliate": 0,
"seller": 0
},
"product_card": {
"gmv": 0,
"shop_tab": 0,
"search": 0
}
}
ShopGmvChannels
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video | ShopGmvVideoChannel | true | none | Video-attributed GMV breakdown for a single time point. |
| live | ShopGmvLiveChannel | true | none | Live-attributed GMV breakdown for a single time point. |
| product_card | ShopGmvProductCardChannel | true | none | Product-card (organic) GMV breakdown for a single time point. |
ShopGmvLiveChannel
{
"gmv": 0,
"affiliate": 0,
"seller": 0
}
ShopGmvLiveChannel
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Total live-attributed GMV for the day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| affiliate | any | false | none | Live GMV from creator/affiliate lives. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| seller | any | false | none | Live GMV from the seller's own lives. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvProductCardChannel
{
"gmv": 0,
"shop_tab": 0,
"search": 0
}
ShopGmvProductCardChannel
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Total product-card GMV (organic surfaces). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_tab | any | false | none | GMV from customers browsing the shop tab/storefront. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| search | any | false | none | GMV from TikTok search results. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvSeriesPoint
{
"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
}
}
ShopGmvSeriesPoint
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| date | string | true | none | Day (YYYY-MM-DD). |
| gmv | any | false | none | Total GMV for the day (before tax, excl. platform co-funding). Sum of channels ≈ gmv (small residuals possible). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| orders | any | false | none | Paid orders that day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| items_sold | any | false | none | Units sold that day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| customers | any | false | none | Unique paying customers that day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| aov | any | false | none | Average order value for the day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| channels | ShopGmvChannels | true | none | GMV breakdown by attribution channel. |
| traffic | ShopGmvTraffic | true | none | none |
ShopGmvSummaryRequest
{
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
ShopGmvSummaryRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | Inclusive window start (YYYY-MM-DD). Defaults to 29 days before end_date. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Inclusive window end (YYYY-MM-DD). Defaults to yesterday. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvSummaryResponse
{
"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
}
}
ShopGmvSummaryResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| currency_code | any | false | none | ISO currency code; null when window has no data. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | string | true | none | none |
| end_date | string | true | none | none |
| day_count | integer | true | none | Number of daily rows that contributed to these totals. |
| gmv | number | true | none | SUM of daily GMV across the window. |
| orders | integer | true | none | SUM of daily orders. |
| items_sold | integer | true | none | SUM of daily units sold. |
| customers | integer | true | none | SUM of daily unique-customer counts. NOTE: this double-counts buyers who purchased on multiple days; the source rollup is unique-per-day. A true window-distinct count is not derivable from this table. |
| aov | any | false | none | Window-level AOV computed as total GMV / total orders over the window. null when there are no orders. Note: this is NOT the average of daily AOV values (which would be meaningless since daily AOVs have different denominators). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| channels | ShopGmvChannels | true | none | SUMmed channel breakdown across the window. |
| traffic | ShopGmvTraffic | true | none | none |
ShopGmvTimeseriesRequest
{
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
ShopGmvTimeseriesRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| start_date | any | false | none | Inclusive window start (YYYY-MM-DD). Defaults to 29 days before end_date (30-day window). The Seller Center data is back-filled ~90 days per shop, so older ranges will return an empty series. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | Inclusive window end (YYYY-MM-DD). Defaults to yesterday (today is excluded because the daily row is still incomplete). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvTimeseriesResponse
{
"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
}
}
]
}
ShopGmvTimeseriesResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| currency_code | any | false | none | ISO currency code applying to every point in the series (e.g. 'GBP', 'USD'). null when the series is empty or (defensively) when the source rows somehow mix currencies for the same shop — in that case GMV values should not be summed in the client. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| granularity | string | false | none | Always 'daily' in v1. |
| start_date | string | true | none | none |
| end_date | string | true | none | none |
| series | [ShopGmvSeriesPoint] | true | none | One entry per day with data in the window. Empty when the shop has no Seller Center data for this range (collection is rolling out — empty is a normal, non-error state). |
ShopGmvTraffic
{
"product_impressions": 0,
"product_clicks": 0
}
ShopGmvTraffic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_impressions | any | false | none | Product impressions across surfaces. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_clicks | any | false | none | Product clicks across surfaces. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopGmvVideoChannel
{
"gmv": 0,
"affiliate": 0,
"seller": 0
}
ShopGmvVideoChannel
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| gmv | any | false | none | Total video-attributed GMV for the day. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| affiliate | any | false | none | Video GMV from creator/affiliate videos. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| seller | any | false | none | Video GMV from the seller's own videos. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopResponse
{
"shop_id": 0,
"shop_name": "string",
"region": "string",
"currency": "string",
"status": "string",
"primary_category": "string"
}
ShopResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | none |
| shop_name | string | true | none | none |
| region | string | true | none | none |
| currency | string | true | none | none |
| status | string | true | none | none |
| primary_category | any | false | none | Shop's primary L1 product category from TikTok Shop. Matches one of the canonical L1 names returned by GET /api/social-intelligence-v2/sellers/categories. Null when the shop has no Social Intelligence data yet. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopSupportContactDefaultRequest
{
"email": "string",
"phone": "string"
}
ShopSupportContactDefaultRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| string | true | none | Default contact email shown to the creator on the TC card. | |
| phone | any | false | none | Optional default contact phone. E.164 format recommended. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopSupportContactDefaultResponse
{
"shop_id": 0,
"configured": true,
"email": "string",
"phone": "string",
"updated_at": "string"
}
ShopSupportContactDefaultResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_id | integer | true | none | Shop the default applies to. |
| configured | boolean | true | none | True when a default is stored for this shop. When False, TC create requests must supply support_contact per request. |
| any | false | none | Default contact email, or null when not configured. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| phone | any | false | none | Default contact phone, or null when unset/not configured. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| updated_at | any | false | none | ISO-8601 timestamp of the last update, or null when not configured. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
ShopsListResponse
{
"data": [
{
"shop_id": 0,
"shop_name": "string",
"region": "string",
"currency": "string",
"status": "string",
"primary_category": "string"
}
]
}
ShopsListResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [ShopResponse] | true | none | none |
SparkCodeSyncAllRequestPublic
{}
SparkCodeSyncAllRequestPublic
Properties
None
SparkCodeSyncRequestPublic
{
"spark_codes": [
"string"
]
}
SparkCodeSyncRequestPublic
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| spark_codes | [string] | true | none | Up to 100 spark codes to sync in one request. Each code fires one TikTok /tt_video/authorize/ call; rate-limited codes are left as pending so the offline CRJ picks them up. Whitespace is stripped; blank or duplicate entries are rejected with 422. |
TargetCollabConfig
{
"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"
}
}
TargetCollabConfig
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| invitation_name | string | true | none | Name shown on the TC invitation card (max 30 chars). Required by the portal — without it, the card displays empty. Persists as config.BASE_INVITATION_NAME. |
| valid_until | any | false | none | Date the TC card stops being valid. After this, the dispatcher stops the automation (see internal/queries/automations_to_run.py). Null = no expiry. Distinct from end_date (top-level automation stop date) — they can differ. Persists as config.VALID_UNTIL in MM/DD/YYYY format (legacy). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | TC card message text shown to the creator (max 500 chars). Different from messages[] (initial outreach DM addons) — this is the body on the invitation card itself. The portal rejects bodies containing the word amazon. Persists as config.TARGET_COLLAB_MESSAGE. |
| products | [TargetCollabProduct] | true | none | none |
| content_type | string | false | none | Content type preference for this TC. Translates to the legacy DB enum (No preference / Shoppable video / Shoppable LIVE) at the persistence boundary. |
| sample_policy | TargetCollabSamplePolicy | false | none | TC sample policy. Three modes from the portal: 1. Manual approval — offer_free_samples=False, auto_approve=False2. Free samples + manual approval — offer_free_samples=True, auto_approve=False3. Free samples + auto approval — offer_free_samples=True, auto_approve=Trueoffer_free_samples=False, auto_approve=True is also accepted butrare in prod (~0% — see audit 2026-05-01). |
| support_contact | any | false | none | Brand-side support contact shown on the TC card. Optional ONLY when this shop has a default configured via PUT /public/v1/target-collabs/support-contact-default (CORE-5428) — in that case it's used as the fallback. When provided here it overrides the shop default for this request. If neither is present the request is rejected with 422 SUPPORT_CONTACT_REQUIRED (the portal also rejects TC creates without a contact email). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollabContact | false | none | Brand-side contact info displayed on the TC card so the creator can reach the merchant with questions. email is required by theportal at TC create time; phone is optional. Persists at the legacyconfig root as EMAIL / PHONE_NUMBER. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| content_type | no_preference |
| content_type | shoppable_video |
| content_type | shoppable_live |
TargetCollabContact
{
"email": "string",
"phone": "string"
}
TargetCollabContact
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| string | true | none | Contact email shown to the creator on the TC card. | |
| phone | any | false | none | E.164 format recommended. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TargetCollabContactPatch
{
"email": "string",
"phone": "string"
}
TargetCollabContactPatch
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| phone | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TargetCollabDirectRequest
{
"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"
}
}
TargetCollabDirectRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | string | true | none | TikTok @-handle (without the @). Resolved server-side against this shop's CRM / affiliate list (a row in crm_creators for reacher_shop_id=<shop_id> whose creator_name matches the handle, ordered by GMV via a LEFT JOIN against the region's creator table). The creator must already have interacted with your shop — handles for creators who haven't applied / sampled / transacted yet will not resolve, even if the handle exists globally on TikTok. Unknown handle → 404 CREATOR_NOT_FOUND. |
| product_id | string | true | none | TikTok Shop product ID to attach to the invitation. |
| commission_rate | number | true | none | Affiliate commission rate (0.0-1.0, e.g. 0.20 for 20%). |
| shop_ads_commission_rate | any | false | none | Optional Shop Ads (co-funded) commission rate (0.0-1.0). When set, persists into the legacy PRODUCTS blob at the per-product level; the TC runtime fills the matching field on the TC form. Omit to leave unset (worker treats as not configured). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | string | true | none | TC card message body shown to the creator (max 500 chars). Mirrors target_collab.message on the full TC create surface — the portal rejects bodies containing the word amazon. |
| invitation_name | string | true | none | Name shown on the TC invitation card (max 30 chars). Same field as target_collab.invitation_name on the full TC create. |
| valid_until | any | false | none | Date the TC card stops being valid. Defaults to today + 30 days when omitted. After this date the dispatcher stops the underlying automation (see internal/queries/automations_to_run.py). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| support_contact | any | false | none | Brand-side support contact shown on the TC card. Optional ONLY when this shop has a default configured via PUT /public/v1/target-collabs/support-contact-default (CORE-5428) — in that case it's used as the fallback. When provided here it overrides the shop default for this request. If neither is present the request is rejected with 422 SUPPORT_CONTACT_REQUIRED. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollabDirectSupportContact | false | none | Brand-side support contact shown on the TC invitation card. MirrorsTargetCollabContact exactly — kept as a separate class so the directsurface's OpenAPI doesn't pull in the heavier automation-shape model name when callers only see this endpoint. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TargetCollabDirectResponse
{
"automation_id": 0,
"status": "string",
"creator_id": "string",
"creator_handle": "string",
"shop_id": 0,
"check_status_at": "string",
"queued_at": "string",
"dry_run": false
}
TargetCollabDirectResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| automation_id | integer | true | none | Underlying Automations.automation_id, for polling. |
| status | string | true | none | Always queued on success. The underlying automation is running immediately; the field name reflects delivery semantics (the TC invite itself is queued for the worker). |
| creator_id | string | true | none | Resolved creator_id for the supplied handle. |
| creator_handle | string | true | none | The handle echoed back (stripped of any leading @). |
| shop_id | integer | true | none | Shop the invite was created under. |
| check_status_at | string | true | none | Relative URL for polling automation state — /public/v1/automations/{automation_id}. |
| queued_at | string | true | none | ISO-8601 timestamp at which the start transition fired. |
| dry_run | boolean | false | none | True when X-Dry-Run was set — no automation row was created and no worker job was queued. automation_id is 0 and queued_at reflects the request time. |
TargetCollabDirectSupportContact
{
"email": "string",
"phone": "string"
}
TargetCollabDirectSupportContact
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| string | true | none | Contact email shown to the creator on the TC card. | |
| phone | any | false | none | E.164 format recommended. Normalized at persistence. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TargetCollabPatchPayload
{
"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
}
TargetCollabPatchPayload
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| invitation_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| valid_until | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| message | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| products | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [TargetCollabProduct] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| content_type | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sample_policy | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollabSamplePolicyPatch | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| support_contact | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | TargetCollabContactPatch | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| lock_receivers_profiles | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | no_preference |
| anonymous | shoppable_video |
| anonymous | shoppable_live |
TargetCollabProduct
{
"product_id": "string",
"commission_rate": 1,
"shop_min_commission": 1,
"shop_ads_commission_rate": 1
}
TargetCollabProduct
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | string | true | none | TikTok Shop product ID. |
| commission_rate | number | true | none | Affiliate commission rate (0.0-1.0, e.g. 0.20 for 20%). |
| shop_min_commission | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shop_ads_commission_rate | any | false | none | Optional Shop Ads (co-funded) commission rate (0.0-1.0). Persisted into the legacy PRODUCTS blob; the TC runtime fills it on the TC form when present. |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TargetCollabSamplePolicy
{
"offer_free_samples": false,
"auto_approve": false,
"send_to": "brand_recipient"
}
TargetCollabSamplePolicy
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| offer_free_samples | boolean | false | none | none |
| auto_approve | boolean | false | none | When true, accepted invites trigger immediate sample-request auto-approval without manual review. Maps to top-level config.AUTO_APPROVE. Per architecture review 2026-05-01. |
| send_to | string | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| send_to | brand_recipient |
| send_to | mall_recipient |
TargetCollabSamplePolicyPatch
{
"offer_free_samples": true,
"auto_approve": true,
"send_to": "brand_recipient"
}
TargetCollabSamplePolicyPatch
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| offer_free_samples | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| auto_approve | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | boolean | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| send_to | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | brand_recipient |
| anonymous | mall_recipient |
TargetCollaborationCardContent
{
"invitation_group_id": "string"
}
TargetCollaborationCardContent
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| invitation_group_id | string | true | none | none |
TcCampaignLink
{
"campaign_id": 0,
"campaign_name": "string"
}
TcCampaignLink
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_id | integer | true | none | none |
| campaign_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TcInvitationBatch
{
"sent_at": "string",
"status": "string",
"creator_count": 0,
"creators": [
"string"
],
"creators_truncated": false,
"expiration_date": "string"
}
TcInvitationBatch
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sent_at | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_count | integer | true | none | none |
| creators | [string] | false | none | none |
| creators_truncated | boolean | false | none | none |
| expiration_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TimeseriesDataPoint
{
"date": "string",
"value": 0
}
TimeseriesDataPoint
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| date | string | true | none | none |
| value | number | true | none | none |
TimeseriesRequest
{
"metrics": [
"gmv"
],
"start_date": "2019-08-24",
"end_date": "2019-08-24",
"granularity": "day"
}
TimeseriesRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| metrics | [string] | true | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| granularity | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | day |
| anonymous | week |
| anonymous | month |
TimeseriesResponse
{
"data": {
"property1": [
{
"date": "string",
"value": 0
}
],
"property2": [
{
"date": "string",
"value": 0
}
]
},
"granularity": "string",
"start_date": "string",
"end_date": "string",
"currency": "string",
"shops_queried": [
"string"
]
}
TimeseriesResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | object | true | none | none |
| » additionalProperties | [TimeseriesDataPoint] | false | none | none |
| granularity | string | true | none | none |
| start_date | string | true | none | none |
| end_date | string | true | none | none |
| currency | string | true | none | none |
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
TrackerVideosRequest
{
"campaign_creator_mapping_id": 0
}
TrackerVideosRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| campaign_creator_mapping_id | integer | true | none | none |
TrackerVideosResponse
{
"status": "success",
"data": [
{}
],
"count": 0
}
TrackerVideosResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | false | none | none |
| data | [object] | false | none | none |
| count | integer | false | none | none |
TriggerFrequency
"daily"
TriggerFrequency
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| TriggerFrequency | string | false | none | How often the automation evaluates its conditions. Only daily is honoured by the offline execution engine today; theportal FE submits this value exclusively. |
Enumerated Values
| Property | Value |
|---|---|
| TriggerFrequency | daily |
ValidationError
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
ValidationError
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| loc | [anyOf] | true | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| msg | string | true | none | none |
| type | string | true | none | none |
VideoContentResponse
{
"status": "success",
"data": [
{}
],
"count": 0
}
VideoContentResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| status | string | false | none | none |
| data | [object] | false | none | none |
| count | integer | false | none | none |
VideoCreativeBreakdown
{
"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"
]
}
VideoCreativeBreakdown
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| analyzed | boolean | true | none | none |
| hook | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | VideoCreativeHook | false | none | Opening-seconds angle of the video. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sell_points | any | false | none | Key selling points the video leans on |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_niche | any | false | none | Product category leaf from the catalog, falling back to the content-angle tag |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shot_style | any | false | none | How the video is framed and composed |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videography | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | VideoCreativeVideography | false | none | Camera work, setting, and presentation patterns. |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| missing_fields | [string] | false | none | none |
VideoCreativeHook
{
"text": "string",
"classification": "string",
"reasoning": "string"
}
VideoCreativeHook
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| text | any | false | none | The hook line as spoken/shown |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| classification | any | false | none | Hook type, e.g. problem-solution, curiosity |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| reasoning | any | false | none | Why the analysis classified it this way |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideoCreativeItem
{
"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"
]
}
}
VideoCreativeItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_id | string | true | none | none |
| title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_gmv | any | false | none | GMV earned in the date range (not lifetime) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| views | any | false | none | Views in the date range (not lifetime) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| like_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| comment_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| posted_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| rank | integer | true | none | none |
| creative | VideoCreativeBreakdown | true | none | AI creative analysis of the video (customers.video_analysis). Not every video has been analyzed — when analyzed is false, or whenindividual fields are null, missing_fields names the gaps so clientscan render "not analyzed" instead of blanks. |
VideoCreativeVideography
{
"locations": [
"string"
],
"lighting": [
"string"
],
"product_showcase": [
"string"
],
"notes": "string"
}
VideoCreativeVideography
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| locations | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| lighting | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_showcase | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| notes | any | false | none | Free-text videography notes (older analyses store prose instead of structured fields) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideoItem
{
"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"
}
VideoItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_id | string | true | none | none |
| title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_url | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_name | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| like_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| comment_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| share_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| units_sold | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| posted_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideoPerformanceItem
{
"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"
}
VideoPerformanceItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_id | string | true | none | none |
| title | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_gmv | any | false | none | GMV earned in the date range (not lifetime) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| views | any | false | none | Views in the date range (not lifetime) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| like_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| comment_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| order_count | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| posted_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideoPerformanceRequest
{
"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
}
VideoPerformanceRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | video_gmv |
| anonymous | views |
| anonymous | like_count |
| anonymous | order_count |
| anonymous | posted_date |
| sort_dir | asc |
| sort_dir | desc |
VideoPerformanceResponse
{
"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"
]
}
VideoPerformanceResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [VideoPerformanceItem] | true | none | [Video with period-specific metrics from video_info (daily table).] |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideosCreativeCoverage
{
"videos_returned": 0,
"with_creative_analysis": 0
}
VideosCreativeCoverage
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| videos_returned | integer | true | none | none |
| with_creative_analysis | integer | true | none | none |
VideosCreativeRequest
{
"limit": 10,
"sort_by": "video_gmv",
"sort_dir": "asc",
"start_date": "2019-08-24",
"end_date": "2019-08-24"
}
VideosCreativeRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| limit | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | video_gmv |
| anonymous | views |
| anonymous | like_count |
| anonymous | order_count |
| anonymous | posted_date |
| sort_dir | asc |
| sort_dir | desc |
VideosCreativeResponse
{
"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"
]
}
VideosCreativeResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [VideoCreativeItem] | true | none | [Video performance row enriched with the creative breakdown.] |
| currency | string | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| coverage | VideosCreativeCoverage | true | none | none |
| total_count | integer | true | none | Total videos with performance data in the window (not just the top N) |
| message | any | false | none | Set when there are no videos in the window (explicit empty state) |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideosListPaginatedResponse
{
"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"
]
}
VideosListPaginatedResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| data | [VideoItem] | true | none | none |
| currency | string | true | none | none |
| pagination | any | true | none | none |
| date_range | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | DateRange | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| shops_queried | any | false | none | Shop names included when querying multiple shops (x-shop-id: all or comma-separated). |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | [string] | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
VideosListRequest
{
"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
}
VideosListRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| page | integer | false | none | none |
| page_size | integer | false | none | none |
| sort_by | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| sort_dir | string | false | none | none |
| start_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| end_date | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string(date) | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| creator_handle | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| product_id | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | string | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_gmv | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | number | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
continued
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| min_views | any | false | none | none |
anyOf
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | integer | false | none | none |
or
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| » anonymous | null | false | none | none |
Enumerated Values
| Property | Value |
|---|---|
| anonymous | video_gmv |
| anonymous | views |
| anonymous | units_sold |
| anonymous | posted_date |
| anonymous | like_count |
| sort_dir | asc |
| sort_dir | desc |
ViewVideoContentRequest
{
"video_id": "string"
}
ViewVideoContentRequest
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| video_id | string | true | none | none |
WeightableMetric
"gmv"
WeightableMetric
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| WeightableMetric | string | false | none | Video metrics that can carry a weight in a weighted leaderboard. |
Enumerated Values
| Property | Value |
|---|---|
| WeightableMetric | gmv |
| WeightableMetric | avg_views_per_post |
| WeightableMetric | views |
| WeightableMetric | videos_posted |
| WeightableMetric | units_sold |
WeightedMetricItem
{
"metric_type": "gmv",
"weight": 100
}
WeightedMetricItem
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| metric_type | WeightableMetric | true | none | Video metrics that can carry a weight in a weighted leaderboard. |
| weight | integer | true | none | none |
WriteErrorResponse
{
"error": {}
}
WriteErrorResponse
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| error | object | true | none | none |