People and identify
How Get Butters builds a People list for each project, and how to set properties on a person with the identify API.
Get Butters keeps a People tab for every project. It lists everyone your app has ever attached to an event through a user_id: their user id, when you first saw them, when you last saw them, how many events they've sent, and any properties you've set on them.
Where to find it
Open a project and click People in the project navigation. You can search the list by typing the start of a user id into the search box.
How people are created
A person shows up automatically the first time an event for that project carries a user_id. This works the same way whether the event comes from the API, from the dashboard playground, from an incoming webhook, or from an import. Every later event with the same user_id updates that person's last seen time and event count. Nothing about this requires calling identify: sending events with a user_id is enough.
Setting properties with identify
If you want to record facts about a person, not just that they exist, call the identify endpoint from your app:
POST /api/identifywith a body like:
{ "user_id": "user-456", "properties": { "plan": "pro", "email": "maria@example.com" } }identify does not create an event and does not count against your monthly event quota. It only sets or updates properties on the person. New properties are merged into whatever the person already has, so calling identify again with just one field leaves the rest alone. Setting a property to null stores null; it does not remove the property.
See the API reference (api.md, Identify section) in the repo for the exact request and error format.
Trust warning: only set what you can afford to lose
If you call identify from a browser using a publishable key, treat everything it sends as unverified. Anyone who can run JavaScript on your page, or who can craft the HTTP request by hand, can call identify with any user_id and any properties they like. There is nothing stopping them from claiming to be a different user or inventing property values.
Because of this, never set a property that matters from a publishable key: not a plan, not billing status, not anything used to grant access, and not anything that will trigger an alert. Set those from your own server using a secret key, where you control both the user_id and the values going in. Reserve publishable-key identify calls for cosmetic details, like a theme preference or last-viewed page.
identify records what a client claims about a user. It is not authentication, and it does not prove the request came from that user.
Troubleshooting
"user_id is required": you called identify without a user_id, or sent an empty one. Every identify call needs a user_id between 1 and 200 characters.
"properties must be a JSON object": properties was missing an object shape, for example an array or a plain string. Send properties as a JSON object of key-value pairs, or leave it out entirely.
"properties must serialize to at most 65536 bytes": the properties object is too large. Trim it to the fields you actually need; identify isn't meant to store large blobs.
A publishable key request returns 404 Project not found: publishable keys write to one project only. If you pass a project field naming a different project, the call is rejected. Omit project entirely when using a publishable key.