> ## Documentation Index
> Fetch the complete documentation index at: https://canopy.wnstn.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify and Link Users to Events in Cano Analytics

> Connect events to real user profiles using identify() calls, manage anonymous-to-known user aliasing, and understand traits vs. event properties.

The `identify()` call links events to real people so you can analyze behavior by user, segment, and cohort. Without it, Cano can tell you *what* happened but not *who* did it. Once you identify a user, every subsequent event tied to their `user_id` automatically enriches their profile in your dashboard.

## How Identify Works

When you call `identify()`, you send a `user_id` and an optional map of **traits** — descriptive attributes about that person. Cano merges all events sharing that `user_id` into a single unified user profile. Traits are stored on the profile and can be used to filter and segment your reports.

<Steps>
  <Step title="Call identify() at sign-in">
    Fire `identify()` as soon as you know who the user is — typically right after login or registration.
  </Step>

  <Step title="Pass stable traits">
    Include traits that describe the user: their name, email, plan, and account creation date.
  </Step>

  <Step title="Cano merges the profile">
    All past and future events with that `user_id` are linked to this profile automatically.
  </Step>
</Steps>

## Identifying a User

<CodeGroup>
  ```javascript JavaScript theme={null}
  cano.identify('usr_123', {
    name: 'Ada Lovelace',
    email: 'ada@example.com',
    plan: 'pro',
    created_at: '2024-01-15'
  });
  ```

  ```python Python theme={null}
  client.identify(
      user_id='usr_123',
      traits={
          'name': 'Ada Lovelace',
          'email': 'ada@example.com',
          'plan': 'pro',
          'created_at': '2024-01-15'
      }
  )
  ```

  ```bash REST API theme={null}
  curl -X POST https://api.canoanalytics.io/v1/identify \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "user_id": "usr_123",
      "traits": {
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "plan": "pro",
        "created_at": "2024-01-15"
      }
    }'
  ```
</CodeGroup>

You can call `identify()` multiple times for the same user — Cano will merge new traits into the existing profile, overwriting any keys that have changed (for example, when a user upgrades their plan).

## Anonymous Users

Cano automatically generates an `anonymous_id` for every unauthenticated visitor, so you capture behavior before you know who they are. When the user signs in, call `identify()` and Cano will **alias** the anonymous session to the real user — meaning all events from the anonymous session retroactively appear on their profile.

```javascript JavaScript theme={null}
// Before login — Cano auto-assigns an anonymous_id and tracks events
cano.track('page_viewed', { page: '/pricing' });

// After the user logs in — link the anonymous session to their real identity
cano.identify('usr_123', {
  name: 'Ada Lovelace',
  email: 'ada@example.com',
  plan: 'pro'
});
// All previous anonymous events are now merged into usr_123's profile
```

## Aliasing Two User IDs

If you need to explicitly merge two known identifiers — for example, a temporary ID from a third-party system and your internal `user_id` — use `cano.alias()`.

```javascript JavaScript theme={null}
// Merge anon_456 into usr_123 — anon_456 becomes an alias
cano.alias('usr_123', 'anon_456');
```

After this call, any events previously attributed to `anon_456` are merged into the `usr_123` profile. Use alias sparingly and only when you have two distinct IDs that represent the same real person.

## User Traits vs. Event Properties

It's important to understand the distinction between traits and properties so your data model stays clean.

|               | **User Traits**                         | **Event Properties**                   |
| ------------- | --------------------------------------- | -------------------------------------- |
| **Set with**  | `identify()`                            | `track()`                              |
| **Describe**  | Who the user *is*                       | What *happened*                        |
| **Examples**  | `plan`, `role`, `company`, `created_at` | `page`, `button`, `amount`, `currency` |
| **Stored on** | User profile                            | Individual event                       |
| **Used for**  | Segmentation, cohorts                   | Filtering, funnel analysis             |

Use traits for persistent, descriptive attributes about a person. Use event properties for the context of a specific action.

<Note>
  **GDPR & data deletion:** You have the right to erase a user's data on request. To delete all events and traits associated with a `user_id`, use the [Users API](/docs/api-reference/users). Cano will permanently remove the profile and all linked events within 30 days, in compliance with GDPR Article 17.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Properties" icon="tag" href="/docs/tracking/custom-properties">
    Enrich your events and user profiles with typed properties that are fully queryable in charts.
  </Card>

  <Card title="Event Tracking" icon="bolt" href="/docs/tracking/event-tracking">
    Go back to event tracking fundamentals — naming conventions, batch sending, and the real-time stream.
  </Card>
</CardGroup>