Create Customers (Batch)

Overview

This batch endpoint allows you to create multiple customers in a single API request for improved efficiency. Each customer in the batch is processed independently with detailed individual results, 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

Response Format

The batch endpoint returns detailed results for each customer processed:

{
  "success": true,
  "total_processed": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "success": true,
      "id": "CUST123",
      "message": "Customer created successfully",
      "customer": {
        "id": "CUST123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "birthday": "1990-01-15",
        "ssnLastFour": "1234",
        "timezone": "America/New_York",
        "phoneNumber": "+15551234567",
        "doNotCall": false,
        "isTest": false,
        "taskType": "Collections",
        "externalMetadata": {
          "employer": "Acme Corp",
          "paySchedule": "biweekly"
        },
        "streetAddress1": "123 Main St",
        "streetAddress2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "zipCode": "10001"
      }
    },
    {
      "success": true,
      "id": "CUST124",
      "message": "Customer created successfully",
      "customer": {
        "id": "CUST124",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "[email protected]",
        "birthday": "1985-05-20",
        "ssnLastFour": "5678",
        "timezone": "America/Los_Angeles",
        "phoneNumber": "+15559876543",
        "doNotCall": false,
        "isTest": false,
        "taskType": "Collections",
        "streetAddress1": "456 Oak Ave",
        "streetAddress2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zipCode": "90001"
      }
    }
  ]
}

Response Fields

success - true if ALL customers were created successfully, false if any failed
total_processed - Total number of customers in the batch
successful - Number of successfully created customers
failed - Number of failed customer creations
results - Array of individual results for each customer
- success - Whether this specific customer was created successfully
- id - The customer ID from the request for easy matching
- message - Success or error message for this specific customer
- customer - Full customer data if creation was successful, null if failed

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 error messages - Each failed customer includes its specific error message
Transaction isolation - Each customer is processed in its own transaction to prevent one failure from affecting others
Overall success flag - The top-level success field is true only if all customers succeeded

Example: Partial Failure Response

{
  "success": false,
  "total_processed": 3,
  "successful": 2,
  "failed": 1,
  "results": [
    {
      "success": true,
      "id": "CUST123",
      "message": "Customer created successfully",
      "customer": {
        "id": "CUST123",
        "firstName": "John",
        "lastName": "Doe",
        ...
      }
    },
    {
      "success": false,
      "id": "CUST124",
      "message": "400: Customer with ID CUST124 already exists",
      "customer": null
    },
    {
      "success": true,
      "id": "CUST125",
      "message": "Customer created successfully",
      "customer": {
        "id": "CUST125",
        "firstName": "Bob",
        "lastName": "Johnson",
        ...
      }
    }
  ]
}

What the Endpoint Does

For each customer in the batch, Finosu:

Validates the customer data - Checks required fields, state restrictions, and task type validity
Checks for duplicates - Verifies the customer ID doesn’t already exist
Creates the customer - Stores customer information in the database
Creates call schedule - For supported task types (e.g., Collections), creates the appropriate call schedule
Returns customer data - Includes all customer fields in the response

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 200 OK for all requests, with detailed success/failure information in the response body for each individual customer. Individual customer errors 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

Check the results array in the response to see which customers succeeded and which failed.

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

customers.id

string

required

Unique identifier for the customer. This is your customer reference and should match your internal system's ID.

customers.firstName

string

required

The first name of the customer

customers.lastName

string

required

The last name of the customer

customers.email

string<email>

required

Customer email address

Example:

"[email protected]"

customers.birthday

string<date>

required

Customer birthday in YYYY-MM-DD format

Example:

"1985-06-15"

customers.streetAddress1

string

required

Street address line 1 (required)

Example:

"123 Main St"

customers.city

string

required

City (required)

Example:

"San Francisco"

customers.state

string

required

State code (required)

Example:

"CA"

customers.zipCode

string

required

ZIP/postal code (required)

Example:

"94102"

customers.taskType

string

required

Type of tasks to create for the customer's automated call schedule. Valid values depend on company configuration. This field is required.

Example:

"collections"

customers.ssnLastFour

string

Last 4 digits of SSN

Example:

"1234"

customers.timezone

string

Timezone of the customer (IANA timezone name, e.g., 'America/New_York', 'America/Los_Angeles')

customers.phoneNumber

string

Phone number of the customer

customers.streetAddress2

string

Street address line 2 (optional)

Example:

"Apt 4B"

customers.doNotCall

boolean

Do not call the customer

customers.isTest

boolean

Indicates if this is a test customer

customers.test

boolean

default:false

Mark customer as test customer

customers.externalMetadata

object

Additional custom metadata about the customer (e.g. employer information, pay schedule, additional contact details)

Show child attributes

customers.externalMetadata.home_phone

string

Example:

"+14155555555"

customers.externalMetadata.cell_phone

string

Example:

"+14155556666"

customers.externalMetadata.employer_name

string

Example:

"Acme Corporation"

customers.externalMetadata.employer_address

string

Example:

"456 Business Ave"

customers.externalMetadata.employer_city

string

Example:

"San Francisco"

customers.externalMetadata.employer_state

string

Example:

"CA"

customers.externalMetadata.employer_zip

string

Example:

"94103"

customers.externalMetadata.employer_department

string

Example:

"Sales"

customers.externalMetadata.employer_phone

string

Example:

"+14155557777"

customers.externalMetadata.employer_direct_line

string

Example:

"+14155558888"

customers.externalMetadata.pay_frequency

string

Example:

"biweekly"

customers.externalMetadata.pay_day

string

Example:

"Friday"

Response

Batch processing completed (may include partial failures - check individual results)

success

boolean

True if ALL customers were created successfully, false if any failed

Example:

true

total_processed

integer

Total number of customers in the batch

Example:

2

successful

integer

Number of successfully created customers

Example:

2

failed

integer

Number of failed customer creations

Example:

0

results

object[]

Individual results for each customer

Show child attributes

results.success

boolean

Whether this specific customer was created successfully

results.id

string

The customer ID from the request for easy matching

results.message

string

Success or error message for this specific customer

results.customer

object

Full customer data if creation was successful, null if failed

Show child attributes

results.customer.firstName

string

required

The first name of the customer

results.customer.lastName

string

required

The last name of the customer

results.customer.id

string

Unique identifier for the customer. This is your customer reference and should match your internal system's ID.

results.customer.email

string<email>

Customer email address

results.customer.birthday

string<date>

Customer birthday in YYYY-MM-DD format

results.customer.ssnLastFour

string

Last 4 digits of SSN

results.customer.timezone

string

Timezone of the customer (IANA timezone name, e.g., 'America/New_York', 'America/Los_Angeles')

results.customer.phoneNumber

string

Phone number of the customer

results.customer.streetAddress1

string

Street address line 1

results.customer.streetAddress2

string

Street address line 2 (optional)

results.customer.city

string

City name

results.customer.state

string

State code (e.g., NY, CA)

results.customer.zipCode

string

ZIP/postal code

results.customer.doNotCall

boolean

Do not call the customer

results.customer.isTest

boolean

Indicates if this is a test customer

results.customer.taskType

string

Type of tasks created for the customer's automated call schedule

results.customer.externalMetadata

object

Additional custom metadata about the customer

API Documentation

Endpoint Examples

Create Customers (Batch)

Overview

Request Body Format

Individual Customer Schema

Response Format

Response Fields

Partial Success Handling

Example: Partial Failure Response

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

​Partial Success Handling

​Example: Partial Failure Response

​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

Partial Success Handling

Example: Partial Failure Response

What the Endpoint Does

When to Use Batch vs Single

Error Handling

Authentication

Example Usage