Mappings

Mappings tell Dregs what your data means. Your app might call a signup user_registered and a user's name nombre. A mapping connects each of those names to a canonical concept (Registration, Full Name) that Dregs's analyzers understand, so scoring works on your naming without changing your code.

Why Mappings Matter

Many analyzers reason about what kind of event happened or which profile field they're looking at. A check for accounts that register and never return needs to know which event is the registration. A check on name quality needs to know which field holds the name. Dregs recognizes common names out of the box. Mappings cover the rest: your own event names, fields in another language, or a name that means something different in your product.

Dregs also matches the common spellings of a snake_case name, so a mapping for sign_up also matches signup, signUp, SignUp, and sign-up, unless you've mapped one of those variants separately. Other spellings, such as SIGN_UP, need a mapping of their own.

Event Types

An event type mapping connects an event name you send with track() or POST /api/events to one of these canonical types:

• Account: Registration, Login, Login Failed, Logout, Password Reset (the recovery flow), Password Change (signed in), Email Confirmation, OTP Request, Profile Update
• Resources: Resource Create, Resource Update, Resource Retrieve, Resource Delete
• Messaging: Message Send, Email Send, Invitation Send
• Commerce: Purchase, Payment Attempt, Refund Request, Promo Redeem
• Activity: Page View, Search, Content Post, File Upload
• Miscellaneous: anything that doesn't fit the others

The canonical type appears on each event in the API as canonicalType.

Identity Fields

An identity field mapping connects a key in the data you pass to dregs.identify() (or a server SDK) to one of these canonical fields: Full Name, First Name, Last Name, Email, Username, Nickname, Organization Name, or Miscellaneous. Dregs uses them for the display name and email you see in the dashboard and for the profile checks behind the Authenticity score. Groups use Organization Name for a group's display name, as described in Groups.

Managing Mappings in the Dashboard

Open Settings and choose the Mappings tab. It has one panel for event types and one for identity fields. Each panel lists the names Dregs has seen in your data, along with any you've mapped ahead of time. Pick a canonical type for each unmapped name and save it; where Dregs recognizes a name, it suggests a match. A mapped name collapses to a single line, and its edit button reopens it so you can choose a different type. To map a name before your app starts sending it, add it by hand.

Each mapping can carry an optional short description of what the name means in your product. Admins can change mappings; other team members can view them.

Your mappings override Dregs's defaults. Deleting one of yours through the API falls back to the default for that name, if there is one.

Managing Mappings via the API

The REST API and the MCP server expose the same operations:

• GET /api/mappings?scope=CUSTOMER&kind=EVENT_TYPE lists your event type mappings. Use kind=IDENTITY_FIELD for identity fields.
• PUT /api/mappings?scope=CUSTOMER with {"kind": "EVENT_TYPE", "source": "user_registered", "target": "REGISTRATION", "description": "Signup form submitted"} creates the mapping, or replaces the one for that source.
• DELETE /api/mappings/{id}?scope=CUSTOMER removes a mapping.
• GET /api/mappings/discovery returns, for each kind, the names seen in your data with their current mapping and a suggested one.

target is the canonical name in upper case, such as LOGIN_FAILED or FIRST_NAME. Writes require an admin or a secret key. Over MCP, the tools are list_mappings, set_mapping, and delete_mapping.