POST /v1/cdp/traits

Add a trait worked out from an event over a window of days — how many times, when last, or a total.

Adds one of the account’s own traits, worked out for every contact from an event your website or server sends: how many times it happened, when it last happened, or the total of a number in it, over the last so many days. Values are worked out in the background.

Needs the cdp.contacts:write scope.

Body

Field	Type	Required	Notes
label	string	Yes	Its name, up to 100 characters. Its key is made from it — Cart adds · 30 days becomes cart_adds_30_days — and can’t be a built-in trait’s.
event_name	string	Yes	The event it counts, as sent to POST /v1/track. Up to 80 characters.
aggregate	string	Yes	count (how many times), last (when it last happened) or sum (the total of property).
property	string	With sum	The event property to add up. Up to 80 characters.
window_days	integer	No	How many days back it counts, 1 to 365. 30 by default.

Send an Idempotency-Key header to add it once however often the request is retried.

Request

cURL

curl -X POST "https://api.fireflo.au/v1/cdp/traits" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trait-cart-adds-30" \
  -d '{
    "label": "Cart adds · 30 days",
    "event_name": "cart_added",
    "aggregate": "count",
    "window_days": 30
  }'

Response

201 Created — the trait. Use key in audience rules, and merge_tag in messages.

{
  "key": "cart_adds_30_days",
  "label": "Cart adds · 30 days",
  "event_name": "cart_added",
  "aggregate": "count",
  "property": "",
  "window_days": 30,
  "merge_tag": "{{trait.cart_adds_30_days}}"
}

Errors

Every refusal is {"error": {"code", "message", "field"}}; field is there when one input is at fault.

Status	Error code	When
400	invalid_request	field names label (missing, a trait with this name exists, or its key would be a built-in’s), event_name, aggregate, property (missing for a sum) or window_days.
403	scope_missing	The key doesn’t have the cdp.contacts:write scope.
404	module_off	The account doesn’t have Customer data on.

Any request can also be refused for its key, its account or its rate (key_required, invalid_key, account_suspended, plan_excludes_api, address_not_allowed, rate_limited); see the overview.