Skip to main content
Everything Reach does revolves around three concepts: contact, transaction, and location. When you share data, you’re describing your own records and then telling Reach how to read them in terms of those three. Get that translation right and the rest of the platform — segments, messaging, attribution — falls into place.

​
The three canonical concepts

Anything that doesn’t fit one of these three is a custom schema — and you should send it anyway (see below).

​
Custom schemas: model your structure truthfully

Don’t flatten your data to fit ours. If your platform has jobs, invoices, estimates, memberships, appointments, or route stops, model each as its own schema exactly as it exists in your system. There’s no penalty for sending data Reach doesn’t use yet — richer relationships mean richer segments later, and the cost of adding a relationship after go-live is higher than the cost of sending it now.

​
Definitions vs. mappings — two steps, two parts of the UI

This is the distinction that trips people up, so be precise about it:
  • A schema definition is the shape of your data — a JSON Schema describing your records as they already exist. Your customerId, your service_date, your field names.
  • A schema mapping tells Reach how to read your data as its concepts — “the email field is the contact’s email,” “this schema is a transactions_schema and transactionTotal is the amount.”
Define first, map second. A definition without a mapping is just a shape Reach stores; the mapping is what turns it into a contact, a transaction, or a location.

​
Everything resolves to a contact

Segments return people, so every record you send should be traceable back to a contact through references. A transaction points at the customer who made it; a location points at the customer it serves; a route stop points at a location that points at a customer. As long as that chain exists, a segment can reach through any depth of related records and still answer with a list of contacts. You declare a reference with $ref and the reach:schemas/ scheme:

​
A concrete chain: pool service

A partner serving pool-cleaning businesses has three schemas that reference one another — each hop is a $ref from the child up to its parent:
Three schema cards referencing upward: Route Stop (custom_schema) references Service Location via locationId, which references Customer (contacts_schema) via customerId. Everything resolves to the Customer at the top.
Because every route stop traces up to a customer, Reach can answer a question that never mentions a customer directly — “customers with a service location that has no route stop scheduled the week before Labor Day” — and return exactly the people to email. That’s the whole point of modeling the relationships instead of flattening them.

Next: define your schemas

See the JSON Schema format, $ref references, categories, and PII annotations.