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

# Create customer

> Creates a new customer object in Zenskar. Customer objects represent the individuals or companies you do business with and serve for your revenue operations—they must exist before you can create contracts, generate invoices, or process payments.

The customer record stores essential billing information including contact details, billing and shipping addresses, tax identifiers, payment preferences, and custom metadata specific to your business needs. Only customer_name is required at creation—all other fields are optional, allowing you to capture minimal information initially. The customer address is an important field which is used for Regional tax calculation, make sure this field is correct for the required customers.

When integrated with external systems, newly created customers are automatically synchronized with configured platforms like Stripe, HubSpot, Zoho, or Xero. Use the external_id field to maintain references to source systems for bidirectional synchronization.



## OpenAPI

````yaml /openAPI/openapi-20240301.json post /customers
openapi: 3.1.0
info:
  title: zenskar
  version: 2.0.0
servers:
  - url: https://api.zenskar.com
security:
  - ApiTokenAuth: []
    OrganisationAuth: []
paths:
  /customers:
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        Creates a new customer object in Zenskar. Customer objects represent the
        individuals or companies you do business with and serve for your revenue
        operations—they must exist before you can create contracts, generate
        invoices, or process payments.


        The customer record stores essential billing information including
        contact details, billing and shipping addresses, tax identifiers,
        payment preferences, and custom metadata specific to your business
        needs. Only customer_name is required at creation—all other fields are
        optional, allowing you to capture minimal information initially. The
        customer address is an important field which is used for Regional tax
        calculation, make sure this field is correct for the required customers.


        When integrated with external systems, newly created customers are
        automatically synchronized with configured platforms like Stripe,
        HubSpot, Zoho, or Xero. Use the external_id field to maintain references
        to source systems for bidirectional synchronization.
      operationId: Create-customer
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequestSchema'
            examples:
              example_1:
                summary: Example 1
                description: Create a customer with just the essential information
                value:
                  customer_name: Acme Corporation
                  email: billing@acme.com
              example_2:
                summary: Example 2
                description: >-
                  Create a customer with complete contact and billing
                  information
                value:
                  customer_name: Acme Corporation
                  email: billing@acme.com
                  phone_number: +1-555-0100
                  address:
                    line1: 123 Business Ave
                    city: San Francisco
                    state: CA
                    zipCode: '94102'
                    country: United States
                  ship_to_address:
                    line1: 456 Delivery St
                    city: Oakland
                    state: CA
                    zipCode: '94601'
                    country: United States
                  custom_data:
                    industry: Technology
                    sales_rep: john.doe@example.com
              example_3:
                summary: Example 3
                description: Create a customer synced from an external CRM system
                value:
                  customer_name: TechStart Inc
                  email: contact@techstart.io
                  external_id: SFDC-12345
                  custom_data:
                    crm_source: salesforce
                    account_tier: enterprise
      responses:
        '200':
          description: Successfully created customer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponseSchema'
              example:
                id: 123e4567-e89b-12d3-a456-426614174000
                customer_name: Acme Corporation
                email: billing@acme.com
                phone_number: +1-555-0100
                address:
                  line1: 123 Business Ave
                  city: San Francisco
                  state: CA
                  zipCode: '94102'
                  country: United States
                  country_code: US
                  validation_status: valid
                tax_info: []
                custom_data:
                  industry: Technology
                  company_size: 50-200
                communications_enabled: true
                auto_charge_enabled: true
        '400':
          description: Bad request - validation error
          content:
            application/json:
              examples:
                missing_required:
                  summary: Missing required fields
                  value:
                    error_code: BAD_REQUEST
                    message: customer_name is required
                invalid_email:
                  summary: Invalid email format
                  value:
                    error_code: BAD_REQUEST
                    message: Invalid email format
                duplicate_customer:
                  summary: Duplicate customer
                  value:
                    error_code: BAD_REQUEST
                    message: Customer with this email already exists
        '422':
          description: Unprocessable Entity - request schema validation error
          content:
            application/json:
              example:
                status_code: 10422
                message: >-
                  1 validation error for CreateCustomerRequestSchema; email:
                  value is not a valid email address
        '500':
          description: Internal server error
          content:
            application/json:
              example:
                error_code: INTERNAL_SERVER_ERROR
                message: Failed to create customer
components:
  schemas:
    CreateCustomerRequestSchema:
      properties:
        external_id:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: External Id
          description: >-
            External identifier for this customer from your system or
            third-party CRM (e.g., Salesforce ID)
        customer_name:
          type: string
          title: Customer Name
          description: Full name of the customer or company
          default: Acme Corporation
        custom_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Data
          description: >-
            Custom key-value pairs for storing additional customer information
            (e.g., industry, account tier, sales rep)
        address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Primary billing address for the customer
        ship_to_address:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Shipping address if different from billing address
        tax_info:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxId'
              type: array
            - type: 'null'
          title: Tax Info
          description: >-
            List of tax identifiers for the customer (e.g., VAT number, GST
            number)
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          description: >-
            Primary email address for the customer (must be unique within
            organization)
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
          description: >-
            Primary phone number for the customer (include country code, e.g.,
            +1-555-0100)
        connector:
          anyOf:
            - $ref: '#/components/schemas/app__customer__schema__Connector'
            - type: 'null'
          description: >-
            External connector information for integration with third-party
            systems
        communications_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Communications Enabled
          description: >-
            Enable or disable email communications for this customer (invoices,
            receipts, etc.)
        auto_charge_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Charge Enabled
          description: Enable or disable automatic payment charging for invoices
        business_entity_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Business Entity Id
          description: Business entity ID to associate with this customer
      type: object
      required:
        - customer_name
      title: CreateCustomerRequestSchema
      description: Create Customer Request Schema
    CustomerResponseSchema:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Customer Id
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: External Customer Id
        customer_name:
          type: string
          title: Customer Name
          description: Customer name
        custom_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Data
          description: Customer Custom Data
        address:
          anyOf:
            - $ref: '#/components/schemas/AddressResponse'
            - type: 'null'
          description: Customer Address
        ship_to_address:
          anyOf:
            - $ref: '#/components/schemas/AddressResponse'
            - type: 'null'
          description: Customer Ship To Address
        tax_info:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaxId'
              type: array
            - type: 'null'
          title: Tax Info
          description: Customer Tax Ids
          default: []
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Customer primary email address
        custom_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Attributes
          description: Customer Tags
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone Number
          description: Customer Phone Number
        communications_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Communications Enabled
          description: To enable/disable communications
          default: true
        auto_charge_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Charge Enabled
          description: To enable/disable auto-charge
          default: true
        business_entity_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Business Entity Id
          description: Business Entity Id
      type: object
      required:
        - id
        - external_id
        - customer_name
        - custom_data
        - address
      title: CustomerResponseSchema
      description: Create Customer Response Schema
    Address:
      properties:
        line1:
          anyOf:
            - type: string
            - type: 'null'
          title: Line1
          description: Street address line 1 (e.g., building number and street name)
        line2:
          anyOf:
            - type: string
            - type: 'null'
          title: Line2
          description: Street address line 2 (e.g., apartment, suite, unit number)
        line3:
          anyOf:
            - type: string
            - type: 'null'
          title: Line3
          description: Street address line 3 (additional address information)
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
          description: City or locality name
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
          description: State, province, or region
        zipCode:
          anyOf:
            - type: string
            - type: 'null'
          title: Zipcode
          description: Postal code or ZIP code
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: Country name (e.g., 'United States')
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          description: Two-letter ISO country code (e.g., 'US', 'GB')
        validation_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Validation Status
          description: Address validation status
        connector_validation:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connector Validation
          description: Validation data from external connector
      type: object
      title: Address
      description: Address Schema
    TaxId:
      properties:
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          description: Two-letter ISO country code for the tax ID (e.g., 'US', 'GB', 'IN')
        tax_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Tax Code
          description: Type of tax identifier (e.g., 'VAT', 'GST', 'EIN')
        tax_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tax Id
          description: The actual tax identification number
      type: object
      title: TaxId
      description: Tax Id Schema
    app__customer__schema__Connector:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: >-
            Name of the external connector or integration (e.g., 'stripe',
            'salesforce')
        reference_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Reference Id
          description: Customer ID in the external system (e.g., Stripe customer ID)
      type: object
      title: Connector
    AddressResponse:
      properties:
        line1:
          anyOf:
            - type: string
            - type: 'null'
          title: Line1
          description: Street address line 1 (e.g., building number and street name)
        line2:
          anyOf:
            - type: string
            - type: 'null'
          title: Line2
          description: Street address line 2 (e.g., apartment, suite, unit number)
        line3:
          anyOf:
            - type: string
            - type: 'null'
          title: Line3
          description: Street address line 3 (additional address information)
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
          description: City or locality name
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
          description: State, province, or region
        zipCode:
          anyOf:
            - type: string
            - type: 'null'
          title: Zipcode
          description: Postal code or ZIP code
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
          description: Country name (e.g., 'United States')
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          description: Two-letter ISO country code (e.g., 'US', 'GB')
        validation_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Validation Status
          description: Address validation status
        connector_validation:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Connector Validation
          description: Validation data from external connector
      type: object
      title: AddressResponse
      description: Address Schema
  securitySchemes:
    ApiTokenAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-default: <your-api-key>
    OrganisationAuth:
      type: apiKey
      in: header
      name: organisation
      x-default: <your-organisation-id>

````