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

# LMS Customer Batch Sync

## Overview

Sync multiple customers and all their loans from your company's configured LMS in a single request.

The endpoint processes customers **asynchronously** — it immediately returns a job ID (HTTP 202 Accepted) and processes customers in the background. Use `GET /webhooks/lms/sync/batch/{jobId}` to check the processing status.

Each customer is processed independently. Individual failures do not block the rest.

## How It Works

1. You send a list of customer IDs from your LMS
2. Finosu returns a job ID immediately
3. In the background, for each customer ID:
   * Fetches customer info from your LMS (name, phone, email, SSN, address, etc.)
   * Creates or updates the customer in Finosu
   * Fetches all loans for that customer
   * Creates loan records and schedules as appropriate
4. You poll for status until the job completes

## Request Body Format

```json theme={null}
{
  "customerIds": ["12345", "67890", "11111"]
}
```

### Fields

* **customerIds** - Array of customer identifiers in your LMS **(required)**
  * Minimum: 1 ID
  * Maximum: 100 IDs per request
  * Each ID must be a non-empty string

## Response Format

The endpoint immediately returns HTTP 202 with a job ID:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalCustomers": 3,
  "message": "Batch sync queued. Use GET /webhooks/lms/sync/batch/550e8400-e29b-41d4-a716-446655440000 to check status."
}
```

### Response Fields

* **jobId** — Unique identifier for the batch job. Use this to poll for status.
* **totalCustomers** — Total number of customers queued for processing.
* **message** — Instructions for checking progress.

## Checking Job Status

Use `GET /webhooks/lms/sync/batch/{jobId}` to check progress:

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "totalCustomers": 3,
  "processed": 2,
  "failed": 0,
  "progressPercentage": 66.7,
  "createdAt": "2026-08-03T12:00:00Z",
  "processingStartedAt": "2026-08-03T12:00:01Z",
  "processingCompletedAt": null,
  "errorMessage": null
}
```

### Status Values

* **pending** — Job is queued but not yet started
* **processing** — Job is currently processing customers
* **completed** — All customers have been processed (some may have failed individually)
* **failed** — Job encountered a fatal error, or all customers failed

## Partial Success Handling

* **Individual failures don't stop processing** — If one customer fails (e.g., not found in your LMS), the rest continue
* **Detailed tracking** — The `failed` count shows how many customers could not be synced
* **Transaction isolation** — Each customer is processed in its own transaction

## When to Use Batch vs Single

**Use the batch endpoint when:**

* Syncing multiple customers from your LMS at once
* Performing initial data migration
* Running scheduled sync workflows
* You have more than a few customers to sync

**Use the [single endpoint](./sync-customer-full.mdx) when:**

* Syncing one customer in real-time (e.g., webhook from your LMS on application submission)
* Testing or debugging individual customer sync
* You need the sync result immediately in the response

## Comparison with POST /customers/batch

|                 | POST /customers/batch                                     | POST /webhooks/lms/sync/customer-full/batch |
| --------------- | --------------------------------------------------------- | ------------------------------------------- |
| **Input**       | Full customer payload (name, phone, email, address, etc.) | Just customer IDs from your LMS             |
| **Data source** | You provide all fields                                    | Finosu fetches from your LMS                |
| **Loans**       | Created separately via POST /loans                        | Automatically synced from your LMS          |
| **Schedules**   | Created based on taskType                                 | Automatically created based on loan status  |
| **Best for**    | Companies without an LMS integration                      | Companies with a configured LMS             |

## Error Handling

| Status  | Meaning                                               |
| ------- | ----------------------------------------------------- |
| **202** | Job queued successfully                               |
| **403** | Company not authorized for LMS integration            |
| **422** | Validation error (empty list, too many IDs, empty ID) |
| **500** | Failed to queue job                                   |

## Authentication

Requires **X-API-Key** header with a valid webhook API key. The key determines which company and LMS integration to use.

## Limits

* Maximum **100 customer IDs** per request
* Each customer ID must be a non-empty string