> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedreach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sync Setup

> Phase 3-4: Schema creation and ongoing data synchronization

## Overview

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

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

## Phase 3: Data Sync Setup

### The Two-Step Process

<Steps>
  <Step title="Schema Definition">
    Reach creates flexible schemas matching your existing data structure—you don't transform data to fit our requirements.
  </Step>

  <Step title="Data Transmission">
    Historical batch import followed by ongoing real-time or scheduled syncs.
  </Step>
</Steps>

***

## Schema Creation Process

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

<AccordionGroup>
  <Accordion title="Step 1: You Provide Sample Data" icon="file-code" defaultOpen>
    Send Reach example JSON objects of your key business records as they exist in your system:

    ```json Example Customer Record theme={null}
    {
      "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"]
    }
    ```

    ```json Example Transaction Record theme={null}
    {
      "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
        }
      ]
    }
    ```

    <Info>
      Send real examples from your database—not idealized versions. Include all fields, even optional ones.
    </Info>
  </Accordion>

  <Accordion title="Step 2: Reach Creates Custom Schemas" icon="diagram-project">
    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.
  </Accordion>

  <Accordion title="Step 3: Reach Maps Critical Fields" icon="map">
    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.
  </Accordion>

  <Accordion title="Step 4: You Get Schema-Specific Endpoints" icon="link">
    Reach provisions endpoints that accept your format:

    ```bash theme={null}
    POST /api/resources/contacts
    POST /api/resources/transactions
    POST /api/resources/locations
    ```

    Each endpoint accepts your JSON structure directly—no reformatting needed.
  </Accordion>
</AccordionGroup>

***

## What Data You'll Send

### Minimum Required Data

<Tabs>
  <Tab title="Customer/Contact 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

    ```json Complete Example theme={null}
    {
      "externalId": "customer_789",
      "email": "jane@example.com",
      "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
    }
    ```
  </Tab>

  <Tab title="Transaction/Billing Data">
    ### 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

    ```json Transaction Example theme={null}
    {
      "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
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Location Data">
    ### 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

    ```json Location Example theme={null}
    {
      "externalId": "loc_001",
      "name": "Downtown Portland Office",
      "address": {
        "street": "789 SW Broadway",
        "city": "Portland",
        "state": "OR",
        "zip": "97205"
      },
      "phone": "+15035551000",
      "googleBusinessProfileId": "ChIJ..."
    }
    ```

    <Info>
      Skip this if you're only using Measure/Acquire or if your customers are single-location businesses.
    </Info>
  </Tab>
</Tabs>

***

## Key Decision: What Counts as a Transaction?

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

<CardGroup cols={3}>
  <Card title="Booking-Based" icon="calendar-check">
    **When**: Customer schedules/reserves

    **Pros**:

    * Shows impact quickly
    * Captures intent early

    **Cons**:

    * Not actual revenue yet
    * May include cancellations
  </Card>

  <Card title="Payment-Based" icon="credit-card">
    **When**: Customer pays

    **Pros**:

    * Actual revenue
    * Most accurate attribution

    **Cons**:

    * Longer attribution window
    * Delayed insights
  </Card>

  <Card title="Invoice-Based" icon="file-invoice">
    **When**: Invoice is issued

    **Pros**:

    * Describes the sale
    * Works for B2B/net-terms

    **Cons**:

    * May not reflect actual payment
    * Requires status updates
  </Card>
</CardGroup>

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

***

## How You'll Send Data

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

<Tabs>
  <Tab title="Real-Time API">
    ### 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 segmentation

    **How it works**:

    ```javascript theme={null}
    // 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)
  </Tab>

  <Tab title="Batch API">
    ### 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 volumes

    **How it works**:

    ```javascript theme={null}
    // 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
  </Tab>

  <Tab title="Database Access">
    ### Reach Queries Your Database

    Grant Reach read-only access to a database view. Reach queries on a schedule to pull new records.

    **Best for**: Partners who prefer minimal integration work or need to backfill historical data quickly

    **How it works**:

    1. Create read-only database views for customers, transactions, etc.
    2. Provide Reach with database credentials (read-only user)
    3. Reach queries on schedule (hourly, daily, etc.)
    4. No code changes required in your application

    **Pros**:

    * Minimal integration effort
    * Easy historical backfill
    * Reach manages sync infrastructure

    **Cons**:

    * Security consideration (database access)
    * Less real-time than API methods
    * Requires database view creation
  </Tab>

  <Tab title="CSV Import">
    ### One-Time File Upload

    Provide Reach with CSV files of your data to be imported.

    **Best for**: One-time imports if batch processing or database access are not options

    **How it works**:

    1. Export data from your system as CSV
    2. Send to Reach team via secure transfer
    3. Reach imports and maps to schemas

    **Pros**:

    * Simple for one-time needs
    * No integration required

    **Cons**:

    * Not suitable for ongoing sync
    * Manual process
    * Requires file preparation
  </Tab>
</Tabs>

### 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

<Tip>
  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.
</Tip>

***

## Phase 4: Ongoing Data Sync

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

### Your Responsibilities

<Steps>
  <Step title="Implement your chosen sync method">
    Set up real-time hooks, batch jobs, or database views based on your decision.
  </Step>

  <Step title="Start sending data to Reach">
    Begin with historical backfill, then ongoing syncs for new/updated records.
  </Step>

  <Step title="Keep data flowing">
    Ensure customers and transactions sync as they're created/updated in your system.
  </Step>

  <Step title="Send status updates">
    Update transactions when they change status (refunded, canceled, modified).
  </Step>
</Steps>

### 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

<Warning>
  **Keep Reach's Data in Sync**

  Whether 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
</Warning>

<Info>
  **Using External IDs**

  When 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.
</Info>

***

## Data Sync Checklist

<Check>**Sample data sent to Reach** - Real examples of customers, transactions, locations</Check>
<Check>**Schemas defined** - Reach has created schemas matching your structure</Check>
<Check>**Sync method chosen** - Real-time API, Batch API, Database Access, or hybrid</Check>
<Check>**Endpoints or access provisioned** - You have what you need to send data</Check>
<Check>**Historical import complete** - Existing data backfilled</Check>
<Check>**Ongoing sync implemented** - New/updated records flow automatically</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Channel Setup" icon="envelope" href="/onboarding/channel-setup">
    Phase 5: Configure email & SMS (Engage only)
  </Card>

  <Card title="Tracking Setup" icon="code" href="/onboarding/tracking">
    Phase 8: Implement attribution snippet (Acquire/Measure)
  </Card>

  <Card title="Integration Checklist" icon="clipboard-check" href="/onboarding/integration-checklist">
    Full implementation checklist
  </Card>

  <Card title="API Documentation" icon="book" href="/api-reference/introduction">
    Detailed API reference
  </Card>
</CardGroup>