Data Sync Setup

Overview

To give your customers the best possible marketing experience, Reach needs access to their data. This is achieved in two parts:

Defining Schemas - Tell us how your data is structured
Sending Data - Historical import + ongoing real-time/batch sync

Phase 3: Data Sync Setup

The Two-Step Process

Schema Definition

Reach creates flexible schemas matching your existing data structure—you don’t transform data to fit our requirements.

Data Transmission

Historical batch import followed by ongoing real-time or scheduled syncs.

Schema Creation Process

Reach’s flexible schema system adapts to your data model instead of forcing you to adapt to ours.

Step 1: You Provide Sample Data

Send Reach example JSON objects of your key business records as they exist in your system:

Example Customer Record

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

Example Transaction Record

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

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

Step 2: Reach Creates Custom Schemas

We define schemas that accept your exact structure and assign each a category:Schema Categories:

contacts_schema: Customer/contact records
transactions_schema: Transaction/billing records
locations_schema: Location/address records
Custom schemas as needed for your business model

No data transformation required—we accept your format as-is.

Step 3: Reach Maps Critical Fields

We identify which fields serve key purposes for attribution and segmentation: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

Transaction Schema Mappings:

Which field is the transaction 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

These mappings power attribution logic, segmentation, and merge fields in communications.

Step 4: You Get Schema-Specific 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

Minimum Required Data

Customer/Contact Data
Transaction/Billing Data
Location Data

All Industries Require

Required Fields:

Email address (primary identifier)
Unique customer ID from your system

Recommended Fields:

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 (tags, categories, preferences)
Lifetime value or spend metrics
Customer status (active, inactive, churned)
Opt-in/opt-out status for email and SMS

Complete Example

{
  "externalId": "customer_789",
  "email": "[email protected]",
  "phone": "+14155559876",
  "firstName": "Jane",
  "lastName": "Smith",
  "createdAt": "2023-06-10T08:15:00Z",
  "address": {
    "street": "456 Oak Ave",
    "city": "Portland",
    "state": "OR",
    "zip": "97201"
  },
  "tags": ["premium_member", "email_subscribed"],
  "lifetimeValue": 3200.00,
  "optInEmail": true,
  "optInSms": false
}

Varies by Industry

Online Transactions (e-commerce, bookings):

Order data with line items
Sent after purchase completion
Include product/service details

Contract-Based Businesses (SaaS, memberships):

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

Invoice-Based Businesses (B2B services):

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

Transaction Example

{
  "externalId": "order_4567",
  "customerId": "customer_789",
  "amount": 250.00,
  "createdAt": "2024-04-15T11:30:00Z",
  "status": "completed",
  "items": [
    {
      "name": "Premium Service Package",
      "quantity": 1,
      "price": 200.00
    },
    {
      "name": "Add-on Feature",
      "quantity": 1,
      "price": 50.00
    }
  ]
}

For Multi-Location Businesses

Required for:

Reputation product (Google Business Profile mapping)
Location-based segmentation in Engage

Include:

Business location addresses
Location names/identifiers
Google Business Profile IDs (if known)
Operating hours, phone numbers

Location Example

{
  "externalId": "loc_001",
  "name": "Downtown Portland Office",
  "address": {
    "street": "789 SW Broadway",
    "city": "Portland",
    "state": "OR",
    "zip": "97205"
  },
  "phone": "+15035551000",
  "googleBusinessProfileId": "ChIJ..."
}

Skip this if you’re only using Measure/Acquire or if your customers are 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 actual payment
Requires status updates

You can send updates as transactions progress through stages (booked → paid → fulfilled). This gives both early visibility and eventual accuracy.

How You’ll Send Data

Choose the method (or combination) that fits your infrastructure:

Real-Time API
Batch API
Database Access
CSV Import

Event-by-Event Sync

Send customer and transaction records to Reach API as events occur in your system.Best for: Partners who want instant analytics and need real-time segmentationHow it works:

// When a new customer is created in your system
await fetch('https://api.embedreach.com/api/resources/contacts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${PARTNER_API_KEY}`,
    'X-Tenant-Id': tenantExternalId,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(customerData),
});

Pros:

Immediate attribution
Real-time campaign targeting
Fresh data for segmentation

Cons:

Requires event hooks in your system
More API calls (rate limiting considerations)

Scheduled Bulk Sync

Send records to Reach API in scheduled batches (hourly, daily, etc.).Best for: Partners who prefer controlled sync windows or have high transaction volumesHow it works:

// Daily batch sync of yesterday's transactions
await fetch('https://api.embedreach.com/api/resources/transactions/batch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${PARTNER_API_KEY}`,
    'X-Tenant-Id': tenantExternalId,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resources: transactionsArray, // Array of transaction objects
  }),
});

Pros:

Controlled sync windows
Efficient for high volumes
Easier error handling

Cons:

Delayed attribution visibility
Requires batch processing infrastructure

Hybrid Approaches

Many partners use combinations:

Database access for initial historical load → Real-time API for ongoing syncs
Real-time API for transactions → Batch API for customer updates
Batch API for regular syncs → Database access for one-time historical backfill

The key is consistent data flow—whether event-by-event or in regular batches. Choose what fits your infrastructure and commit to keeping Reach’s data in sync with yours.

Phase 4: Ongoing Data Sync

Once schemas are defined and your sync method is chosen, implement the data flow:

Your Responsibilities

Implement your chosen sync method

Set up real-time hooks, batch jobs, or database views based on your decision.

Start sending data to Reach

Begin with historical backfill, then ongoing syncs for new/updated records.

Keep data flowing

Ensure customers and transactions sync as they’re created/updated in your system.

Send status updates

Update transactions when they change status (refunded, canceled, modified).

Reach’s Responsibilities

Create custom schemas matching your data
Map fields to attribution logic
Provision custom API endpoints
Handle schema evolution as your needs change
Query database on schedule (if using database access method)

Important Notes

Keep Reach’s Data in SyncWhether you’re sending real-time, batches, or using database access, ensure we have current information about:

Customer updates (address changes, opt-in status, etc.)
Transaction status changes (completed → refunded, pending → paid)
Refunds or cancellations
New customers and transactions as they’re created

Using External IDsWhen using Reach APIs, you can always use the resource externalId. This maps to YOUR internal ID so you never need to know or store Reach’s resource IDs. This makes integration much simpler.

Data Sync Checklist

Sample data sent to Reach - Real examples of customers, transactions, locations

Schemas defined - Reach has created schemas matching your structure

Sync method chosen - Real-time API, Batch API, Database Access, or hybrid

Endpoints or access provisioned - You have what you need to send data

Historical import complete - Existing data backfilled

Ongoing sync implemented - New/updated records flow automatically

Next Steps

Channel Setup

Phase 5: Configure email & SMS (Engage only)

Tracking Setup

Phase 8: Implement attribution snippet (Acquire/Measure)

Integration Checklist

Full implementation checklist

API Documentation

Detailed API reference

Getting Started

Integration Guide

Overview

Phase 3: Data Sync Setup

The Two-Step Process

Schema Creation Process

What Data You’ll Send

Minimum Required Data

All Industries Require

Varies by Industry

For Multi-Location Businesses

Key Decision: What Counts as a Transaction?

Booking-Based

Payment-Based

Invoice-Based

How You’ll Send Data

Event-by-Event Sync

Scheduled Bulk Sync

Reach Queries Your Database

One-Time File Upload

Hybrid Approaches

Phase 4: Ongoing Data Sync

Your Responsibilities

Reach’s Responsibilities

Important Notes

Data Sync Checklist

Next Steps

Channel Setup

Tracking Setup

Integration Checklist

API Documentation

Getting Started

Integration Guide

​Overview

​Phase 3: Data Sync Setup

​The Two-Step Process

​Schema Creation Process

​What Data You’ll Send

​Minimum Required Data

​All Industries Require

​Varies by Industry

​For Multi-Location Businesses

​Key Decision: What Counts as a Transaction?

Booking-Based

Payment-Based

Invoice-Based

​How You’ll Send Data

​Event-by-Event Sync

​Scheduled Bulk Sync

​Reach Queries Your Database

​One-Time File Upload

​Hybrid Approaches

​Phase 4: Ongoing Data Sync

​Your Responsibilities

​Reach’s Responsibilities

​Important Notes

​Data Sync Checklist

​Next Steps

Channel Setup

Tracking Setup

Integration Checklist

API Documentation

Overview

Phase 3: Data Sync Setup

The Two-Step Process

Schema Creation Process

What Data You’ll Send

Minimum Required Data

All Industries Require

Varies by Industry

For Multi-Location Businesses

Key Decision: What Counts as a Transaction?

How You’ll Send Data

Event-by-Event Sync

Scheduled Bulk Sync

Reach Queries Your Database

One-Time File Upload

Hybrid Approaches

Phase 4: Ongoing Data Sync

Your Responsibilities

Reach’s Responsibilities

Important Notes

Data Sync Checklist

Next Steps