# Create a new customer

Creates a new customer record.

Endpoint: POST /v1/api/customer
Version: 1.2.4
Security: X-Api-Key

## Request fields (application/json):

  - `email` (string, required)
    Email address of the Customer.
    Example: "customer@example.com"

  - `firstName` (string, required)
    First name of the Customer.
    Example: "John"

  - `lastName` (string, required)
    Last name of the Customer.
    Example: "Doe"

  - `outletId` (string)
    Outlet ID associated with the Customer.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `externalId` (string)
    External ID associated with the Customer when synced from external source. If present, it will set fromFinal to true.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `phone` (string)
    Phone number of the Customer.
    Example: "+1234567890"

  - `totalSpent` (string)
    Total amount spent by the Customer.
    Example: "1000.50"

  - `lastAction` (string)
    Timestamp when the Customer was last actioned.
    Example: "2025-12-07T19:31:48.436+00:00"

  - `tags` (array)
    Tags associated with the Customer.
    Example: ["vip","loyal","premium"]

  - `billing` (object)
    Billing address associated with the Customer.
    Example: {"firstName":"John","lastName":"Doe","address1":"123 Main St","address2":"Suite 100","city":"New York","state":"NY","country":"USA","postCode":"10001"}

  - `billing.firstName` (string)
    First name of the person associated with the Address.
    Example: "John"

  - `billing.lastName` (string)
    Last name of the person associated with the Address.
    Example: "Doe"

  - `billing.address1` (string)
    First line of the address.
    Example: "123 Main St"

  - `billing.address2` (string)
    Second line of the address.
    Example: "Suite 100"

  - `billing.city` (string)
    City of the address.
    Example: "New York"

  - `billing.state` (string)
    State of the address.
    Example: "NY"

  - `billing.country` (string)
    Country of the address.
    Example: "USA"

  - `billing.postCode` (string)
    Post code of the address.
    Example: "10001"

  - `shipping` (object)
    Shipping address associated with the Customer.
    Example: {"firstName":"John","lastName":"Doe","address1":"123 Main St","address2":"Suite 100","city":"New York","state":"NY","country":"USA","postCode":"10001"}

  - `metadata` (array)
    Metadata associated with the Customer.
    Example: [{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}]

  - `metadata.key` (string, required)
    Key of the metadata entry.
    Example: "key1"

  - `metadata.value` (string, required)
    Value of the metadata entry.
    Example: "value1"

  - `metadata.externalId` (string)
    External ID associated with the metadata entry.
    Example: "ext123"

  - `notes` (array)
    Notes associated with the Customer.
    Example: [{"createdAt":"2025-12-07T19:31:48.436+00:00","message":"Note 1"}]

  - `notes.createdAt` (string, required)
    Timestamp when the Note was created.
    Example: "2025-12-07T19:31:48.436+00:00"

  - `notes.message` (string, required)
    Message of the Note.
    Example: "Note message"

## Response 201 fields (application/json):

  - `id` (string)
    Unique identifier for the Customer.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `createdAt` (string)
    Timestamp when the Customer was created.
    Example: "2025-12-07T19:31:48.436+00:00"

  - `updatedAt` (string)
    Timestamp when the Customer was last updated.
    Example: "2025-12-07T19:35:48.436+00:00"

  - `companyId` (string)
    Company ID associated with the Customer.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `email` (string)
    Email address of the Customer.
    Example: "customer@example.com"

  - `firstName` (string)
    First name of the Customer.
    Example: "John"

  - `lastName` (string)
    Last name of the Customer.
    Example: "Doe"

  - `fromFinal` (boolean)
    Flag to indicate if the Customer is created from Final.

  - `outletId` (string)
    Outlet ID associated with the Customer.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `externalId` (string)
    External ID associated with the Customer when synced from external source. If present, it will set fromFinal to true.
    Example: "o1p2q3r4s5t6u7v8w9x0y1z2"

  - `phone` (string)
    Phone number of the Customer.
    Example: "+1234567890"

  - `totalSpent` (string)
    Total amount spent by the Customer.
    Example: "1000.50"

  - `lastAction` (string)
    Timestamp when the Customer was last actioned.
    Example: "2025-12-07T19:31:48.436+00:00"

  - `tags` (array)
    Tags associated with the Customer.
    Example: ["vip","loyal","premium"]

  - `billing` (object)
    Billing address associated with the Customer.
    Example: {"firstName":"John","lastName":"Doe","address1":"123 Main St","address2":"Suite 100","city":"New York","state":"NY","country":"USA","postCode":"10001"}

  - `billing.firstName` (string)
    First name of the person associated with the Address.
    Example: "John"

  - `billing.lastName` (string)
    Last name of the person associated with the Address.
    Example: "Doe"

  - `billing.address1` (string)
    First line of the address.
    Example: "123 Main St"

  - `billing.address2` (string)
    Second line of the address.
    Example: "Suite 100"

  - `billing.city` (string)
    City of the address.
    Example: "New York"

  - `billing.state` (string)
    State of the address.
    Example: "NY"

  - `billing.country` (string)
    Country of the address.
    Example: "USA"

  - `billing.postCode` (string)
    Post code of the address.
    Example: "10001"

  - `shipping` (object)
    Shipping address associated with the Customer.
    Example: {"firstName":"John","lastName":"Doe","address1":"123 Main St","address2":"Suite 100","city":"New York","state":"NY","country":"USA","postCode":"10001"}

  - `metadata` (array)
    Metadata associated with the Customer.
    Example: [{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}]

  - `metadata.key` (string, required)
    Key of the metadata entry.
    Example: "key1"

  - `metadata.value` (string, required)
    Value of the metadata entry.
    Example: "value1"

  - `metadata.externalId` (string)
    External ID associated with the metadata entry.
    Example: "ext123"

  - `notes` (array)
    Notes associated with the Customer.
    Example: [{"createdAt":"2025-12-07T19:31:48.436+00:00","message":"Note 1"}]

  - `notes.createdAt` (string, required)
    Timestamp when the Note was created.
    Example: "2025-12-07T19:31:48.436+00:00"

  - `notes.message` (string, required)
    Message of the Note.
    Example: "Note message"

## Response 400 fields (application/json):

  - `statusCode` (number, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message describing what went wrong
    Example: "Validation failed: Field `schemaField` is required."

  - `error` (string, required)
    Error type/name
    Enum: "Bad Request", "Unauthorized", "Forbidden", "Not Found", "Conflict", "Unprocessable Entity", "Internal Server Error"