Data Model
Understanding Wicket's entity relationships and data architecture
Wicket is a record-centric platform. Almost everything in the API hangs off two primary records — People and Organizations — and the relationships, memberships, contact details, and custom data attached to them. Understanding how these entities connect makes it much easier to navigate the API Reference and design integrations.
Core entities
| Entity | API type | What it represents |
|---|---|---|
| People | people | Individuals — the primary entity in Wicket's identity model. |
| Organizations | organizations | Companies, associations, and chapters. Organizations can be nested into a hierarchy. |
| Connections | connections | Typed relationships between people and organizations (called "relationships" in the admin UI). |
| Memberships | memberships, person_memberships, organization_memberships | Membership tiers offered by an organization, plus the person/organization records that hold them. |
| Groups | groups | Collections of people such as committees, teams, or chapters — owned by an organization. |
| Roles | roles | Permissions granted to a person or organization, optionally scoped to a specific record. |
| Segments | segment_filters | Saved filters over people or organizations, used for targeting and automation. |
| Contact records | addresses, emails, phones, web_addresses | Addresses, emails, phones, and web addresses attached to a person or organization. |
| Identities | user_identities, service_identities | Login accounts and external-system identifiers for a record. |
People
Person records are the heart of the identity model. A person carries profile
attributes (given_name, family_name, birth_date, …), contact records,
memberships, group memberships, roles, and any custom data_fields. A person
may optionally have a single login User account and may belong to one or
more organizations through Connections.
Organizations
Organizations represent companies, associations, and chapters. They support a parent/child hierarchy, own the membership tiers they offer, contain groups, and — like people — carry their own contact records, roles, and custom data. A person can be linked to an organization as an employee, member, or any other connection type.
Connections
A connection is a typed, directional relationship between two records. The
from and to endpoints are each either a person or an organization, so a
single model expresses person-to-person, person-to-organization, and
organization-to-organization relationships. The connection's resource type
(for example "employee" or "member") describes what the relationship means.
Memberships
The membership domain has three pieces:
- Membership tiers (
memberships) — the catalog of memberships an organization offers. Tiers can be nested into categories and are typed as eitherindividualororganization. - Person memberships — records linking a person to a tier, with status and start/end dates.
- Organization memberships — records linking an organization to a tier. An organization membership can in turn cover individual people (for example, every employee covered by a corporate membership).
Groups
Groups are collections of people owned by an organization — committees, boards, chapters, and similar. People join a group through a group member record, which has its own type and active date range. Groups themselves support a parent/child hierarchy.
Roles
Roles grant permissions to a person or organization. A role can be global or scoped to a particular record (such as administrator of one organization), which is how Wicket models fine-grained, delegated access.
Segments
Segments are saved filters over people or organizations. They power
targeting and automation — a segment can have actions that run automatically
against the records it matches. (On the wire the resource type is
segment_filters.)
Contact records
Each person and organization can have any number of:
- Addresses — physical locations, with primary, mailing, and consent flags
- Emails — with primary and consent flags
- Phones — with primary, SMS, and consent flags
- Web addresses — websites and social profiles
Every contact record carries a type (work, home, billing, …) drawn from the configurable resource-type taxonomy described below.
Identities
- Users are login accounts. A person has at most one user account (one-to-one), which is what authenticates against SSO.
- Service identities map a record to its identifier in an external system (a CRM, LMS, or payment processor), so integrations can correlate Wicket records with their own.
Entity relationship diagrams
Rather than one dense diagram, the model is easier to follow broken into the clusters that map to how you actually work with the API: the core records and the relationships between them, then memberships, groups, and contact records & roles. People and organizations appear in several diagrams because they are the hubs that everything else attaches to.
Core records & connections
People and organizations are the two primary records. A connection
is a typed, directional relationship whose from and to endpoints are each
either a person or an organization, so one model expresses person-to-person,
person-to-organization, and organization-to-organization relationships.
Organizations also nest into a parent/child hierarchy (the self-relationship
below).
Memberships
An organization offers membership tiers. A tier is granted to a person through a person membership, or to an organization through an organization membership — and an organization membership can in turn cover the person memberships of the people it includes (for example, every employee under a corporate membership).
Groups & group members
Groups are collections of people owned by an organization. A person joins a group through a group member record, which carries its own type and active date range.
Contact records & roles
Both people and organizations carry contact records and roles. Contact
records (addresses, emails, phones, web_addresses) attach
polymorphically to either record type — only emails and addresses are
drawn here to keep the diagram readable; phones and web_addresses follow the
same pattern.
Custom data (Additional Info)
Beyond the built-in attributes, Wicket lets each tenant define custom fields
so you can store data specific to your organization. Custom values live in the
data_fields attribute on a person or organization record and are validated against a JSON Schema.
Custom data can also be attached to other entity records (ex: Connection, Group and GroupMember) and the attribute name is custom_data_field.
The mechanism has three parts:
- JSON Schemas define the shape of a custom field group — the fields, their types, and validation rules. (See the JSON Schemas endpoints.)
- JSON Schema resources map a schema to the entity types it applies to (people, organizations, groups, connections, …) and the contexts it's available in.
- Data fields hold the actual values on a given record, grouped by schema.
When you read a person or organization, custom values appear under
data_fields, keyed by schema. You can also filter on them — see
Filtering & Sorting for the
data_fields.* syntax.
Resource types and entity types
Many records carry a configurable type — the kind of an address (work, home), the nature of a connection (employee, member), a person classification, and so on. These come from a two-level taxonomy:
- Entity types are the top-level categories (Person, Organization, Address, Connection, …).
- Resource types are the configurable values within a category (for an Address: work, home, billing).
This taxonomy is tenant-configurable, which is why a record's type is a
reference rather than a fixed enum.