> ## Documentation Index > Fetch the complete documentation index at: https://docs.finosu.com/llms.txt > Use this file to discover all available pages before exploring further. # Customer Schedule Sync > Sync customer schedule by creating or updating customer and recreating their call schedule. This endpoint is idempotent. ## 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](/api-reference/introduction#authentication) for details. ## Request Body The request accepts largely the same fields as the Create Customer endpoint, with the same validations. It does not accept `loanIds`. This endpoint is **not** affected by the [upcoming Create Customer contract changes](/api-reference/upcoming-changes) — its required fields and its `test` and `loanId` parameters are unchanged. ### Always Required * `id` - External customer reference ID **(required)** * `firstName` - Customer's first name **(required)** * `lastName` - Customer's last name **(required)** * `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 **(required)** ### Required unless `sync: true` * `email` - Customer email address **(required)** * `streetAddress1` - Street address line 1 **(required)** * `city` - City name **(required)** * `state` - State code (e.g., "NY", "CA") **(required)** * `zipCode` - ZIP/postal code **(required)** ### Optional Fields * `birthday` - Customer birthday (YYYY-MM-DD format) * `ssnLastFour` - Last 4 digits of SSN * `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 * `loanId` - LMS loan ID, stored on the created tasks so call outcomes can be written back against the right loan * `sync` - When `true`, auto-fetch missing customer data from your company's LMS (default: `false`). See the [Create Customer endpoint](/api-reference/endpoint/customers/create#lms-auto-fetch-sync) for details. ## 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 ## OpenAPI ````yaml POST /customers/schedule/sync openapi: 3.1.0 info: title: Finosu API description: Finosu API license: name: MIT version: 1.0.0 servers: [] security: - apiKeyAuth: [] paths: /customers/schedule/sync: post: description: >- Sync customer schedule by creating or updating customer and recreating their call schedule. This endpoint is idempotent. requestBody: description: Customer data to sync content: application/json: schema: $ref: '#/components/schemas/SyncCustomerSchedule' required: true responses: '200': description: Customer schedule synced successfully content: application/json: schema: $ref: '#/components/schemas/SyncScheduleResponse' '400': description: Validation error or customer has Do Not Call status content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SyncCustomerSchedule: description: >- Customer data for the schedule sync endpoint. This endpoint is NOT affected by the upcoming Create Customer contract change. required: - id - taskType - firstName - lastName - phoneNumber - timezone type: object properties: id: description: >- Unique identifier for the customer. This is your customer reference and should match your internal system's ID. type: string firstName: description: The first name of the customer type: string lastName: description: The last name of the customer type: string email: description: Customer email address. Required unless sync is true. type: string format: email example: john.doe@example.com birthday: description: Customer birthday in YYYY-MM-DD format type: string format: date example: '1985-06-15' ssnLastFour: description: Last 4 digits of SSN type: string example: '1234' timezone: description: >- Timezone of the customer (IANA timezone name, e.g., 'America/New_York', 'America/Los_Angeles'). Required for TCPA compliance so calls are placed during permitted hours. type: string phoneNumber: description: Phone number of the customer type: string streetAddress1: description: Street address line 1. Required unless sync is true. type: string example: 123 Main St streetAddress2: description: Street address line 2 (optional) type: string example: Apt 4B city: description: City. Required unless sync is true. type: string example: San Francisco state: description: State code. Required unless sync is true. type: string example: CA zipCode: description: ZIP/postal code. Required unless sync is true. type: string example: '94102' doNotCall: description: >- Do not call the customer. If omitted, the existing value is preserved. type: boolean test: description: Mark customer as test customer type: boolean default: false taskType: description: >- Type of tasks to create for the customer's automated call schedule. Valid values depend on company configuration. type: string example: collections externalMetadata: description: >- Additional custom metadata about the customer (e.g. employer information, pay schedule, additional contact details) type: object sync: type: boolean default: false description: >- When true, auto-fetch missing customer data from your integrated lending system. Defaults to false. loanId: type: string description: >- Loan reference ID from your lending system, stored on the created tasks so call outcomes can be written back against the right loan. SyncScheduleResponse: type: object required: - id - firstName - lastName - scheduleCreated - tasksCreated - existingTasksRemoved properties: id: description: Customer ID (reference_id) type: string firstName: description: Customer's first name type: string lastName: description: Customer's last name type: string email: description: Customer email address type: string format: email birthday: description: Customer birthday in YYYY-MM-DD format type: string format: date ssnLastFour: description: Last 4 digits of SSN type: string timezone: description: >- Timezone of the customer (IANA timezone name, e.g., 'America/New_York', 'America/Los_Angeles') type: string phoneNumber: description: Phone number of the customer type: string streetAddress1: description: Street address line 1 type: string streetAddress2: description: Street address line 2 (optional) type: string city: description: City name type: string state: description: State code (e.g., NY, CA) type: string zipCode: description: ZIP/postal code type: string doNotCall: description: Do not call the customer type: boolean isTest: description: Indicates if this is a test customer type: boolean taskType: description: Type of tasks created for the customer's automated call schedule type: string externalMetadata: description: Additional custom metadata about the customer type: object scheduleCreated: description: Whether a new schedule was created during this sync operation type: boolean example: true tasksCreated: description: Number of new tasks created as part of the schedule type: integer example: 1 existingTasksRemoved: description: >- Number of pending tasks that were removed before creating the new schedule type: integer example: 3 Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key ````