Identify users and companies

This is the second step of Instrument your app. It assumes you have already installed the SDK.

Schematic does not mint its own identifiers. It uses the ones already in your system, and calls them keys. A key can be any alphanumeric string. Your internal customer ID, a Stripe customer ID, or a Salesforce account ID all work.

Identify on the frontend

The frontend SDKs expose an identify function that takes information about both the user and the company, and sets that context for every subsequent call in the session.

1
useEffect(() => {
2
  identify({
3
    company: {
4
      keys: { "demo-id": "demo-company" },
5
    },
6
    keys: { "demo-id": "demo-user" },
7
  });
8
}, [identify]);

This identifies the company demo-company and the user demo-user.

Identify on the backend

The backend SDKs wrap API calls that all take a keys argument. Below is upsertCompany in Python.

1
client.companies.upsert_company(
2
    keys={"demo-id": "demo-company"},
3
)

What actually matters

The company keys are the required part. They are what loads the correct plan, entitlements, and usage data. Identifying the user on top of that is optional, and worth doing because it makes usage data far more legible later.

Beyond keys you can attach a name and traits. Traits are metadata you can target on, including trait-based entitlements.

1
useEffect(() => {
2
  identify({
3
    company: {
4
      keys: { "demo-id": "demo-company" },
5
      name: "Acme Widgets, Inc.",
6
      traits: {
7
        city: "Atlanta",
8
        high_score: 25,
9
        is_active: true,
10
      },
11
    },
12
    keys: { "demo-id": "demo-user" },
13
    traits: {
14
      role: "admin",
15
    },
16
    name: "John Doe",
17
  });
18
}, [identify]);

1
client.companies.upsert_company(
2
    keys={"demo-id": "demo-company"},
3
    name="Acme Widgets, Inc.",
4
    traits={
5
        "city": "Atlanta",
6
        "high_score": 25,
7
        "is_active": True,
8
    },
9
)

Choosing between identify and upsertCompany

Both upsert. Identify a company Schematic has never seen and it gets created either way. The differences are where they run and what they return.

Last seen timestamps

Schematic records the most recent identify or track call per company and user. While you are wiring things up, the Companies and Events tabs are the fastest confirmation that your calls are landing. Afterwards, an account that has stopped sending activity is a churn signal worth acting on.

You can also set the timestamp explicitly through the companyUpsert endpoint, in the API or any SDK.

Next step

Return to Instrument your app for entitlement checks, usage events, and components. Keys are a core concept, and Key Management covers how they resolve and how to choose them.