Skip to main content
POST
cURL

Upcoming Contract Changes

The required-field contract for this endpoint is changing. birthday and ssnLastFour (optional today) will become required; state (today required unless sync: true) becomes required in all cases; email/phoneNumber and timezone/zipCode become at-least-one pairs; and loanId is being removed in favor of loanIds. One part is already live: validation failures now return 422, as described below. The remaining request fields documented on this page reflect what is enforced today, and we will give partners ample time to adjust before introducing any breaking changes. See Upcoming API Changes for the new contract, the rationale, and migration examples.

Required Fields

Always required:
  • id - Your customer reference ID; should match your internal system’s ID (required)
  • 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 422 Unprocessable Content error with a list of valid task types.
Required unless sync: true (when sync is enabled these are auto-fetched from your LMS — see below):
  • email - Customer email address (required)
  • 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:
  • birthday - Customer birthday (YYYY-MM-DD format) - Used for identity verification on calls. Will become required — see Upcoming API Changes.
  • ssnLastFour - Last 4 digits of SSN - Used for identity verification on calls. Will become required — see Upcoming API Changes.
  • streetAddress2 - Street address line 2
  • doNotCall - Whether to mark customer for Do Not Call (default: false)
  • externalMetadata - Custom JSON object with additional customer data
  • loanIds - Array of loan IDs to import
Missing required fields return a 422 Unprocessable Content naming the fields, e.g. {"detail": "Missing required fields: firstName, timezone"}.

Existing Customers

If a customer with the same id already exists for your company, this endpoint updates that customer in place and still returns 201. Provided fields overwrite the stored values; omitted optional fields (including externalMetadata) are preserved.

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, doNotText, doNotEmail, 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. The API response will return all address fields separately as they are stored in the database.

Test Customers

You can mark a customer as a test customer by setting isTest to true in the request body. Test customers are useful for development and testing purposes and can be filtered separately when retrieving customers. The same field is returned as isTest on every customer response.

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 when omitted. An unresolvable ZIP defaults to America/New_York; if both timezone and ZIP are absent after fetching, the request returns 422 for missing timezone.
  • The id must be numeric when sync is true
Minimal request with sync:
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 IDs (Optional)

For companies with an LMS integration, the loanIds field specifies 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. To import exactly one loan, pass a single-element array (e.g., [67890]).

Loan ID (Deprecated)

The loanId field (string) is deprecated. It never selects loans to import — use loanIds for that, passing a single-element array for one loan. For origination-boarding records at companies explicitly configured for the supported LMS origination integration, loanId is read as the LMS application reference; on all other records it is ignored. It will be removed in a future update. See Upcoming API Changes.

Validation and LMS failures

Invalid caller-supplied birthday, phoneNumber, or timezone values return 422 for both new and existing customers. With sync: true, a failed LMS fetch or invalid contact data returned by the LMS returns 502, not 422. Malformed optional LMS birthdays are skipped; an existing birthday is preserved. Unexpected internal failures remain 500. A 5xx response does not guarantee that retrying a write is safe. Follow the operation’s idempotency behavior and use bounded retries; do not retry unchanged invalid input.

Authorizations

X-API-Key
string
header
required

Body

application/json

Customer to add

Customer creation payload. NOTE: the required-field contract for this endpoint is changing — see the Upcoming API Changes page (/api-reference/upcoming-changes) for the new contract.

id
string
required

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

firstName
string
required

The first name of the customer

lastName
string
required

The last name of the customer

timezone
string
required

Timezone of the customer (IANA timezone name, e.g., 'America/New_York', 'America/Los_Angeles'). Required for TCPA compliance so calls are placed during permitted hours. UPCOMING: at least one of timezone or zipCode will be required, and timezone will be derived from zipCode when omitted — see /api-reference/upcoming-changes.

phoneNumber
string
required

Phone number of the customer. UPCOMING: at least one of email or phoneNumber will be required — see /api-reference/upcoming-changes.

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"

email
string<email>

Customer email address. Required unless sync is true. UPCOMING: at least one of email or phoneNumber will be required — see /api-reference/upcoming-changes.

Example:

"[email protected]"

birthday
string<date>

Customer birthday in YYYY-MM-DD format. UPCOMING: this field will become required — see /api-reference/upcoming-changes.

Example:

"1985-06-15"

ssnLastFour
string

Last 4 digits of SSN. UPCOMING: this field will become required — see /api-reference/upcoming-changes.

Example:

"1234"

streetAddress1
string

Street address line 1. Required unless sync is true.

Example:

"123 Main St"

streetAddress2
string

Street address line 2 (optional)

Example:

"Apt 4B"

city
string

City. Required unless sync is true.

Example:

"San Francisco"

state
string

State code. Required unless sync is true. UPCOMING: this field will be required in all cases — see /api-reference/upcoming-changes.

Example:

"CA"

zipCode
string

ZIP/postal code. Required unless sync is true. UPCOMING: at least one of timezone or zipCode will be required — see /api-reference/upcoming-changes.

Example:

"94102"

doNotCall
boolean

Do not call the customer

isTest
boolean
default:false

Mark customer as test customer. Matches the isTest field returned on every customer response.

externalMetadata
object

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

loanIds
integer[]

Array of loan IDs to import. If provided, only these loans are imported. If omitted, all loans are imported. Pass a single-element array to import exactly one loan.

Example:
sync
boolean
default:false

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

loanId
string
deprecated

DEPRECATED — has no effect on this endpoint and will be removed in a future update. Pass the loan ID as a single-element loanIds array instead. See /api-reference/upcoming-changes.

Response

Customer response

id
string
required

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

firstName
string
required

The first name of the customer

lastName
string
required

The last name of the customer

email
string<email> | null

Customer email address

birthday
string<date> | null

Customer birthday in YYYY-MM-DD format

ssnLastFour
string | null

Last 4 digits of SSN

timezone
string | null

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

phoneNumber
string | null

Phone number of the customer

streetAddress1
string | null

Street address line 1

streetAddress2
string | null

Street address line 2 (optional)

city
string | null

City name

state
string | null

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

zipCode
string | null

ZIP/postal code

doNotCall
boolean | null

Do not call the customer

doNotText
boolean | null

Do not text the customer

doNotEmail
boolean | null

Do not email the customer

bankruptcy
boolean | null

Whether the customer has an active bankruptcy compliance status

debtConsolidation
boolean | null

Whether the customer has an active debt-management or debt-consolidation compliance status

deceased
boolean | null

Whether the customer has an active deceased compliance status

militaryStatus
boolean | null

Whether the customer has an active military or servicemember compliance status

legalThreat
boolean | null

Whether threatened legal action has been reported. This is not attorney representation and has no attorney-representation hold.

isTest
boolean | null

Indicates if this is a test customer

taskType
string | null

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

externalMetadata
object | null

Additional custom metadata about the customer