Create Customer

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.

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.

firstName

string

required

The first name of the customer

lastName

string

required

The last name of the customer

string<email>

required

Customer email address

Example:

"[email protected]"

birthday

string<date>

required

Customer birthday in YYYY-MM-DD format

Example:

"1985-06-15"

streetAddress1

string

required

Street address line 1 (required)

Example:

"123 Main St"

city

string

required

City (required)

Example:

"San Francisco"

state

string

required

State code (required)

Example:

"CA"

zipCode

string

required

ZIP/postal code (required)

Example:

"94102"

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"

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

streetAddress2

string

Street address line 2 (optional)

Example:

"Apt 4B"

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

externalMetadata.home_phone

string

Example:

"+14155555555"

externalMetadata.cell_phone

string

Example:

"+14155556666"

externalMetadata.employer_name

string

Example:

"Acme Corporation"

externalMetadata.employer_address

string

Example:

"456 Business Ave"

externalMetadata.employer_city

string

Example:

"San Francisco"

externalMetadata.employer_state

string

Example:

"CA"

externalMetadata.employer_zip

string

Example:

"94103"

externalMetadata.employer_department

string

Example:

"Sales"

externalMetadata.employer_phone

string

Example:

"+14155557777"

externalMetadata.employer_direct_line

string

Example:

"+14155558888"

externalMetadata.pay_frequency

string

Example:

"biweekly"

externalMetadata.pay_day

string

Example:

"Friday"

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

API Documentation

Endpoint Examples

Create Customer

Response Body

Required Fields

Test Customers

External Metadata

Authorizations

Body

Response

API Documentation

Endpoint Examples

​Response Body

​Required Fields

​Test Customers

​External Metadata

Authorizations

Body

Response

Response Body

Required Fields

Test Customers

External Metadata