---
title: "Create a CRM Group from a dashboard segment"
method: POST
path: "/crm-groups/from-segment"
tags: ["CRM Groups"]
---

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

## Headers

- `Idempotency-Key` string, nullable
- `X-Dry-Run` string, nullable

## Request body

- CrmGroupFromSegmentRequest — POST /crm-groups/from-segment request body.
  - `group_name` string, required — Name for the new group. Creation upserts by (shop, group_name) — reusing a name overwrites that group's definition and re-materializes its members.
  - `tier` string, nullable — GMV tier code to narrow the segment, e.g. 'L3'. Omit for all tiers.
  - `automation_id` integer, nullable — Restrict the segment to creators reached by this automation.
  - `start_date` string, date, nullable — Segment window start (inclusive).
  - `end_date` string, date, nullable — Segment window end (inclusive).
  - `group_tags` string[], nullable — Optional tags to attach to the group.

## Response `200`

Dry-run result (X-Dry-Run: true). Nothing was written.

- CrmGroupFromSegmentResponse
  - `data` CrmGroupFromSegmentResult, required
    - `crm_group_id` string, nullable — UUID of the created group. Null on a dry run.
    - `name` string, required
    - `creator_count` integer, required — Creators actually materialized into the group — those that mapped to a CRM record. This is the group's real size.
    - `handles_resolved` integer, required — 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[]
  - `dry_run` boolean, nullable

## Other responses

- `201` — Successful Response
- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests
- `500` — Internal Server 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/d4fe3e380424/schema)