Personalization Properties API

Create visitor properties from tracked events for behavior-based personalization and experiment targeting.

Create rules that accumulate a scalar visitor property from the next matching tracked event. Use those properties in personalization and experiment targeting, or read them through window.ours_experiments.getVisitorContext().

For example, a page_view whose event.context.current_url contains /pricing can set visited_pricing: true. On the visitor's next full page load, target a personalization experience on the bare visited_pricing key.

Rules do not query arbitrary historical event data at evaluation time. They start accumulating after creation and persist the derived value for later page loads.

GET/rest/v1/personalization-properties

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

experimentSettingsId*string

Required. List properties belonging to this experiment settings record. Get the id from GET /rest/v1/experiment-settings.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/personalization-properties?experimentSettingsId=08524dc8-5289-48e8-bf40-b3a7cfa6ca0a"

{  "entities": [    {      "id": "string",      "experimentSettingsId": "string",      "propertyKey": "visited_pricing",      "accumulator": "set_true",      "triggerEventName": "page_view",      "triggerConditions": [        {          "field": "event.context.current_url",          "operator": "contains",          "value": "/pricing"        }      ],      "valueField": "event.context.utm_campaign",      "status": "Enabled",      "createdAt": "string",      "updatedAt": "string"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

POST/rest/v1/personalization-properties

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

experimentSettingsId*string

Experiment settings record that will own this property. Get the id from GET /rest/v1/experiment-settings.

Length1 <= length

propertyKey*string

Name this value is stored and read under. Must be unique within the parent experiment settings record — a duplicate key is rejected with 409. Because accumulated values are delivered to the visitor's browser and are readable there, never accumulate secrets, credentials, PHI, or confidential data into a property.

Length1 <= length

accumulator*string

How repeated trigger events fold into the stored value. set_true records true the first time the event matches — use it for one-shot interest flags. increment counts matching events as a number. latest_value stores the most recent value read from valueField, replacing whatever was there before.

Value in

"increment"
"latest_value"
"set_true"

triggerEventName*string

Name of the tracked event that advances this property. Every event with this name is evaluated against triggerConditions.

Length1 <= length

triggerConditions?array<>|

Optional filters the triggering event must satisfy. All conditions must match (AND). Omit or send an empty list to accumulate on every event with the matching name.

valueField?|

Event field to read the stored value from. Required for latest_value; ignored by set_true and increment. Only scalar values (string, number, boolean) are stored. Must be one of event.name, event.properties.<name>, or event.context.<name> where <name> is one of current_url, referrer, utm_source, utm_medium, utm_campaign, utm_content, or utm_term. Any other path is rejected with 400.

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/personalization-properties" \  -H "Content-Type: application/json" \  -d '{    "experimentSettingsId": "08524dc8-5289-48e8-bf40-b3a7cfa6ca0a",    "propertyKey": "visited_pricing",    "accumulator": "set_true",    "triggerEventName": "page_view"  }'

{  "id": "string",  "experimentSettingsId": "string",  "propertyKey": "visited_pricing",  "accumulator": "set_true",  "triggerEventName": "page_view",  "triggerConditions": [    {      "field": "event.context.current_url",      "operator": "contains",      "value": "/pricing"    }  ],  "valueField": "event.context.utm_campaign",  "status": "Enabled",  "createdAt": "string",  "updatedAt": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

GET/rest/v1/personalization-properties/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/personalization-properties/string"

{  "id": "string",  "experimentSettingsId": "string",  "propertyKey": "visited_pricing",  "accumulator": "set_true",  "triggerEventName": "page_view",  "triggerConditions": [    {      "field": "event.context.current_url",      "operator": "contains",      "value": "/pricing"    }  ],  "valueField": "event.context.utm_campaign",  "status": "Enabled",  "createdAt": "string",  "updatedAt": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

PATCH/rest/v1/personalization-properties/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

propertyKey?|

Renamed key. Name this value is stored and read under. Must be unique within the parent experiment settings record — a duplicate key is rejected with 409. Because accumulated values are delivered to the visitor's browser and are readable there, never accumulate secrets, credentials, PHI, or confidential data into a property. Omit this field or send null to leave it unchanged.

accumulator?|

Value in

"increment"
"latest_value"
"set_true"

triggerEventName?|

Name of the tracked event that advances this property. Every event with this name is evaluated against triggerConditions. Omit this field or send null to leave it unchanged.

triggerConditions?array<>|

Optional filters the triggering event must satisfy. All conditions must match (AND). Omit or send an empty list to accumulate on every event with the matching name. Sending this field replaces the prior list — partial-array merging is not supported. Send null or an empty array to clear every condition, which makes the rule fire on each occurrence of the trigger event.

valueField?|

status?|

Pause or resume accumulation. Disabled stops accumulating without discarding values already recorded. Omit this field or send null to leave it unchanged.

Value in

"Disabled"
"Enabled"

Response Body

`application/json`

curl -X PATCH "https://example.com/rest/v1/personalization-properties/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "experimentSettingsId": "string",  "propertyKey": "visited_pricing",  "accumulator": "set_true",  "triggerEventName": "page_view",  "triggerConditions": [    {      "field": "event.context.current_url",      "operator": "contains",      "value": "/pricing"    }  ],  "valueField": "event.context.utm_campaign",  "status": "Enabled",  "createdAt": "string",  "updatedAt": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

DELETE/rest/v1/personalization-properties/{id}

Authorization

apiKey

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/rest/v1/personalization-properties/string"

true

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

{  "error": "string",  "details": "string"}

Personalization Properties

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`