Anonymous Events
Start logging events before people sign up or log into your site, app, or service. When people sign up or log in, you can associate those events with people. Anonymous events help you do things like personalize your onboarding campaigns based on things people did before they signed up. For example, if a customer viewed a pricing plan before signing up for a trial, your onboarding campaign might cover features relevant to the plan they viewed.
An anonymous event is an event associated with a person you don’t recognize. The event bears an anonymous_id
—a value representing the unknown person, like a cookie. We store these events for up to 30 days.
The Anonymous event merge feature lets you associate these events with a person after you identify them. You can enable anonymous event merging in your workspace settings.
- If you use the JavaScript snippet (client-side): we automatically log anonymous events and associate them with people you identify.
- If you use the API (server-side): When you log anonymous events, you’ll set an
anonymous_id
on the event. When you identify people, you can set ananonymous_id
attribute, and we’ll associate any events with the matchinganonymous_id
that we received up to, and within five minutes after, youridentify
call. If you send anonymous events more than five minutes after theidentify
call that you want to associate with a previously identified person, you need to send a newidentify
request with theanonymous_id
of the events you want to associate with a known person.


Turn on anonymous event merging
When you create a new workspace, anonymous event merging is on by default
If you created your workspace before July 2021, you must enable Anonymous event merging to associate anonymous events with people you identify.
Anonymous event merging is the act of associating anonymous events—events with an anonymous_id
—with a person. When you assign an anonymous_id
attribute to a person, any anonymous events with that same ID are associated with the person.
- Go to Settings > Workspace Settings
- Scroll down to Merge Settings and click Settings.
- Turn on the Anonymous event merge setting.
- Set up an integration that sends events to Customer.io:
- Use the JavaScript Snippet.
- Integrate with the endpoint to track anonymous events.
Now, any events with an anonymous_id
are merged with people bearing the same anonymous_id
attribute.
JavaScript snippet implementation (client-side)
Using the JavaScript snippet, you can send anonymous events with _cio.track
. If you’ve enabled Anonymous event merging, the JavaScript snippet automatically associates events (that occurred in the past 30 days) with people when you identify them.
So, for example, if a person adds items to their cart before they log in, the snippet automatically associates those events with a person when they log in.
<script type="text/javascript">
_cio.track("addedToCart", { product: "cool-shoes" });
_cio.identify({
id: 'YOUR_USER_ID_HERE',
});
</script>
Server-side API implementation
If you send events to us using the API, you can set the anonymous_id
in the payload of an anonymous event call. These events represent things done by people you haven’t identified.
When you use the identify method, you can set a person’s anonymous_id
attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.. This tells us to associate events with the matching anonymous ID that you sent before, and up to five minutes after, with the person you identify. After you identify a person, you should send events using their known identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. until they log out (or otherwise become unidentifiable), and not the anonymous ID that you previously used.
person]-->|performs activity| B[/Event with
anonymous ID/] B-->|person logs in| C[/identify call
w/anonymous ID/] D-->G[No] C-->D{Does
anonymous_id
match?}-->E[Yes] E-->F[Events merged w/
Identified Person] F-->H[/Events use
ID or email/] F-->|Person logs out| A
You cannot reuse an anonymous ID after you have assigned it to a person. If you send an event with an anonymous ID that you already assigned to a person more than five minutes ago, the event will not be associated with the identified person; it will remain anonymous.
If you send events with a new anonymous ID for a person you identified more than five minutes ago, you’ll need to send a new identify
request with the new anonymous ID to associate those events with a person.
The example event below has an anonymous_id
of abc123
. Anonymous event IDs must be unique and are not reusable. The corresponding identify
request will associate events with the anonymous_id
of abc123
with the person identified by the email address person@example.com
.
{
"name": "https://example.com/interesting-page",
"anonymous_id": "abc123",
"type": "page",
"data": {
"first_name": "Person",
}
}
curl --request PUT \
--url https://track.customer.io/api/v1/customers/person@example.com \
--header "Authorization: Basic $(echo -n site_id:api_key | base64)" \
--header 'content-type: application/json' \
--data '{"email":"user@example.com","anonymous_id":"abc123"}'
Anonymous event retention and campaign triggers
Customer.io retains anonymous events for 30 days. These events don’t do anything—they cannot trigger campaigns or segment membership—until they are associated with a person. They appear in the activity log in the Anonymous tab, but they’re otherwise unusable until you associate them with a person by anonymous_id
.
When an anonymous event is associated with a person, it can trigger a campaign if it occurred within the past 72 hours.
Anonymous event merge in the activity log
The Activity Log reports an Anonymous Data Merged activity for a person when anonymous events are merged to an identified person’s profileAn instance of a person. Generally, a person is synonymous with their profile; there should be a one-to-one relationship between a real person and their profile in Customer.io. You reference a profile’s attributes in liquid using customer
—e.g. {{customer.email}}
.. This activity records the number of anonymous events merged with a profile, the unix timestamp for the oldest event, and the anonymous ID for the events.


Third-party support for anonymous events
The following third-parties support anonymous events:
- Segment Destination Actions
- Segment Destination (Device mode only)
To request support for anonymous events from other third-party platforms, email the third party directly and CC product@customer.io.
Anonymous events vs invite events
An invite event is very similar to an anonymous event: it uses the same API endpoint as anonymous events, but it contains a data.recipient
field and does not contain an anonymous_id
. The recipient
contains the email address of someone that you want to send a message to—typically an “invite”, hence “invite event”. Here’s an example payload for an invite event.
{
"name": "https://example.com/invite-me",
"type": "page",
"data": {
"recipient": "person@example.com",
"first_name": "Person",
}
}
Invite events can trigger message campaigns to people who aren’t in your workspace. However, before you consider using events this way, we encourage you to consider transactional messaging—in which a person implicitly requests an email, we identify a person, and then send them a message—or otherwise identifying a person by email first and then triggering a campaign.
Identifying a person provides a way for you to track a person’s preferences (both using the unsubscribed
attribute and other attributes). It provides a way to retain information about the person you send messages to, and to track the outcome of your invite—something that you cannot do if you use invite events to send messages directly to a recipient.
Anonymous events in the Activity log
The activity log shows Identified and Anonymous events. Identified events are events associated with a person in your workspace. Anonymous events are associated with an unknown person. While we capture anonymous events, these events don’t do anything until you associate (or merge) them with a person.
When events are merged to a person’s profile, they become “identified” and appear in the Identified tab. Events with a icon next to the person, were previously anonymous events that are now associated with a person.

