Pre-release — content may change.

Concepts

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

EntityAPI typeWhat it represents
PeoplepeopleIndividuals — the primary entity in Wicket's identity model.
OrganizationsorganizationsCompanies, associations, and chapters. Organizations can be nested into a hierarchy.
ConnectionsconnectionsTyped relationships between people and organizations (called "relationships" in the admin UI).
Membershipsmemberships, person_memberships, organization_membershipsMembership tiers offered by an organization, plus the person/organization records that hold them.
GroupsgroupsCollections of people such as committees, teams, or chapters — owned by an organization.
RolesrolesPermissions granted to a person or organization, optionally scoped to a specific record.
Segmentssegment_filtersSaved filters over people or organizations, used for targeting and automation.
Contact recordsaddresses, emails, phones, web_addressesAddresses, emails, phones, and web addresses attached to a person or organization.
Identitiesuser_identities, service_identitiesLogin 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 either individual or organization.
  • 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.

On this page