Schemas
A schema defines one kind of business record and the fields maxclicks accepts for it. It gives your team, integrations and agents the same vocabulary for customers, subscriptions, products and business events.
Start with a decision you want to support. A renewal journey needs a customer, the subscription they own, a renewal date and a meaningful connection between the two. Creating those definitions prepares the model; importing or syncing records supplies the facts.
Create your first schema
Open Settings → Schemas → Create schema and choose:
- Type: Contact for people, or Object for business entities. This choice is fixed after creation.
- Name and Plural name: the singular and list labels. Schema names are also used in generated definitions, so the form normalizes them rather than accepting arbitrary display text.
- Slug: the stable URL and API identifier. This is also fixed after creation.
- Description: what one record represents and which source owns its facts.
Create business event schemas separately under Settings → Events. Website and server collected events have their own source and versioned payload definition there.
After creation, open Attributes to add fields. Give each field a type and missing-value policy. A field description should include units, allowed meanings and the source of the value. See Attributes.
Choose the right kind
| Kind | What one record represents | Identity and change |
|---|---|---|
| Contact | A person your team can address | Can be created or updated; matched within its contact schema |
| Object | A product, order, account, subscription or another business entity | Can be created or updated; your externalId makes repeated syncs refer to the same object |
| Event | One business occurrence | Accepted once for an occurrence identity; prepared before downstream use; not edited into a new fact |
Contacts and objects appear under Records, one list per schema. A person can have a record in two contact schemas. maxclicks does not automatically combine those profiles or their preferences across schemas.
What every record already has
All records have a platform id and timestamps. Contacts also have names, email, phone, your userId, an avatar, notes and tags. Their communication fields include channel subscriptions, topicIds, source and email statistics.
Objects have externalId, notes and tags. Add fields such as status, price or renewal date for your own model.
Business events have eventId, occurredAt, receivedAt, readyAt, readinessState and definitionRevision, plus an optional explicit contactId or objectId subject. See Events for the difference between acceptance and readiness.
Platform-maintained fields are read-only even when they appear alongside writable fields. Published calculated values also have their own read-only context and expansion rules; do not import a traits column as customer data.
How maxclicks decides a record is one you already have
Matching happens inside the selected schema. For contacts, a platform ID identifies a record directly. Otherwise the supplied userId takes priority; without it, email is used, and without either, phone is used. This is not a search across every identifier until any match is found. A new userId can describe a different profile from an email-only record.
Objects use the platform ID or an externalId within the object schema. Without a usable identity, a write can create another record instead of matching the one you intended.
Conflicting identifiers are handled differently by different write operations. Review the contact identity rules, object identity rules and the response from your chosen API operation. Event retry detection is separate and uses eventId with an unchanged occurrence payload.
Name it something maxclicks can use
Schema names and slugs must be available within the workspace. The form checks availability and normalizes names; names are 2–200 characters and cannot use reserved data-type terms such as string, number, object or event. Use a business name such as Customer, Subscription or PurchaseCompleted.
Choose slugs for longevity because integrations and API calls use them. Use display names and descriptions to improve clarity later without changing those references.
Your default contact schema
The first contact schema becomes the workspace default. A Default badge identifies it; use Set as default on another contact schema to change the default.
The default helps operations that do not specify a schema. It does not move existing contacts, merge schemas or override an explicit selection. Keep at least one contact schema in the workspace.
Change a schema later
The Configuration tab lets you change names and the description. The type and slug remain fixed. Integration-owned schemas are locked against manual configuration changes; their own integration maintains those definitions.
Deleting a schema permanently removes the records it owns. Dependencies and the last-contact-schema requirement can block deletion. Read the reported references and update the consuming definitions before retrying.
Deletion is an asynchronous operation when cleanup is required. The app waits for its status; the initial accepted request is not the same as completed cleanup. Other workspace processing can be temporarily gated while deletion removes related data. Do not use deletion as a way to rename a populated schema.
Related
- Attributes: stored fields, evaluated relationships and computed measures.
- Contacts and Objects: identity, editing and imports.
- Events: business occurrences and typed collection sources.
- Segments: apply the model to an audience.
- Schemas API and Records API: inspect definitions and write supported records.