Data Sync Setup

Overview

Phase 4 turns your Phase 3 plan into concrete schemas. You define how your data maps to Reach’s system through flexible schema definitions that match your existing data structure—no transformation required.

The Two-Part Process

Defining schemas

You define schemas that describe your data exactly as it exists in your system, and map the fields Reach needs.

Sending data

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

This is self-service — you create schemas, map fields, and send data through the partner UI or API without waiting on us. During onboarding we’ll review the model with you before go-live. If you haven’t yet, read How Reach models your data first; the Custom Schemas reference has the full JSON format.

Schema Creation Process

Step 1: Start from your real data

Use example JSON objects of your customer, transaction, and other important business records as they exist in your system as the basis for the schemas you’ll define. Don’t reshape your data to fit ours — the schema describes your structure as-is.

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

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

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

Send real examples from your database—not idealized versions. Include all fields, even optional ones.

Step 2: Define custom schemas

Create a schema for each record type. Each schema accepts your exact structure and 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 — your format is accepted as-is. See Custom Schemas for the JSON Schema format, $ref references between schemas, and PII annotations.

Step 3: Map critical fields

In each schema mapping, identify which fields 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

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 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: Send data to the resources endpoint

Once a schema exists, you write records against it at the standard resources endpoint, keyed by schema name:

POST /api/resources/{SchemaName}    # e.g. /api/resources/Customer, /api/resources/Transaction

Each request accepts your JSON structure directly—no reformatting needed. Writes are an upsert keyed on the record’s external ID. See Ongoing Data Sync for single vs. batch writes and backfill.

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

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

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/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, within strict validation rules that protect existing data: Adding new fields — always safe. Add the field to the schema; existing records are unaffected and the new field becomes available for segmentation and merge fields. Renaming, retyping, or removing a field — restricted once records exist. Removing a field that resources use returns an error rather than silently dropping data; a field that live tenant segments or merge fields depend on is protected. While you’re still iterating before go-live, the simplest path is to clear a schema’s resources and re-send. Adding new schemas — self-service and independent. Define the new schema and start writing to it at your own pace.

The full change-by-change reference (what’s allowed, what errors, and how to fix it) lives in the schema lifecycle guide.

Phase 4 Checklist

Sample data sent to Reach

Real JSON examples of customers, transactions, locations

Schemas defined by Reach

Custom schemas created matching your structure

Field mappings confirmed

Critical fields identified for attribution and segmentation

API endpoints provisioned

Custom endpoints ready to accept your data

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 5: Ongoing Data Sync

Choose sync method and implement ongoing data flow

Getting Started

Integration Guide

Overview

The Two-Part Process

Schema Creation Process

Step 1: Start from your real data

Step 2: Define custom schemas

Step 3: Map critical fields

Step 4: Send data to the resources endpoint

What Data You’ll Send

Customer/Contact Data (Required for All Industries)

Transaction/Billing Data (Varies by Industry)

Location Data (If Applicable)

Key Decision: What Counts as a Transaction?

Booking-Based

Payment-Based

Invoice-Based

Schema Evolution

Phase 4 Checklist

Next Steps

Phase 5: Ongoing Data Sync

​Overview

​The Two-Part Process

​Schema Creation Process

​Step 1: Start from your real data

​Step 2: Define custom schemas

​Step 3: Map critical fields

​Step 4: Send data to the resources endpoint

​What Data You’ll Send

​Customer/Contact Data (Required for All Industries)

​Transaction/Billing Data (Varies by Industry)

​Location Data (If Applicable)

​Key Decision: What Counts as a Transaction?

Booking-Based

Payment-Based

Invoice-Based

​Schema Evolution

​Phase 4 Checklist

​Next Steps

Phase 5: Ongoing Data Sync

Overview

The Two-Part Process

Schema Creation Process

Step 1: Start from your real data

Step 2: Define custom schemas

Step 3: Map critical fields

Step 4: Send data to the resources endpoint

What Data You’ll Send

Customer/Contact Data (Required for All Industries)

Transaction/Billing Data (Varies by Industry)

Location Data (If Applicable)

Key Decision: What Counts as a Transaction?

Schema Evolution

Phase 4 Checklist

Next Steps