Skip to main content

​
Overview

Phase 3 focuses on defining how your data maps to Reach’s system. This is accomplished through flexible schema definitions that match your existing data structure—no transformation required.

​
The Two-Part Process

1

Defining Schemas

Tell Reach how your data is structured by providing sample JSON
2

Sending Data

Historical import followed by ongoing sync (covered in Phase 4)

​
Schema Creation Process

​
Step 1: You Provide Sample Data

Send Reach example JSON objects of your customer, transaction, and other important business records as they exist in your system.
  • Customer Example
  • Transaction Example
  • Location Example
{
  "id": "cust_12345",
  "email": "john@example.com",
  "phone": "+14155551234",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2024-01-15T10:30:00Z",
  "city": "San Francisco",
  "state": "CA",
  "total_lifetime_value": 5280.50,
  "tags": ["vip", "email_subscribed"]
}
Send real examples from your database—not idealized versions. Include all fields, even optional ones.

​
Step 2: Reach Creates Custom Schemas

Reach defines schemas in the system that accept your exact structure. Each schema is assigned a category: Schema Categories:
  • contacts_schema: Customer/contact records
  • transactions_schema: Transaction/billing records
  • locations_schema: Location/address records
  • Additional schemas: Custom schemas as needed for your business model
No data transformation required. Reach accepts your format as-is.

​
Step 3: Reach Maps Critical Fields

Reach identifies which fields in your structure serve key purposes:
  • Customer Mappings
  • Transaction Mappings
  • Location Mappings
Customer Schema Mappings:
  • Which field is the email? → email
  • Which field is the phone? → phone
  • Which field is the customer ID? → id
  • Which field is the creation date? → created_at
  • Which fields for segmentation? → tags, city, state, total_lifetime_value
  • Which fields for merge fields? → first_name, last_name
These mappings enable:
  • Segmentation for targeted campaigns
  • Personalization in emails and SMS
  • Attribution logic

​
Step 4: You Get Schema-Specific API Endpoints

Reach provisions endpoints that accept your format: 
POST /api/resources/contacts
POST /api/resources/transactions
POST /api/resources/locations
Each endpoint accepts your JSON structure directly—no reformatting needed.

​
What Data You’ll Send

​
Customer/Contact Data (Required for All Industries)

Minimum Required:
  • Email address (primary identifier)
  • Unique customer ID from your system
Highly Recommended:
  • Phone number (enables SMS, improves attribution)
  • First and last name
  • Creation date/timestamp
  • Address (city, state, zip for geographic targeting)
Optional but Valuable:
  • Custom attributes for segmentation
  • Lifetime value or spend metrics
  • Customer status (active, inactive, churned)
  • Opt-in/opt-out status for email and SMS
  • Tags or categories

​
Transaction/Billing Data (Varies by Industry)

  • Online Transactions
  • Contract-Based
  • Invoice-Based
E-commerce, Bookings:
  • Order data with line items
  • Sent after purchase completion
  • Include product/service details
{
  "externalId": "order_4567",
  "customerId": "customer_789",
  "amount": 250.00,
  "createdAt": "2024-04-15T11:30:00Z",
  "status": "completed",
  "items": [
    {
      "name": "Product A",
      "quantity": 2,
      "price": 100.00
    }
  ]
}

​
Location Data (If Applicable)

Required for:
  • Reputation product (Google Business Profile mapping)
  • Location-based segmentation in Engage
Skip if:
  • Only using Measure/Acquire
  • Single-location businesses

​
Key Decision: What Counts as a Transaction?

Work with Reach to define your “conversion event”—the moment that matters for attribution:

Booking-Based

When: Customer schedules/reservesPros:
  • Shows impact quickly
  • Captures intent early
Cons:
  • Not actual revenue yet
  • May include cancellations

Payment-Based

When: Customer paysPros:
  • Actual revenue
  • Most accurate attribution
Cons:
  • Longer attribution window
  • Delayed insights

Invoice-Based

When: Invoice is issuedPros:
  • Describes the sale
  • Works for B2B/net-terms
Cons:
  • May not reflect payment
  • Requires status updates
You can send updates as transactions progress through stages (booked → paid → fulfilled). This provides both early visibility and eventual accuracy.

​
Schema Evolution

Schemas can evolve as your needs change: Adding New Fields:
  • Send updated sample data with new fields
  • Reach adds fields to schema
  • Existing records unaffected
  • New fields available for segmentation and merge fields
Changing Field Types:
  • Discuss with Reach team via Slack
  • May require data migration
  • Reach handles complexity
Adding New Schemas:
  • Send sample data for new resource types
  • Reach creates new schema and endpoints
  • Integrate at your own pace

​
Phase 3 Checklist

1

Sample data sent to Reach

Real JSON examples of customers, transactions, locations
2

Schemas defined by Reach

Custom schemas created matching your structure
3

Field mappings confirmed

Critical fields identified for attribution and segmentation
4

API endpoints provisioned

Custom endpoints ready to accept your data
5

Conversion event defined

Decision made on what counts as a transaction

​
Next Steps

With schemas defined, you’re ready to choose a sync method and begin sending data.

Phase 4: Ongoing Data Sync

Choose sync method and implement ongoing data flow