Skip to main content
POST
/
ccs
/
v1
/
segmentation
Segment user based on provided events and pre-existing state
curl --request POST \
  --url 'https://api.permutive.app/ccs/v1/segmentation?k=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
        }
      }
    }
  ]
}
'
{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "cohorts": [
    "12345",
    "23456",
    "34567"
  ],
  "activations": {
    "gam": [
      "12345"
    ]
  }
}
This endpoint persists user state, which will be used in subsequent requests for the same user.

​
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

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"
        }
      }
    ]
  }'

Authorizations

​
k
string
query
required

Query Parameters

​
activations
boolean
default:false

Return a list of activated cohorts in the response

​
synchronous-validation
boolean
default:false

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.

Body

application/json

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.

​
user_id
string<uuid>
​
alias
Alias · object
​
aliases
PrioritisedAlias · object[]
​
events
Event · object[]

Response

List of cohorts of which the user is currently a member, along with the Permutive User ID and activations if requested

​
user_id
string<uuid>
required
​
cohorts
string[]
​
activations
Map_Seq_String · object