Customer Schedule Sync

{
  "id": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "scheduleCreated": true,
  "tasksCreated": 1,
  "existingTasksRemoved": 3,
  "email": "[email protected]",
  "birthday": "2023-12-25",
  "ssnLastFour": "<string>",
  "timezone": "<string>",
  "phoneNumber": "<string>",
  "streetAddress1": "<string>",
  "streetAddress2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zipCode": "<string>",
  "doNotCall": true,
  "isTest": true,
  "taskType": "<string>",
  "externalMetadata": {}
}

​

Overview

This endpoint provides an idempotent way to sync a customer’s call schedule. It will:

1. Create or update the customer with the provided data
2. Remove all pending tasks for the customer
3. Create a new call schedule based on the task type

Calling this endpoint multiple times with the same data will produce the same result, making it safe for retries and integration workflows.

​

Authentication

Authentication via X-API-Key header. See Authentication for details.

​

Request Body

The request accepts the same fields as the Create Customer endpoint, with all the same validations and requirements.

​

Required Fields

• id - External customer reference ID
• firstName - Customer’s first name
• lastName - Customer’s last name
• email - Customer email address
• birthday - Customer birthday (YYYY-MM-DD format)
• ssnLastFour - Last 4 digits of SSN
• phoneNumber - Customer’s phone number (required) - Used for automated calling and SMS communications
• timezone - Customer’s timezone as an IANA timezone name (e.g., “America/New_York”, “America/Los_Angeles”, “America/Chicago”) (required) - Required for TCPA compliance to ensure calls are made during appropriate hours. Must be a valid IANA timezone identifier.
• taskType - Task type for customer’s call schedule
• streetAddress1 - Street address line 1
• city - City name
• state - State code (e.g., “NY”, “CA”)
• zipCode - ZIP/postal code

​

Optional Fields

• doNotCall - Whether to mark customer for Do Not Call (optional; if not provided, existing value is preserved)
• test - Mark customer as test customer (default: false)
• externalMetadata - Custom JSON object with additional customer data
• streetAddress2 - Street address line 2

​

Response Body

The API returns all customer fields that were provided in the request body, along with any computed fields and sync operation metadata. This includes:

• Basic Information: id, firstName, lastName, email, phoneNumber, timezone
• Personal Information: birthday, ssnLastFour
• Address Information: streetAddress1, streetAddress2, city, state, zipCode
• Configuration: taskType, doNotCall, isTest
• Custom Data: externalMetadata - The complete metadata object you provided
• Sync Metadata: schedule_created, tasks_created, existing_tasks_removed - Information about the sync operation performed

All fields that were included in the request will be returned in the response, along with sync metadata that indicates what actions were taken during the sync operation.

​

Sync Metadata Fields

In addition to all the customer fields, the response includes three metadata fields that describe the sync operation:

• schedule_created (boolean): Whether a new schedule was created during this sync operation. This will be true if the customer has both a valid timezone and phone number, and false if either is missing.
• tasks_created (integer): The number of new tasks created as part of the schedule.
• existing_tasks_removed (integer): The number of pending tasks that were removed before creating the new schedule. This ensures a clean slate for the new schedule and prevents duplicate tasks.

​

Schedule Creation

The response will indicate whether the schedule was successfully created via the schedule_created field.

​

Do Not Call Validation

If an existing customer is already marked as Do Not Call, the endpoint will return a 400 error unless you explicitly set doNotCall: false in the request. Behavior:

• If doNotCall is not provided (omitted from request) and the customer has Do Not Call status → Error (prevents accidental schedule creation)
• If doNotCall: true and the customer has Do Not Call status → Error (attempting to maintain Do Not Call while creating schedule)
• If doNotCall: false and the customer has Do Not Call status → Success (explicitly removing Do Not Call and creating schedule)
• If doNotCall is not provided and the customer does NOT have Do Not Call status → Success (preserves existing state)

​

Idempotency

This endpoint is designed to be idempotent:

• If a customer with the given id exists, it will be updated
• All pending tasks are removed before creating the new schedule
• Calling the endpoint multiple times with the same data produces the same result
• Safe for retries in case of network failures or integration workflows

​

Use Cases

This endpoint is useful for:

• Re-syncing customer data from external systems
• Resetting call schedules after customer information changes
• Bulk customer updates where you want to ensure consistent state
• Integration workflows that need guaranteed idempotency