# API : segments

3 opérations REST du groupe segments.

Base : `/api/v1`. [Conventions](/documentation/api-conventions/) · [Toutes les ressources](/documentation/api-reference/)

- GET /segments : Lister les segments (hors archivés)
- POST /segments : Créer un segment
- GET /segments/{id}/members : Les membres d'un segment (contacts), paginés
## GET /segments

```json
{
  "summary": "Lister les segments (hors archivés)",
  "tags": [
    "Marketing"
  ],
  "parameters": [
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Curseur opaque de la page précédente",
        "type": "string"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Taille de page - défaut 50, max 200 (clampé)",
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    },
    {
      "name": "updatedSince",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "ISO 8601 - objets modifiés depuis (inclusif), le filtre des syncs incrémentales",
        "type": "string"
      }
    },
    {
      "name": "archived",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "boolean"
      }
    }
  ],
  "security": [
    {
      "oauth2": [
        "marketing:read"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Page de segments",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "name": {
                      "type": "string"
                    },
                    "kind": {
                      "type": "string",
                      "enum": [
                        "dynamic",
                        "static"
                      ]
                    },
                    "object": {
                      "type": "string",
                      "enum": [
                        "contact",
                        "company"
                      ]
                    },
                    "memberCount": {
                      "type": "integer",
                      "minimum": -9007199254740991,
                      "maximum": 9007199254740991
                    },
                    "computedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "definition": {
                      "type": "object",
                      "properties": {},
                      "additionalProperties": {},
                      "description": "Définition (contactable, all, anyGroups) : le même schéma que l'écran Segments"
                    },
                    "archivedAt": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time",
                          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "kind",
                    "object",
                    "memberCount",
                    "computedAt",
                    "definition",
                    "archivedAt",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "data",
              "nextCursor"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```

## POST /segments

```json
{
  "summary": "Créer un segment",
  "description": "Dynamique : la définition est validée et compilée par le même code que l'écran Segments (422 sur un champ inconnu). Quota `segments` du plan (429).",
  "tags": [
    "Marketing"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "kind": {
              "type": "string",
              "enum": [
                "dynamic",
                "static"
              ]
            },
            "object": {
              "description": "Défaut : contact",
              "type": "string",
              "enum": [
                "contact",
                "company"
              ]
            },
            "definition": {
              "description": "Dynamique : critères validés et compilés comme dans l'UI (422 sinon)",
              "type": "object",
              "properties": {
                "contactable": {
                  "default": true,
                  "type": "boolean"
                },
                "all": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "object": {
                        "type": "string",
                        "enum": [
                          "contact",
                          "company",
                          "affiliation",
                          "quote",
                          "order",
                          "contract",
                          "invoice",
                          "sales_activity",
                          "marketing_consent",
                          "marketing_delivery",
                          "event_invitation",
                          "marketing_touch",
                          "tag"
                        ]
                      },
                      "field": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      },
                      "op": {
                        "type": "string",
                        "enum": [
                          "is",
                          "is_not",
                          "contains",
                          "gt",
                          "lt",
                          "between",
                          "in",
                          "empty",
                          "not_empty",
                          "within_days",
                          "older_than_days"
                        ]
                      },
                      "value": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 200
                          },
                          {
                            "type": "number"
                          },
                          {
                            "type": "boolean"
                          },
                          {
                            "maxItems": 50,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 200
                            }
                          }
                        ]
                      },
                      "not": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "object",
                      "field",
                      "op"
                    ]
                  }
                },
                "anyGroups": {
                  "default": [],
                  "maxItems": 5,
                  "type": "array",
                  "items": {
                    "minItems": 1,
                    "maxItems": 10,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "object": {
                          "type": "string",
                          "enum": [
                            "contact",
                            "company",
                            "affiliation",
                            "quote",
                            "order",
                            "contract",
                            "invoice",
                            "sales_activity",
                            "marketing_consent",
                            "marketing_delivery",
                            "event_invitation",
                            "marketing_touch",
                            "tag"
                          ]
                        },
                        "field": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 64
                        },
                        "op": {
                          "type": "string",
                          "enum": [
                            "is",
                            "is_not",
                            "contains",
                            "gt",
                            "lt",
                            "between",
                            "in",
                            "empty",
                            "not_empty",
                            "within_days",
                            "older_than_days"
                          ]
                        },
                        "value": {
                          "anyOf": [
                            {
                              "type": "string",
                              "maxLength": 200
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean"
                            },
                            {
                              "maxItems": 50,
                              "type": "array",
                              "items": {
                                "type": "string",
                                "maxLength": 200
                              }
                            }
                          ]
                        },
                        "not": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "object",
                        "field",
                        "op"
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": [
            "name",
            "kind"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "marketing:write"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "201": {
      "description": "Segment créé",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
              },
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "dynamic",
                  "static"
                ]
              },
              "object": {
                "type": "string",
                "enum": [
                  "contact",
                  "company"
                ]
              },
              "memberCount": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              "computedAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "definition": {
                "type": "object",
                "properties": {},
                "additionalProperties": {},
                "description": "Définition (contactable, all, anyGroups) : le même schéma que l'écran Segments"
              },
              "archivedAt": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              }
            },
            "required": [
              "id",
              "name",
              "kind",
              "object",
              "memberCount",
              "computedAt",
              "definition",
              "archivedAt",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```

## GET /segments/{id}/members

```json
{
  "summary": "Les membres d'un segment (contacts), paginés",
  "description": "Statique : les membres figés ; dynamique : compilé à l'instant. Les contacts hors visibilité du jeton (périmètre) ne sont pas rendus.",
  "tags": [
    "Marketing"
  ],
  "parameters": [
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Curseur opaque de la page précédente",
        "type": "string"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "description": "Taille de page - défaut 50, max 200 (clampé)",
        "type": "integer",
        "minimum": 1,
        "maximum": 9007199254740991
      }
    }
  ],
  "security": [
    {
      "oauth2": [
        "marketing:read",
        "contacts:read"
      ]
    },
    {
      "userSession": []
    }
  ],
  "responses": {
    "200": {
      "description": "Page de contacts",
      "content": {
        "application/json": {
          "schema": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                    },
                    "salutation": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "mr",
                            "mrs"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "email": {
                      "description": "Adresse PRINCIPALE du contact (T-809 : multi-emails - la fiche peut porter d'autres adresses, ce champ reste le miroir de la principale).",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "phone": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "title": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "avatar": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "linkedin": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "birthday": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date",
                          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Date de naissance « YYYY-MM-DD », null = inconnue"
                    },
                    "timeZone": {
                      "description": "Fuseau IANA explicitement connu ; null = inconnu, jamais déduit du pays",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "addressLine1": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "addressLine2": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "postalCode": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "city": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "country": {
                      "description": "Code pays ISO 3166-1 alpha-2",
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "customFields": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": [
                          "string",
                          "number",
                          "boolean"
                        ]
                      }
                    },
                    "doNotContact": {
                      "type": "boolean",
                      "description": "Opposition RGPD : le contact ne doit pas être sollicité (E183 #514, badge « Ne pas contacter » à côté de l'email)"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                    },
                    "externalRefs": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "source": {
                            "type": "string",
                            "description": "Système source (minuscules) - `tacto`, `erp`…"
                          },
                          "externalId": {
                            "type": "string"
                          },
                          "sourceUpdatedAt": {
                            "anyOf": [
                              {
                                "type": "string",
                                "format": "date-time",
                                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Dernière modification connue dans la source (curseur du delta), null si inconnue"
                          }
                        },
                        "required": [
                          "source",
                          "externalId",
                          "sourceUpdatedAt"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Identifiants de cet objet dans les systèmes tiers (external_ref, ADR-138 D1, ADR-156 D6)"
                    }
                  },
                  "required": [
                    "id",
                    "salutation",
                    "firstName",
                    "lastName",
                    "email",
                    "phone",
                    "title",
                    "avatar",
                    "linkedin",
                    "birthday",
                    "timeZone",
                    "addressLine1",
                    "addressLine2",
                    "postalCode",
                    "city",
                    "country",
                    "customFields",
                    "doNotContact",
                    "createdAt",
                    "updatedAt"
                  ],
                  "additionalProperties": false
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "data",
              "nextCursor"
            ],
            "additionalProperties": false
          }
        }
      }
    },
    "default": {
      "description": "Erreur - enveloppe problem+json (RFC 9457)",
      "content": {
        "application/problem+json": {
          "schema": {
            "$ref": "#/components/schemas/Problem"
          }
        }
      }
    }
  }
}
```