Create Customers (Batch)

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.

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:

Queues the job - Stores customer data and creates a background job
Returns immediately - Returns HTTP 202 with job ID for status tracking
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

Show child attributes

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

API Documentation

Endpoint Examples

Create Customers (Batch)

Overview

Request Body Format

Individual Customer Schema

Response Format

Response Fields

Checking Job Status

Status Values

Partial Success Handling

What the Endpoint Does

When to Use Batch vs Single

Error Handling

Authentication

Example Usage

Authorizations

Body

Response

API Documentation

Endpoint Examples

​Overview

​Request Body Format

​Individual Customer Schema

​Response Format

​Response Fields

​Checking Job Status

​Status Values

​Partial Success Handling

​What the Endpoint Does

​When to Use Batch vs Single

​Error Handling

​Authentication

​Example Usage

Authorizations

Body

Response

Overview

Request Body Format

Individual Customer Schema

Response Format

Response Fields

Checking Job Status

Status Values

Partial Success Handling

What the Endpoint Does

When to Use Batch vs Single

Error Handling

Authentication

Example Usage