This API is used by Sellers to search for Creators in the Creator Marketplace. Sellers can search based on filters such as GMV, keywords, and Creator follower demographics. All the data returned is for the last 30 days.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Identifies the shop. Obtain it from the Get Authorized Shops API.
Pagination token that identifies where to continue the search. For the first request, omit this parameter or leave it empty. For each subsequent request, pass the next_page_token returned by the previous response.
The value of “page_size” must be 12 or 20
Request Body
Section titled “Request Body”object
Caching search results improves api performance and ensures stable request results. You don’t need to pass a value on the first call. For the second call, please pass the value returned in the response of the first call.
Searching creators by keyword, matching based on TikTok Username and Nickname.
Filtering creators by follower demographics
object
Follower age filtering options, which are range intervals, include: AGE_RANGE_18_24: “18-24”, AGE_RANGE_25_34: “25-34”, AGE_RANGE_35_44: “35-44”, AGE_RANGE_45_54: “45-54”, AGE_RANGE_55_AND_ABOVE: “55+”
Follower count filtering
object
The minimum value of follower count. The value passed in must be greater than or equal to 0
The maximum value of follower count.
- Generally, a value greater than or equal to 0 needs to be passed. If a value less than 0 is passed, it means that the field will not be filtered.
Filters creators by follower gender. Possible values:
- MALE
- FEMALE
object
A particular gender, “MALE” or “FEMALE”
Greater than or equal to a certain percentage, scaled up by 10,000 times. For example, 6000 stands for 0.6 or 60%
Filtering by GMV range intervals which include: GMV_RANGE_0_100: “0-100”, GMV_RANGE_100_1000: “100-1000”, GMV_RANGE_1000_10000: “1000-10000”, GMV_RANGE_10000_AND_ABOVE: “10000+” For example:
- If GMV_RANGE_0_100 is passed, it means filtering the creator data that is greater than or equal to 0 and less than or equal to 100.
- If GMV_RANGE_0_100 and GMV_RANGE_100_1000 are passed, it means to filter the creator data that is greater than or equal to 0 and less than or equal to 1000.
Filtering by sales volume range intervals which include: UNITS_SOLD_RANGE_0_10: “0-10”, UNITS_SOLD_RANGE_10_100: “10-100”, UNITS_SOLD_RANGE_100_1000: “100-1000”, UNITS_SOLD_RANGE_1000_AND_ABOVE: “1000+” For example:
- If UNITS_SOLD_RANGE_0_10 is passed, it means filtering the creator data that is greater than or equal to 0 and less than or equal to 10.
- If UNITS_SOLD_RANGE_0_10 and UNITS_SOLD_RANGE_10_100 are passed, it means to filter the creator data that is greater than or equal to 0 and less than or equal to 100.
Array of category filter objects. Use Get Categories to retrieve category IDs.
object
Category of the parent category. If you are only using a parent category, you do not need to pass in a child category ID.
If you are using the category ID for a child category, you must pass the parent category as well. A child category is only 1 level deeper than the parent category. We do not support going deeper down the category tree (some countries have 4 levels, others have 7)
Object containing content performance filters
object
Average Video Views more than You can pass in average video views anywhere between 0 and 100k Pick any whole number between 0 and 100,000, and we will return all results with average video views greater than that number. You can only pass in Average Video Views OR Average Shoppable Video Views. Using both filters will cause the API call to fail.
You can pass in average shoppable video views anywhere between 0 and 100k Pick any whole number between 0 and 100,000, and we will return all results with average shoppable video views greater than that number. You can only pass in Average Video Views OR Average Shoppable Video Views. Using both filters will cause the API call to fail.
Average engagement rate more than 0-20. You can only filter by increments of 1% point, up to 20%.
Average shoppable engagement rate more than 0-20. You can only filter by increments of 1% point, up to 20%.
Filters creators whose average LIVE viewers are greater than or equal to the specified value. Enter a whole number from 0 to 100,000. You can only pass one of avg_live_avg_viewers_ge and avg_shoppable_live_avg_viewers_ge. Using both filters causes the API call to fail.
Filters creators whose average shoppable LIVE viewers are greater than or equal to the specified value. Enter a whole number from 0 to 100,000. You can only pass one of avg_live_avg_viewers_ge and avg_shoppable_live_avg_viewers_ge. Using both filters causes the API call to fail.
Object which contains affiliate based data
object
- ALL
- LESS_THAN_20%
- LESS_THAN_15%
- LESS_THAN_10%
- LESS_THAN_5% Creator’s average commission rate range based on showcase products, sales, and promoted products in the last 30 days. You can only pick one value.
These categories represent how often a creator posts a shoppable video or LIVE after receiving a sample.
- ALL
- OK
- GOOD
- BETTER Every country has its own benchmark based on what is a GOOD vs BETTER fulfillment rate. BETTER is always going to have the highest fulfillment rate, including 100% fulfillment rate.
- AGENCY_MANAGED
- INDEPENDENT
Top 10% of creators with the greatest increase in transactions, revenue, shoppable videos, live views, or followers in the last 30 days
True/False Select this filter to see creators you haven’t invited in the last 90 days
Advanced filters are specific to each country. Before using advanced filters with this API, use Get Seller Search Creator Marketplace Advanced Filters to retrieve the filters available for the relevant country.
object
Content preference type. e.g. -VIDEO -LIVE
Creator is eligible for flat fee invitation, only available in US local seller
Creator Marketplace Advanced Filter Option List. Please use “Get Seller Search Creator Marketplace Advanced Filters”(https://partner.tiktokshop.com/docv2/page/get-seller-search-creator-marketplace-advanced-filters) get available options for you first
object
Options in this option type
object
Option id
The option name.
Children option detail list, used if the option has sub option choices
object
Children Option id
Children Option name
Option type
Sorter algorithm id. Please use “Get Seller Search Creator Marketplace Advanced Filters”(https://partner.tiktokshop.com/docv2/page/get-seller-search-creator-marketplace-advanced-filters) get available sorter algorithm for you first. Default is 1(default sorter)
Creator’s Data Group, get all group by default, which include:
- BASIC_CREATOR_INFORMATION
- CONTENT_PERFORMANCE
- FOLLOWER_INFORMATION
- COLLABORATION
- SALES_AND_GMV
Example
{ "search_key": "2E+0EcXoSk2HWdEWh2nITfkBRMbwuug0mt9s3fWgV0k=", "keyword": "JefreeStar", "follower_demographics": { "age_ranges": [ "AGE_RANGE_18_24", "AGE_RANGE_35_44" ], "count_range": { "count_ge": 1000, "count_le": 10000 }, "gender_distribution": { "gender": "MALE", "percentage_ge": 6000 } }, "gmv_ranges": [ "GMV_RANGE_0_100", "GMV_RANGE_100_1000" ], "units_sold_ranges": [ "UNITS_SOLD_RANGE_0_10", "UNITS_SOLD_RANGE_100_1000", "UNITS_SOLD_RANGE_1000_AND_ABOVE" ], "category": [ { "parent_category_id": "600001", "child_category_id_list": [ "851848" ] } ], "content_performance": { "avg_video_views": "1", "avg_shoppable_video_views": "1", "avg_engagement_rate": "1", "avg_shopable_engagement_rate": "1", "avg_live_avg_viewers_ge": "1", "avg_shoppable_live_avg_viewers_ge": "1" }, "affiliate_data": { "avg_commission_rate": "LESS_THAN_20%", "post_rate": "GOOD", "creator_agency_staus": "AGENCY_MANAGED", "is_fast_growing": false, "not_invited_l90_days": false }, "advanced_filters": { "content_preference_type": [ "VIDEO" ], "eligible_flat_fee": false, "option_list": [ { "options": [ { "id": "1", "name": "English", "option_children": [ { "id": "2", "name": "SubTypeName" } ] } ], "option_type": "OPTION_LANGUAGE" } ], "sorter_algorithm_id": "1" }, "data_groups": [ "BASIC_CREATOR_INFORMATION", "SALES_AND_GMV" ]}Responses
Section titled “Responses”Success
object
Status code; 0 means success.
Success or failure message.
Request log ID.
object
Pagination token for the next page. To continue, pass this value as query parameter page_token, pass the search_key returned in the same response as request-body search_key, and reuse the same page_size. An empty token means there are no more results.
Search key for continuing the same search with stable results. Pass this value as search_key in the next request.
Creator records with basic profile, content performance, follower, GMV, and sales-range information. Included fields depend on the requested data_groups.
object
Creator’s TikTok Username
Creator’s TikTok Nickname
Creator’s profile picture
object
The URL for the creator’s TikTok profile avatar.
Regions where the creator operates and promotes products
It indicates the main product categories when the creator posts products.
Average UV for creator’s e-commerce live streams
Average views for creator’s e-commerce videos
Follower count
Creator GMV-related information If the creator does not authorize sharing precise data, this will be omitted.
object
The ISO 4217 currency code for the GMV amount.
The amount of GMV
Live stream GMV If the creator does not authorize sharing precise data, this will be omitted.
object
The currency code.
Total livestream GMV associated with the creator.
Video GMV-related information If the creator does not authorize sharing precise data, this will be omitted.
object
The currency code.
The total video GMV associated with the creator.
GMV range. Applicable if the target market is the US and the creator does not authorize sharing precise data.
object
The currency code.
The lowest GMV value.
The highest GMV value.
The formatted range of GMV values associated with this creator.
The range of minimum number of units sold to maximum number of units sold over the lifetime of the creator account. Note that this property is included if the target market is US only. Note that if the creator has not given permission for precise data sharing, these properties will not be present.
object
The lowest number of units sold.
The highest number of units sold.
The formatted range of minimum number of units sold to maximum number of units sold over the lifetime of the creator account.
Top follower information of the creator
object
Return the top 3 age ranges of the followers. Ranges are : AGE_RANGE_18_24: “18-24”, AGE_RANGE_25_34: “25-34”, AGE_RANGE_35_44: “35-44”, AGE_RANGE_45_54: “45-54”, AGE_RANGE_55_AND_ABOVE: “55+”
Major gender of the followers
object
Top follower gender category of the creator, “MALE” or “FEMALE”
Percentage of top follower gender, scaled up by 10,000 times. For example, 6524 stands for 0.6524 or 65.24%. You can then infer that the opposite gender would be 0.3476 or 34.76%.
Creator Open ID. More details
Advanced creator profile information. An empty object means that this profile information is not currently supported for your account or region.
object
Creator has official recommend tag or not
Creator bind MCN name
Creator has fast growing tag or not
Has collaborated with this creator or not
User type tag. Possible values:
- 1: Privacy creator
- 2: Carve-out creator
Has invited creaor before 90 days
Is this creator blocked by shop or not
Creator promotion performance score(PPS).The score reflects the quality of a creator’s shoppable content and product selection over the past 30 days. A high score may indicate a better shopping experience, with fewer potential refunds or negative reviews. e.g. 4.3/5.0
Is creator eligible for flat fee, only available for US local seller
Creator has rising star tag or not
Creator level
Example
{ "code": 0, "data": { "next_page_token": "b2Zmc2V0PTEy", "search_key": "k1ChOzI9e+j5BHHHEnt+VhItjVFEkPUCCXNsrU8/v4U=", "creators": [ { "username": "abc", "nickname": "cde", "avatar": { "url": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp?lk3s=a5d48078&x-expires=1712988000&x-signature=E8US22KfUCwKz0R%2FMFF6%2FMOmogs%3D" }, "selection_region": "GB", "category_ids": [ "60001" ], "avg_ec_live_uv": 1331, "avg_ec_video_view_count": 112, "follower_count": 23241, "gmv": { "currency": "USD", "amount": "1232.90" }, "live_gmv": { "currency": "USD", "amount": "0.34" }, "video_gmv": { "currency": "USD", "amount": "23.34" }, "gmv_range": { "currency": "USD", "minimum_amount": "0", "maximum_amount": "100", "formatted_range": "$0-$100" }, "units_sold_range": { "minimum_amount": 100, "maximum_amount": 1000, "formatted_range": "100-1K" }, "top_follower_demographics": { "age_ranges": [ "AGE_RANGE_18_24", "AGE_RANGE_25_34" ], "major_gender": { "gender": "FEMALE", "percentage": 6524 } }, "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "creator_profile": { "is_official_recommend": false, "creator_bind_mcn_name": "name", "is_fast_growing": false, "has_collaborated": false, "user_type_tag": [ 1 ], "has_invited_90d": false, "is_creator_blocked": false, "pps_score": "4.3", "is_eligible_flat_fee": false, "is_rising_star": false, "creator_level": 2 } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7"}