> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finosu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Creates a new customer

## 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](/api-reference/upcoming-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](/api-reference/upcoming-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:**

```json theme={null}
{
  "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](/api-reference/upcoming-changes).


## OpenAPI

````yaml POST /customers
openapi: 3.1.0
info:
  title: Finosu API
  description: Finosu API
  license:
    name: MIT
  version: 1.0.0
servers: []
security:
  - apiKeyAuth: []
paths:
  /customers:
    post:
      description: Creates a new customer
      requestBody:
        description: Customer to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewCustomer'
        required: true
      responses:
        '200':
          description: Customer response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewCustomer:
      description: >-
        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.
      required:
        - id
        - taskType
        - firstName
        - lastName
        - phoneNumber
        - timezone
      type: object
      properties:
        id:
          description: >-
            Unique identifier for the customer. This is your customer reference
            and should match your internal system's ID.
          type: string
        firstName:
          description: The first name of the customer
          type: string
        lastName:
          description: The last name of the customer
          type: string
        email:
          description: >-
            Customer email address. Required unless sync is true. UPCOMING: at
            least one of email or phoneNumber will be required — see
            /api-reference/upcoming-changes.
          type: string
          format: email
          example: john.doe@example.com
        birthday:
          description: >-
            Customer birthday in YYYY-MM-DD format. UPCOMING: this field will
            become required — see /api-reference/upcoming-changes.
          type: string
          format: date
          example: '1985-06-15'
        ssnLastFour:
          description: >-
            Last 4 digits of SSN. UPCOMING: this field will become required —
            see /api-reference/upcoming-changes.
          type: string
          example: '1234'
        timezone:
          description: >-
            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.
          type: string
        phoneNumber:
          description: >-
            Phone number of the customer. UPCOMING: at least one of email or
            phoneNumber will be required — see /api-reference/upcoming-changes.
          type: string
        streetAddress1:
          description: Street address line 1. Required unless sync is true.
          type: string
          example: 123 Main St
        streetAddress2:
          description: Street address line 2 (optional)
          type: string
          example: Apt 4B
        city:
          description: City. Required unless sync is true.
          type: string
          example: San Francisco
        state:
          description: >-
            State code. Required unless sync is true. UPCOMING: this field will
            be required in all cases — see /api-reference/upcoming-changes.
          type: string
          example: CA
        zipCode:
          description: >-
            ZIP/postal code. Required unless sync is true. UPCOMING: at least
            one of timezone or zipCode will be required — see
            /api-reference/upcoming-changes.
          type: string
          example: '94102'
        doNotCall:
          description: Do not call the customer
          type: boolean
        test:
          description: >-
            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.
          type: boolean
          default: false
          deprecated: true
        taskType:
          description: >-
            Type of tasks to create for the customer's automated call schedule.
            Valid values depend on company configuration. This field is
            required.
          type: string
          example: collections
        externalMetadata:
          description: >-
            Additional custom metadata about the customer (e.g. employer
            information, pay schedule, additional contact details)
          type: object
          properties:
            home_phone:
              type: string
              example: '+14155555555'
            cell_phone:
              type: string
              example: '+14155556666'
            employer_name:
              type: string
              example: Acme Corporation
            employer_address:
              type: string
              example: 456 Business Ave
            employer_city:
              type: string
              example: San Francisco
            employer_state:
              type: string
              example: CA
            employer_zip:
              type: string
              example: '94103'
            employer_department:
              type: string
              example: Sales
            employer_phone:
              type: string
              example: '+14155557777'
            employer_direct_line:
              type: string
              example: '+14155558888'
            pay_frequency:
              type: string
              example: biweekly
            pay_day:
              type: string
              example: Friday
        loanIds:
          description: >-
            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.
          type: array
          items:
            type: integer
          example:
            - 123
            - 456
            - 789
        sync:
          type: boolean
          default: false
          description: >-
            When true, auto-fetch missing customer data from your integrated
            lending system. Defaults to false.
        loanId:
          type: string
          description: >-
            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.
          deprecated: true
    Customer:
      required:
        - id
        - firstName
        - lastName
      type: object
      properties:
        id:
          description: >-
            Unique identifier for the customer. This is your customer reference
            and should match your internal system's ID.
          type: string
        firstName:
          description: The first name of the customer
          type: string
        lastName:
          description: The last name of the customer
          type: string
        email:
          description: Customer email address
          type: string
          format: email
        birthday:
          description: Customer birthday in YYYY-MM-DD format
          type: string
          format: date
        ssnLastFour:
          description: Last 4 digits of SSN
          type: string
        timezone:
          description: >-
            Timezone of the customer (IANA timezone name, e.g.,
            'America/New_York', 'America/Los_Angeles')
          type: string
        phoneNumber:
          description: Phone number of the customer
          type: string
        streetAddress1:
          description: Street address line 1
          type: string
        streetAddress2:
          description: Street address line 2 (optional)
          type: string
        city:
          description: City name
          type: string
        state:
          description: State code (e.g., NY, CA)
          type: string
        zipCode:
          description: ZIP/postal code
          type: string
        doNotCall:
          description: Do not call the customer
          type: boolean
        isTest:
          description: Indicates if this is a test customer
          type: boolean
        taskType:
          description: Type of tasks created for the customer's automated call schedule
          type: string
        externalMetadata:
          description: Additional custom metadata about the customer
          type: object
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````