Person Traits
Set custom parameters (traits) on a person by external_id, email, or visitor cookie — with or without an event
Traits are custom parameters you attach to a person — plan, seats, company, anything. FullVision shallow-merges them onto the person record: top-level keys you send are upserted, keys you don't send are preserved.
Use it when you know something about a person that is not an event — their plan, their seat count, their company — and you want it available as a filter on every report.
There are two ways to push traits, both on https://db.fullvision.io. Both take a secret key (sk_) — a publishable pk_ key is rejected.
Identifying the person
Both endpoints resolve the person by the same identifier precedence — send whichever you have:
| Priority | Field | Alias | Behavior |
|---|---|---|---|
| 1 | external_id | user_id | Finds or creates the person by your user ID. |
| 2 | email | — | Finds or creates the person by email. Used only when external_id is absent. |
| 3 | visitor_id | fv_visitor_id | Attaches traits only if that visitor is already linked to a person. An unlinked visitor resolves to no person and the traits are dropped. Used only when external_id and email are both absent. |
Send more than one and the highest priority wins. When you send a visitor_id alongside a resolvable external_id/email, the visitor is also stitched to that person.
Put customer attributes in traits. On POST /v1/events, properties describes the event, not the person — attributes there are not merged onto the person.
POST /v1/persons — traits only
Sets traits without creating an event. Preferred for a pure profile update.
curl -X POST https://db.fullvision.io/v1/persons \
-H "Authorization: Bearer sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"external_id": "user_12345",
"email": "jane@acme.com",
"name": "Jane Doe",
"traits": { "plan": "pro", "seats": 5, "company": "Acme" }
}'At least one of external_id / email / visitor_id is required, otherwise the call returns 400.
Response 200:
{ "person_id": "b1f2…" }person_id is null when only an unlinked visitor_id was supplied (nothing to attach the traits to yet).
POST /v1/events — traits on an event
When a real event is happening anyway, attach traits to the same call instead
of making two. Person resolution is identical to the endpoint above.
curl -X POST https://db.fullvision.io/v1/events \
-H "Authorization: Bearer sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"event_name": "plan_upgraded",
"external_id": "user_12345",
"traits": { "plan": "pro", "seats": 5 },
"properties": { "from_plan": "free" }
}'The full request shape, the batch form and the rest of the field list are on Server-side events.
Which one to use
- Profile update, no event happening →
POST /v1/persons. - A real event is happening (upgrade, signup, purchase) and you want to set traits at the same time →
POST /v1/events.