---
title: "List the CRM creator roster"
method: GET
path: "/crm/creators"
tags: ["CRM Roster"]
---

# List the CRM creator roster

`GET /crm/creators`

The shop's My Creators table: one row per creator (the most recently updated of their creator × product records), carrying the sample / content lifecycle `status`, lifetime and 28-day GMV, commission, fulfillment, video and live counts, and CRM `tags`.

Filter with any combination of `status` (repeatable display labels), `stage` (a canonical funnel stage, which overrides `status`), `product_id`, `tags` (creator carries ANY) and `tags_all` (carries ALL), plus `creator_handle` for a case-insensitive handle search. Sort with `sort_by` / `sort_dir`; the default is GMV descending.

`start_date`/`end_date` window the *metric* columns (`video_gmv`, `total_video_views`, `videos_posted`) — pass both or neither. Status, tags and lifetime `gmv` are always as-of-now.

Set `include_products=true` to attach each creator's product cards (title, image, status, remaining sample stock). Per-product GMV and the videos themselves are deliberately not attached — they are the two heaviest reads in this surface; fetch them per creator from GET /crm/content.

Single-shop only. Creator contact details are never returned: no real name, shipping address, phone or email. `creator_name` is the public TikTok handle.

## Query parameters

- `page` integer — 1-based page number.
- `page_size` integer — Rows per page (max 100).
- `status` string[], nullable — Repeatable status label. One of: ['Sample Requested', 'Sample Approved', 'Ready to Ship', 'Sample Shipped', 'Content Pending', 'Completed', 'Sample Request Rejected', 'Sample Request Expired', 'Content Unfulfilled', 'Idle', 'Posted Video', 'Sold Products', 'GMV Generated', 'Showcasing Product', 'Livestreamed'].
- `stage` string, nullable — Canonical funnel stage id; overrides `status` with that stage's label set. One of: ['sample-requests', 'sample-requested', 'approved-samples', 'sample-approved', 'content-pending', 'content-unfulfilled', 'content-posted', 'generated-gmv', 'gmv-generated'].
- `product_id` string, nullable — Restrict to one product.
- `tags` string[], nullable — Repeatable. Creators carrying ANY of these CRM tags.
- `tags_all` string[], nullable — Repeatable. Creators carrying ALL of these CRM tags.
- `creator_handle` string, nullable — Case-insensitive substring search on the TikTok handle.
- `sort_by` string, nullable — Sort column. One of: ['video_num', 'live_num', 'fulfillment_rate', 'gmv', 'video_release_date', 'creator_gmv', 'follower_num', 'video_gmv', 'total_video_views', 'videos_posted', 'avg_views', 'affiliate_gmv_28d', 'units_sold', 'commission'].
- `sort_dir` 'asc' | 'desc' — Sort direction.
- `start_date` string, date, nullable — Start of the metric window. Requires end_date.
- `end_date` string, date, nullable — End of the metric window. Requires start_date.
- `include_products` boolean — Attach each creator's product cards.

## Response `200`

Successful Response

- CrmRosterResponse
  - `data` CrmRosterCreator[], required
    - `id` string, nullable — CRM row id — `{creator_id}-{product_id}-{shop_id}`.
    - `creator_id` string, nullable
    - `creator_name` string, nullable — Public TikTok handle. Never the creator's real name.
    - `avatar_url` string, nullable
    - `follower_num` integer, nullable
    - `tags` string[], nullable
    - `bio` string, nullable — The creator's TikTok profile bio/signature text. Null when not scraped for this creator.
    - `categories` string[], nullable — Broad TikTok Shop product categories the creator has sold across (the whole set, not a single niche/content label).
    - `curr_status` string, nullable — Sample/collaboration status as a display label (e.g. `Content Pending`) — the upstream roster already resolves the raw TikTok code before it reaches this surface.
    - `status` string, nullable — Alias of `curr_status`, kept for caller convenience.
    - `expired_in` integer, nullable
    - `fulfillment_status` integer, nullable
    - `fulfillment_rate` number, nullable
    - `sample_received_num` integer, nullable
    - `product_id` string, nullable
    - `product_title` string, nullable
    - `sku_id` string, nullable
    - `sku_left_num` integer, nullable
    - `gmv` number, nullable — Lifetime GMV this creator drove for this shop.
    - `creator_gmv` number, nullable — The creator's total GMV across all shops.
    - `video_gmv` number, nullable
    - `affiliate_gmv_28d` number, nullable — Trailing-28-day affiliate GMV. Null when the shop has no affiliate ledger — deliberately not zero-filled.
    - `refund_gmv` number, nullable
    - `commission` number, nullable
    - `commission_rate` number, nullable
    - `estimate_commission` number, nullable
    - `units_sold` integer, nullable
    - `item_sold` integer, nullable
    - `refund_item_sold` integer, nullable
    - `product_sold` integer, nullable
    - `video_num` integer, nullable
    - `live_num` integer, nullable
    - `videos_posted` integer, nullable
    - `total_video_views` integer, nullable
    - `content_video_views` integer, nullable
    - `avg_views` integer, nullable
    - `engagement_rate` number, nullable
    - `video_release_date` string, date-time, nullable
    - `video_url` string, nullable
    - `updated_at` string, date-time, nullable
    - `products` CrmRosterProduct[], nullable
      - `product_id` string, required
      - `product_title` string, nullable
      - `sku_image` string, nullable
      - `status` string, nullable — Display status label for this creator × product.
      - `requested_date` string, nullable
      - `expires_in` integer, nullable
      - `quantity` integer, nullable — Remaining sample stock for the SKU (`sku_left_num`).
  - `pagination` PublicApiCorePaginationPaginationMeta, required — Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)