---
title: "Create segment"
method: POST
path: "/api/v1/user/segments"
tags: ["User"]
---

# Create segment

`POST /api/v1/user/segments`

Create a tier-limited saved corporate segment. At least one effective UserSegmentFilters anchor is required. Unknown fields and legacy forma/estado filters are rejected with 400; an individually valid but unindexed combination is rejected with 422.

## Headers

- `X-CSRF-Token` string, required

## Request body

- UserSegmentCreateRequest
  - `name` string, required
  - `description` string
  - `filters` UserSegmentFilters, required — Corporate-only filters executed exclusively over the immutable company_public_v2 sidecar. At least one effective anchor is required: provincia, cnae_prefix, a capital bound, a year bound or recent_days. `forma` and `estado` are deliberately not accepted; stored legacy filters containing either fail closed. Without provincia/cnae_prefix, capital and temporal anchors cannot be combined; capital-only anchors accept only capital_desc/capital_asc (or the default), and temporal-only anchors accept only recent/oldest (or the default).
    - `provincia` string — Canonical Spanish province name or supported alias; matched exactly after normalization.
    - `cnae_prefix` string
    - `capital_min` integer — Euros. Must not exceed capital_max when both are present.
    - `capital_max` integer — Euros. Must be greater than or equal to capital_min when both are present.
    - `year_min` integer — Inclusive year of the first documentary record; must not exceed year_max.
    - `year_max` integer — Inclusive year of the first documentary record; must be greater than or equal to year_min.
    - `recent_days` integer — First documentary record within this rolling number of days.
    - `sort` 'capital_desc' | 'capital_asc' | 'acts_desc' | 'oldest' | 'recent' — Indexed ordering. The accepted value depends on the effective anchor as documented in x-rejected-combinations.
  - `persona` string, nullable
  - `icon` string, nullable
  - `pinned` boolean

## Response `201`

Created

- UserSegmentCreatedResponse
  - `id` integer, required
  - `segment` UserSegment, required — Saved account segment. Extra migration columns may be returned for backward compatibility.
    - `id` integer
    - `user_id` integer
    - `name` string
    - `description` string
    - `filters_json` string
    - `filters` UserSegmentStoredFilters — Read-only decoded filters_json from an existing segment. New writes must use UserSegmentFilters. Historic records may still contain removed keys such as forma or estado; clients must present them as unavailable and execution fails closed rather than ignoring them.
    - `persona` string, nullable
    - `icon` string, nullable
    - `pinned` union
      - integer
      - boolean
    - `created_at` string
    - `updated_at` string

## Other responses

- `400` — Malformed/unknown filter, legally unavailable legacy filter, missing effective anchor or tier limit
- `401` — Authentication required (no active session)
- `422` — Individually valid filters do not have a safe indexed combination

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/versions/996f96a11758/schema)