Data Sync Setup

Phase 3: Define schemas for your data structure

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

{
  "id": "cust_12345",
  "email": "[e-mail]",
  "phone": "[phone]",
  "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"]
}

Transaction Example

{
  "id": "txn_67890",
  "customer_id": "cust_12345",
  "amount": 150.00,
  "created_at": "2024-03-20T14:22:00Z",
  "status": "completed",
  "items": [
    {
      "name": "Service A",
      "price": 100.00
    },
    {
      "name": "Service B",
      "price": 50.00
    }
  ]
}

Location Example

{
  "id": "loc_001",
  "name": "Downtown Office",
  "address": {
    "street": "123 Main St",
    "city": "Portland",
    "state": "OR",
    "zip": "97201"
  },
  "phone": "[phone]",
  "google_business_profile_id": "ChIJ..."
}

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

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

Transaction Mappings

Transaction Schema Mappings:

• Which field is the amount? → amount or total
• Which field is the transaction date? → created_at or completed_at
• Which field links to customer? → customer_id
• Which field indicates status? → status
• Which fields contain line items? → items array

These mappings enable:

• ROAS calculations
• Revenue attribution
• Conversion tracking

Location Mappings

Location Schema Mappings:

• Which field is the location name? → name
• Which field has the address? → address object
• Which field links to Google Business Profile? → google_business_profile_id

These mappings enable:

• Multi-location reputation management
• Location-based segmentation
• Google Business Profile integration

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

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
    }
  ]
}

Contract-Based

SaaS, Memberships:

• Agreements/proposals after finalization
• Can be amended over time as contracts change
• Include contract value and terms

{
  "externalId": "contract_789",
  "customerId": "customer_456",
  "amount": 12000.00,
  "createdAt": "2024-01-10T09:00:00Z",
  "startDate": "2024-02-01",
  "endDate": "2025-02-01",
  "status": "active"
}

Invoice-Based

B2B Services:

• Invoice data (even if unpaid)
• More important than payment completion
• Describes the sale before money changes hands

{
  "externalId": "invoice_123",
  "customerId": "customer_789",
  "amount": 5000.00,
  "invoiceDate": "2024-03-01",
  "dueDate": "2024-03-31",
  "status": "pending",
  "services": [...]
}

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/reserves

Pros:

• Shows impact quickly
• Captures intent early

Cons:

• Not actual revenue yet
• May include cancellations

Payment-Based

When: Customer pays

Pros:

• Actual revenue
• Most accurate attribution

Cons:

• Longer attribution window
• Delayed insights

Invoice-Based

When: Invoice is issued

Pros:

• 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