Skip to main content
POST
/
customers
/
batch
cURL
curl --request POST \
  --url https://api.example.com/customers/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "customers": [
    {
      "id": "<string>",
      "taskType": "collections",
      "firstName": "<string>",
      "lastName": "<string>",
      "email": "[email protected]",
      "birthday": "1985-06-15",
      "ssnLastFour": "1234",
      "timezone": "<string>",
      "phoneNumber": "<string>",
      "streetAddress1": "123 Main St",
      "streetAddress2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "zipCode": "94102",
      "doNotCall": true,
      "isTest": true,
      "test": false,
      "externalMetadata": {
        "home_phone": "+14155555555",
        "cell_phone": "+14155556666",
        "employer_name": "Acme Corporation",
        "employer_address": "456 Business Ave",
        "employer_city": "San Francisco",
        "employer_state": "CA",
        "employer_zip": "94103",
        "employer_department": "Sales",
        "employer_phone": "+14155557777",
        "employer_direct_line": "+14155558888",
        "pay_frequency": "biweekly",
        "pay_day": "Friday"
      },
      "loanIds": [
        123,
        456,
        789
      ],
      "sync": false,
      "loanId": "<string>"
    }
  ]
}
'
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalCustomers": 100,
  "message": "Batch job created with 4 parallel batches. Use GET /customers/batch/550e8400-e29b-41d4-a716-446655440000 to check status."
}

​
Overview

This batch endpoint allows you to create multiple customers in a single API request for improved efficiency. The endpoint processes customers asynchronously - it immediately returns a job ID (HTTP 202 Accepted) and processes customers in the background. Use GET /customers/batch/{jobId} to check the processing status. Each customer in the batch is processed independently, making it ideal for bulk customer imports from your LMS system or initial data migration.

​
Request Body Format

The batch endpoint accepts an array of customer records wrapped in a customers field: 
{
  "customers": [
    {
      "id": "CUST123",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "birthday": "1990-01-15",
      "ssnLastFour": "1234",
      "phoneNumber": "+15551234567",
      "timezone": "America/New_York",
      "taskType": "Collections",
      "streetAddress1": "123 Main St",
      "streetAddress2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zipCode": "10001",
      "doNotCall": false,
      "test": false,
      "externalMetadata": {
        "employer": "Acme Corp",
        "paySchedule": "biweekly"
      }
    },
    {
      "id": "CUST124",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "birthday": "1985-05-20",
      "ssnLastFour": "5678",
      "phoneNumber": "+15559876543",
      "timezone": "America/Los_Angeles",
      "taskType": "Collections",
      "streetAddress1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zipCode": "90001",
      "doNotCall": false,
      "test": false
    }
  ]
}

​
Individual Customer Schema

Each object in the customers array follows the same schema as the single customer endpoint: Required Fields:
  • id - External customer reference ID
  • 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) - Valid task types depend on your company configuration. If an invalid task type is provided for your company, the API will return a 400 Bad Request error with a list of valid task types.
  • 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:
  • email - Customer email address
  • birthday - Customer birthday (YYYY-MM-DD format)
  • ssnLastFour - Last 4 digits of SSN
  • streetAddress2 - Street address line 2
  • doNotCall - Whether to mark customer for Do Not Call (default: false)
  • test - Mark customer as test customer (default: false)
  • externalMetadata - Custom JSON object with additional customer data
  • loanIds - Array of loan IDs to import for the customer (e.g., [123, 456, 789]). If provided, only the specified loans will be imported. If omitted, all loans for the customer will be imported.
  • loanId - LMS loan ID for enrichment (string)
  • sync - When true, auto-fetch missing customer data from your company’s LMS (default: false). See the Create Customer endpoint for details.

​
Response Format

The batch endpoint immediately returns a job ID for tracking: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalCustomers": 100,
  "message": "Batch job created with 4 parallel batches. Use GET /customers/batch/550e8400-e29b-41d4-a716-446655440000 to check status."
}

​
Response Fields

  • jobId - Unique identifier for the batch job. Use this to check status via GET /customers/batch/{jobId}
  • totalCustomers - Total number of customers queued for processing
  • message - Status message with instructions for checking progress

​
Checking Job Status

Use GET /customers/batch/{jobId} to check the processing status: 
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "totalCustomers": 100,
  "processed": 75,
  "failed": 2,
  "progressPercentage": 75.0,
  "createdAt": "2024-01-15T10:30:00Z",
  "processingStartedAt": "2024-01-15T10:30:05Z",
  "processingCompletedAt": null,
  "errorMessage": null
}

​
Status Values

  • pending - Job is queued but not yet started
  • processing - Job is currently processing customers
  • completed - Job has finished processing all customers
  • failed - Job encountered a fatal error

​
Partial Success Handling

The batch endpoint uses partial success handling to ensure maximum processing:
  • Individual failures don’t stop processing - If one customer fails, the remaining customers are still processed
  • Detailed tracking - The failed count in job status shows how many customers failed
  • Transaction isolation - Each customer is processed in its own transaction to prevent one failure from affecting others

​
What the Endpoint Does

When you submit a batch request, Finosu:
  1. Queues the job - Stores customer data and creates a background job
  2. Returns immediately - Returns HTTP 202 with job ID for status tracking
  3. Processes asynchronously - For each customer in parallel batches:
    • Validates the customer data (required fields, state restrictions, task type)
    • Checks for duplicates (verifies customer ID doesn’t already exist)
    • Creates the customer in the database
    • Creates call schedule for supported task types (e.g., Collections)

​
When to Use Batch vs Single

Use the batch endpoint when:
  • Importing multiple customers from your LMS system
  • Performing initial data migration
  • You have more than 5-10 customers to create
  • You want to minimize API calls for efficiency
Use the single endpoint when:
  • Creating individual customers in real-time
  • You only have 1-2 customers to create
  • You need simpler error handling
  • Testing or debugging individual customer creation

​
Error Handling

The endpoint returns HTTP status 202 Accepted for all requests, with a job ID that can be used to check processing status via GET /customers/batch/{job_id}. Individual customer errors during processing may include:
  • 400 BAD REQUEST - Missing required fields, invalid task type, duplicate customer ID, or state restrictions
  • 500 INTERNAL SERVER ERROR - Server error during processing
Use GET /customers/batch/{jobId} to monitor the processed and failed counts during processing.

​
Authentication

Authentication via X-API-Key header:
  • API key is company-scoped
  • Must be obtained from Finosu
  • Same authentication as single customer endpoint

​
Example Usage

This endpoint is typically used for:
  • Bulk customer import - Import multiple customers from your loan management system
  • Initial setup - Create multiple customers during initial platform setup
  • Scheduled jobs - Automated daily/weekly customer sync workflows
  • Data migration - Migrate customer data from legacy systems

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Batch of customer records

​
customers
object[]
required

Array of customer records to create

Response

Batch job accepted for async processing. Use GET /customers/batch/{jobId} to check status.

​
jobId
string

Unique identifier for the batch job. Use this to check status via GET /customers/batch/{jobId}

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
totalCustomers
integer

Total number of customers queued for processing

Example:

100

​
message
string

Status message with instructions for checking progress

Example:

"Batch job created with 4 parallel batches. Use GET /customers/batch/550e8400-e29b-41d4-a716-446655440000 to check status."