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>",
  "firstName": "<string>",
  "lastName": "<string>",
  "timezone": "<string>",
  "phoneNumber": "<string>",
  "taskType": "collections",
  "email": "[email protected]",
  "birthday": "1985-06-15",
  "ssnLastFour": "1234",
  "streetAddress1": "123 Main St",
  "streetAddress2": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94102",
  "doNotCall": 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>"
}
'

import requests

url = "https://api.example.com/customers"

payload = {
    "id": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "timezone": "<string>",
    "phoneNumber": "<string>",
    "taskType": "collections",
    "email": "[email protected]",
    "birthday": "1985-06-15",
    "ssnLastFour": "1234",
    "streetAddress1": "123 Main St",
    "streetAddress2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "doNotCall": 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>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: '<string>',
    firstName: '<string>',
    lastName: '<string>',
    timezone: '<string>',
    phoneNumber: '<string>',
    taskType: 'collections',
    email: '[email protected]',
    birthday: '1985-06-15',
    ssnLastFour: '1234',
    streetAddress1: '123 Main St',
    streetAddress2: 'Apt 4B',
    city: 'San Francisco',
    state: 'CA',
    zipCode: '94102',
    doNotCall: 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>'
  })
};

fetch('https://api.example.com/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'timezone' => '<string>',
    'phoneNumber' => '<string>',
    'taskType' => 'collections',
    'email' => '[email protected]',
    'birthday' => '1985-06-15',
    'ssnLastFour' => '1234',
    'streetAddress1' => '123 Main St',
    'streetAddress2' => 'Apt 4B',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zipCode' => '94102',
    'doNotCall' => 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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/customers"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/customers")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "firstName": "<string>",
  "lastName": "<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": {}
}

{
  "error": 123,
  "message": "<string>"
}

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>",
  "firstName": "<string>",
  "lastName": "<string>",
  "timezone": "<string>",
  "phoneNumber": "<string>",
  "taskType": "collections",
  "email": "[email protected]",
  "birthday": "1985-06-15",
  "ssnLastFour": "1234",
  "streetAddress1": "123 Main St",
  "streetAddress2": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "zipCode": "94102",
  "doNotCall": 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>"
}
'

import requests

url = "https://api.example.com/customers"

payload = {
    "id": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "timezone": "<string>",
    "phoneNumber": "<string>",
    "taskType": "collections",
    "email": "[email protected]",
    "birthday": "1985-06-15",
    "ssnLastFour": "1234",
    "streetAddress1": "123 Main St",
    "streetAddress2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "doNotCall": 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>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    id: '<string>',
    firstName: '<string>',
    lastName: '<string>',
    timezone: '<string>',
    phoneNumber: '<string>',
    taskType: 'collections',
    email: '[email protected]',
    birthday: '1985-06-15',
    ssnLastFour: '1234',
    streetAddress1: '123 Main St',
    streetAddress2: 'Apt 4B',
    city: 'San Francisco',
    state: 'CA',
    zipCode: '94102',
    doNotCall: 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>'
  })
};

fetch('https://api.example.com/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'id' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'timezone' => '<string>',
    'phoneNumber' => '<string>',
    'taskType' => 'collections',
    'email' => '[email protected]',
    'birthday' => '1985-06-15',
    'ssnLastFour' => '1234',
    'streetAddress1' => '123 Main St',
    'streetAddress2' => 'Apt 4B',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zipCode' => '94102',
    'doNotCall' => 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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/customers"

	payload := strings.NewReader("{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/customers")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"taskType\": \"collections\",\n  \"email\": \"[email protected]\",\n  \"birthday\": \"1985-06-15\",\n  \"ssnLastFour\": \"1234\",\n  \"streetAddress1\": \"123 Main St\",\n  \"streetAddress2\": \"Apt 4B\",\n  \"city\": \"San Francisco\",\n  \"state\": \"CA\",\n  \"zipCode\": \"94102\",\n  \"doNotCall\": true,\n  \"test\": false,\n  \"externalMetadata\": {\n    \"home_phone\": \"+14155555555\",\n    \"cell_phone\": \"+14155556666\",\n    \"employer_name\": \"Acme Corporation\",\n    \"employer_address\": \"456 Business Ave\",\n    \"employer_city\": \"San Francisco\",\n    \"employer_state\": \"CA\",\n    \"employer_zip\": \"94103\",\n    \"employer_department\": \"Sales\",\n    \"employer_phone\": \"+14155557777\",\n    \"employer_direct_line\": \"+14155558888\",\n    \"pay_frequency\": \"biweekly\",\n    \"pay_day\": \"Friday\"\n  },\n  \"loanIds\": [\n    123,\n    456,\n    789\n  ],\n  \"sync\": false,\n  \"loanId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "firstName": "<string>",
  "lastName": "<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": {}
}

{
  "error": 123,
  "message": "<string>"
}

Upcoming Contract Changes

The required-field contract for this endpoint is changing. birthday, ssnLastFour, and state will become required; email/phoneNumber and timezone/zipCode become at-least-one pairs; and test and loanId are being removed in favor of isTest and loanIds. Nothing below has changed yet — the fields documented on this page reflect what is enforced today. 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 400 Bad Request 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 400 Bad Request naming the fields, e.g. {"detail": "Missing required fields: firstName, timezone"}.

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. 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 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. test is deprecated and will be replaced by isTest (which is what the response already returns). Note that isTest is not yet accepted on the request — sending it today has no effect and would create a non-test customer, so keep using test until you are notified that the change is live. See Upcoming API Changes.

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
The id must be numeric when sync is true

Minimal request with sync:

{
  "id": "12345",
  "taskType": "YourTaskType",
  "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 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. To import exactly one loan, pass a single-element array (e.g., [67890]).

Loan ID (Deprecated)

The loanId field (string) is deprecated and has no effect on this endpoint — it is accepted and then ignored. It will be removed in a future update. Use loanIds instead, passing a single-element array for one loan. See Upcoming API Changes.

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.

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"

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

test

boolean

default:false

deprecated

DEPRECATED — mark customer as test customer. This field will be removed in a future update; use isTest instead once the change is live. See /api-reference/upcoming-changes.

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. Pass a single-element array to import exactly one loan.

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

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

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>

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)

API Documentation

Endpoint Examples

Create Customer

Upcoming Contract Changes

Required Fields

Response Body

Test Customers

External Metadata

LMS Auto-Fetch (sync)

Loan IDs (Optional)

Loan ID (Deprecated)

Authorizations

Body

Response

​Upcoming Contract Changes

​Required Fields

​Response Body

​Test Customers

​External Metadata

​LMS Auto-Fetch (sync)

​Loan IDs (Optional)

​Loan ID (Deprecated)

Authorizations

Body

Response

Upcoming Contract Changes

Required Fields

Response Body

Test Customers

External Metadata

LMS Auto-Fetch (sync)

Loan IDs (Optional)

Loan ID (Deprecated)