> ## Documentation Index
> Fetch the complete documentation index at: https://docs.permutive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segment User

> This endpoint accepts a list of events for a given user and combines them with any pre-existing state for the user to determine the full list of cohorts of which they are a member. State is also persisted, to be applied to subsequent requests for the same user.

Events provided to this endpoint are published to the Permutive Events API, meaning that they will be reflected in other areas of Permutive, for example Insights.


<Info>
  This endpoint persists user state, which will be used in subsequent requests for the same user.
</Info>

## User Identification

You must provide exactly one of the following to identify the user:

* `user_id`: The Permutive User ID (UUID)
* `alias`: A single custom alias with `tag` and `id`
* `aliases`: A list of prioritized aliases, each with `priority`, `tag`, and `id`

## Events

Events should match the schema defined in your Permutive workspace. Each event requires:

* `name`: The event name (e.g., "Pageview")
* `time`: ISO 8601 timestamp
* `properties`: Event properties as a JSON object

Optional fields:

* `view_id`: UUID to group events within a single page view
* `session_id`: UUID to group events within a session

## Response

The response includes:

* `user_id`: The Permutive User ID
* `cohorts`: List of cohort IDs the user is currently a member of
* `activations`: (Optional) Map of activation platform to cohort IDs, if `activations=true` was set

## Example Usage

```bash theme={"dark"}
curl -X POST "https://api.permutive.app/ccs/v1/segmentation?k=YOUR_API_KEY&activations=true" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
    "events": [
      {
        "name": "Pageview",
        "time": "2024-01-15T10:30:00Z",
        "properties": {
          "url": "https://example.com/article/123",
          "title": "Example Article"
        }
      }
    ]
  }'
```


## OpenAPI

````yaml POST /ccs/v1/segmentation
openapi: 3.1.0
info:
  title: Custom Cohort Segmentation API
  version: v1
servers:
  - url: https://api.permutive.app
security: []
paths:
  /ccs/v1/segmentation:
    post:
      tags:
        - API version 1
      summary: Segment user based on provided events and pre-existing state
      description: >
        This endpoint accepts a list of events for a given user and combines
        them with any pre-existing state for the user to determine the full list
        of cohorts of which they are a member. State is also persisted, to be
        applied to subsequent requests for the same user.


        Events provided to this endpoint are published to the Permutive Events
        API, meaning that they will be reflected in other areas of Permutive,
        for example Insights.
      operationId: postCcsV1Segmentation
      parameters:
        - name: activations
          in: query
          description: Return a list of activated cohorts in the response
          required: false
          schema:
            default: false
            type: boolean
        - name: synchronous-validation
          in: query
          description: >-
            Validate provided event(s) against their schema before proceeding
            with segmentation.


            By default validation is performed asynchronously after segmentation
            has been performed and the response has been returned. This can make
            it difficult to debug issues with invalid events.


            It is recommended to use this option only during development and
            debugging, as validation can be expensive and slow.
          required: false
          schema:
            default: false
            type: boolean
      requestBody:
        description: >
          A user identifier together with a list of events to be used for
          segmentation.


          The user identifier must be either a `user_id`, an `alias`, or a list
          of prioritised aliases.


          The largest number of events that can currently be included in a
          single request is 10.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentationRequest'
            example:
              user_id: 2008c38f-dece-4570-976d-87593ed001c3
              alias: null
              aliases: null
              events:
                - name: Pageview
                  time: '2022-06-22T19:40:43.179Z'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_property: interesting
                - name: Pageview
                  time: '2022-06-22T19:40:45.152Z'
                  view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
                  session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
                  properties:
                    my_object:
                      inner_property: 42
        required: true
      responses:
        '200':
          description: >-
            List of cohorts of which the user is currently a member, along with
            the Permutive User ID and activations if requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationResponse'
              example:
                user_id: 2008c38f-dece-4570-976d-87593ed001c3
                cohorts:
                  - '12345'
                  - '23456'
                  - '34567'
                activations:
                  gam:
                    - '12345'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
      security:
        - apiKeyAuth: []
        - apiKeyAuth1: []
components:
  schemas:
    SegmentationRequest:
      title: SegmentationRequest
      type: object
      properties:
        user_id:
          type: string
          format: uuid
        alias:
          $ref: '#/components/schemas/Alias'
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritisedAlias'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    SegmentationResponse:
      title: SegmentationResponse
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          format: uuid
        cohorts:
          type: array
          items:
            type: string
        activations:
          $ref: '#/components/schemas/Map_Seq_String'
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
        - request_id
        - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          required:
            - type
            - status_code
            - status
            - code
            - message
            - docs
          properties:
            type:
              type: string
            status_code:
              type: integer
              format: int32
            status:
              type: string
            code:
              type: integer
              format: int32
            message:
              type: string
            docs:
              type: string
            cause:
              type: string
    Alias:
      title: Alias
      type: object
      required:
        - tag
        - id
      properties:
        tag:
          type: string
        id:
          type: string
    PrioritisedAlias:
      title: PrioritisedAlias
      type: object
      required:
        - priority
        - tag
        - id
      properties:
        priority:
          type: integer
          format: int32
        tag:
          type: string
        id:
          type: string
    Event:
      title: Event
      type: object
      required:
        - name
        - time
        - properties
      properties:
        name:
          type: string
        time:
          type: string
          format: date-time
        view_id:
          type: string
          format: uuid
        session_id:
          type: string
          format: uuid
        properties:
          $ref: '#/components/schemas/JsonObject'
    Map_Seq_String:
      title: Map_Seq_String
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    RequestId:
      title: RequestId
      oneOf:
        - type: string
        - type: string
        - type: string
          format: uuid
    JsonObject:
      title: JsonObject
      type: object
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: k
      in: query
    apiKeyAuth1:
      type: apiKey
      name: X-Api-Key
      in: header

````