Create Customer

cURL

curl --request POST \
  --url https://api.example.com/customers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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>"
}
'

{
  "firstName": "<string>",
  "lastName": "<string>",
  "id": "<string>",
  "email": "[email protected]",
  "birthday": "2023-12-25",
  "ssnLastFour": "<string>",
  "timezone": "<string>",
  "phoneNumber": "<string>",
  "streetAddress1": "<string>",
  "streetAddress2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zipCode": "<string>",
  "doNotCall": true,
  "isTest": true,
  "taskType": "<string>",
  "externalMetadata": {}
}

POST

customers

cURL

curl --request POST \
  --url https://api.example.com/customers \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "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>"
}
'

{
  "firstName": "<string>",
  "lastName": "<string>",
  "id": "<string>",
  "email": "[email protected]",
  "birthday": "2023-12-25",
  "ssnLastFour": "<string>",
  "timezone": "<string>",
  "phoneNumber": "<string>",
  "streetAddress1": "<string>",
  "streetAddress2": "<string>",
  "city": "<string>",
  "state": "<string>",
  "zipCode": "<string>",
  "doNotCall": true,
  "isTest": true,
  "taskType": "<string>",
  "externalMetadata": {}
}

Response Body

The API returns all fields that were provided in the request body, along with any computed fields. 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

All fields that were included in the request will be returned in the response, making it easy to verify the customer was created correctly.

Required Fields

When creating a customer, the following fields are required: Name Fields:

firstName - Customer’s first name (required)
lastName - Customer’s last name (required)

Contact Information:

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.

Task Type:

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.

Address Information:

streetAddress1 - Street address line 1 (required)
city - City name (required)
state - State code (e.g., “NY”, “CA”) (required)
zipCode - ZIP/postal code (required)

Optional Address Fields:

streetAddress2 - Street address line 2

The API response will return all fields separately as they are stored in the database.

Test Customers

You can mark a customer as a test customer by setting the test parameter to true in the request body. Test customers are useful for development and testing purposes and can be filtered separately when retrieving customers.

External Metadata

The externalMetadata field allows you to store additional custom data about the customer as a JSON object. This is particularly useful for storing:

Employer Information: Company name, address, department, contact details
Pay Schedule: Pay frequency and pay day information
Additional Contact Information: Multiple phone numbers and contact methods
Custom Fields: Any other customer-specific data your system needs to track

The metadata is stored as-is in the database and can be retrieved later when processing customer tasks or making calls. AI agents can access this information during conversations.

LMS Auto-Fetch (sync)

If your company has a Loan Management System integrated with Finosu, you can use the sync field to automatically fetch customer data instead of providing it manually.

Default: false — all fields must be provided in the request
When true: The API uses the id field as the customer ID in your LMS and auto-fetches any missing fields (name, email, SSN, birthday, phone, address, zip, timezone)
Caller-supplied values take precedence — if you provide a field, the LMS value is not used
Timezone is auto-resolved from the zip code when not provided

Minimal request with sync:

{
  "id": "12345",
  "taskType": "YourTaskType",
  "loanId": "67890",
  "sync": true
}

This reduces the required payload to just id, taskType, and sync: true — the rest is fetched from your LMS automatically. Contact your Finosu account manager to enable LMS integration for your company.

Loan ID (Optional)

The loanId field (string) allows you to specify a single loan ID from your LMS for enrichment. This links the customer’s task to a specific loan in your system.

Loan IDs (Optional)

The loanIds field allows you to specify which loans should be imported for the customer when creating them:

Format: Array of integers (e.g., [123, 456, 789])
Behavior: If provided, only the specified loans will be fetched and imported. If omitted, all loans for the customer will be imported.
Use Case: Useful when you only want to import specific loans instead of all loans associated with the customer.

Authorizations

X-API-Key

string

header

required

Body

application/json

Customer to add

string

required

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

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"

firstName

string

The first name of the customer

lastName

string

The last name of the customer

string<email>

Customer email address

Example:

"[email protected]"

birthday

string<date>

Customer birthday in YYYY-MM-DD format

Example:

"1985-06-15"

ssnLastFour

string

Last 4 digits of SSN

Example:

"1234"

timezone

string

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

phoneNumber

string

Phone number of the customer

streetAddress1

string

Street address line 1

Example:

"123 Main St"

streetAddress2

string

Street address line 2 (optional)

Example:

"Apt 4B"

city

string

City

Example:

"San Francisco"

state

string

State code

Example:

"CA"

zipCode

string

ZIP/postal code

Example:

"94102"

doNotCall

boolean

Do not call the customer

isTest

boolean

Indicates if this is a test customer

test

boolean

default:false

Mark customer as test customer

externalMetadata

object

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

Show child attributes

loanIds

integer[]

Array of loan IDs to import. If provided, only these loans are imported. If omitted, all loans are imported.

Example:

[123, 456, 789]

sync

boolean

default:false

When true, auto-fetch missing customer data from your integrated lending system. Defaults to false.

loanId

string

Loan reference ID for enrichment. Distinct from loanIds which filters loan imports.

Response

Customer response

firstName

string

required

The first name of the customer

lastName

string

required

The last name of the customer

string

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

string<email>

Customer email address

birthday

string<date>

Customer birthday in YYYY-MM-DD format

ssnLastFour

string

Last 4 digits of SSN

timezone

string

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

phoneNumber

string

Phone number of the customer

streetAddress1

string

Street address line 1

streetAddress2

string

Street address line 2 (optional)

city

string

City name

state

string

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

zipCode

string

ZIP/postal code

doNotCall

boolean

Do not call the customer

isTest

boolean

Indicates if this is a test customer

taskType

string

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

externalMetadata

object

Additional custom metadata about the customer

Update Customer Create Customers (Batch)

​Response Body

​Required Fields

​Test Customers

​External Metadata

​LMS Auto-Fetch (sync)

​Loan ID (Optional)

​Loan IDs (Optional)

Authorizations

Body

Response

Response Body

Required Fields

Test Customers

External Metadata

LMS Auto-Fetch (sync)

Loan ID (Optional)

Loan IDs (Optional)