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

# Create Customer

> Create a new customer for your company

<Note>
  **Important:** Customer keys are immutable once created and cannot be changed through updates. Choose your customer key carefully during creation and ideally, should align with the unique id of the customer on your platform.
</Note>


## OpenAPI

````yaml POST /api/v1/customers
openapi: 3.0.1
info:
  title: Metrifox API Documentation
  version: v1
  description: >-
    Welcome to Metrifox Platform's API documentation. This comprehensive API
    suite enables seamless integration with our platform, providing secure and
    efficient access to our services.
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: api.metrifox.com
security:
  - api_key: []
paths:
  /api/v1/customers:
    post:
      tags:
        - Customers
      summary: Creates a customer
      description: >
        Creates a new customer with the provided information. The endpoint
        supports both JSON and multipart form data.

        For multipart requests, the customer data should be sent as a JSON
        string in the 'customer' field.


        **Important Note:** Customer keys are immutable once created and cannot
        be changed through updates. Choose your customer key carefully during
        creation.


        **Customer Types:**

        - **BUSINESS**: For business customers with business details and contact
        people

        - **INDIVIDUAL**: For individual customers with personal details


        **Required Fields:**

        - `customer_type`: Must be either "BUSINESS" or "INDIVIDUAL"

        - `customer_key`: Unique identifier in your system (immutable once
        created)

        - `primary_email`: Primary email address for the customer
      operationId: createCustomer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateRequest'
            examples:
              business_customer:
                summary: Business Customer Example
                value:
                  customer_type: BUSINESS
                  customer_key: acme-corp-001
                  primary_email: contact@acme.com
                  primary_phone: '+1234567890'
                  legal_name: Acme Corporation
                  display_name: Acme Corp
                  billing_email: billing@acme.com
                  timezone: America/New_York
                  language: en
                  currency: USD
                  tax_status: TAXABLE
                  address_line1: 123 Business St
                  city: New York
                  state: NY
                  country: United States
                  zip_code: '10001'
                  contact_people:
                    - first_name: John
                      last_name: Doe
                      email_address: john.doe@acme.com
                      designation: CEO
                      is_primary: true
                  email_addresses:
                    - email: contact@acme.com
                      is_primary: true
                    - email: billing@acme.com
                      is_primary: false
                  phone_numbers:
                    - phone_number: '+1234567890'
                      country_code: '+1'
                      is_primary: true
              individual_customer:
                summary: Individual Customer Example
                value:
                  customer_type: INDIVIDUAL
                  customer_key: jane-doe-001
                  primary_email: jane.doe@example.com
                  primary_phone: '+15551234567'
                  first_name: Jane
                  middle_name: Marie
                  last_name: Doe
                  billing_email: jane.doe@example.com
                  timezone: America/Los_Angeles
                  language: en
                  currency: USD
                  address_line1: 456 Personal Ave
                  city: Los Angeles
                  state: CA
                  country: United States
                  zip_code: '90210'
                  email_addresses:
                    - email: jane.doe@example.com
                      is_primary: true
                  phone_numbers:
                    - phone_number: '5551234567'
                      country_code: '+1'
                      is_primary: true
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCreateResponse'
              examples:
                business_customer_response:
                  summary: Business Customer Response
                  value:
                    message: Customer Created
                    data:
                      id: 550e8400-e29b-41d4-a716-446655440000
                      primary_email: contact@acme.com
                      primary_phone: '+1234567890'
                      legal_name: Acme Corporation
                      display_name: Acme Corp
                      legal_number: null
                      tax_identification_number: null
                      logo_url: null
                      website_url: null
                      account_manager: null
                      first_name: null
                      middle_name: null
                      last_name: null
                      full_name: Acme Corporation
                      billing_email: billing@acme.com
                      timezone: America/New_York
                      language: en
                      currency: USD
                      tax_status: TAXABLE
                      address_line1: 123 Business St
                      address_line2: null
                      city: New York
                      state: NY
                      country: United States
                      zip_code: '10001'
                      shipping_address_line1: null
                      shipping_address_line2: null
                      shipping_city: null
                      shipping_state: null
                      shipping_country: null
                      shipping_zip_code: null
                      created_at: '2024-01-15T10:30:00Z'
                      updated_at: '2024-01-15T10:30:00Z'
                      customer_type: BUSINESS
                      customer_key: acme-corp-001
                      phone_numbers: []
                      email_addresses:
                        - email: contact@acme.com
                          is_primary: true
                      billing_configuration: {}
                      tax_identifications: []
                      contact_people: []
                      payment_terms: []
                      metadata: {}
                      date_of_birth: null
                      documents: {}
                    status: created
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Validation failed
                errors:
                  customer_type:
                    - must be either BUSINESS or INDIVIDUAL
                  customer_key:
                    - is required
                  primary_email:
                    - is required
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity - Validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: |
            from metrifox_sdk import MetrifoxClient

            client = MetrifoxClient(api_key="your_api_key")

            # Simple usage
            customer_data = {
                "customer_key": "your_customer_unique_id",
                "primary_email": "customer_email@example.com",
                "customer_type": "BUSINESS",
                "legal_name": "Your Company LLC",
                "display_name": "Your Company",
                "billing_email": "billing@yourcompany.com"
                # ...other_fields
            }

            # Create a customer
            response = client.customers.create(customer_data)
        - lang: js
          label: JavaScript SDK
          source: >
            import { init } from "metrifox-js";


            const metrifoxClient = init({
              apiKey: process.env.METRIFOX_API_KEY
            });


            // Create a customer

            const customerData = {
              // customer data - refer to request schema for all available fields
            };

            const response = await
            metrifoxClient.customers.create(customerData);
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

            # Initialize with configuration
            METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" })

            # Create a customer
            customer_data = {
              # customer data - refer to request schema for all available fields
            }
            response = METRIFOX_SDK.customers.create(customer_data)
components:
  schemas:
    CustomerCreateRequest:
      type: object
      properties:
        customer_type:
          type: string
          enum:
            - BUSINESS
            - INDIVIDUAL
          description: Type of customer
        customer_key:
          type: string
          description: Unique identifier of the customer in your application
        primary_email:
          type: string
          format: email
          description: Primary email address for the customer
        primary_phone:
          type: string
          description: Primary phone number for the customer
        legal_name:
          type: string
          description: Legal business name
        display_name:
          type: string
          description: Display name for the business
        legal_number:
          type: string
          description: Legal registration number
        tax_identification_number:
          type: string
          description: Tax identification number
        logo_url:
          type: string
          format: uri
          description: URL to company logo
        website_url:
          type: string
          format: uri
          description: Company website URL
        account_manager:
          type: string
          description: Assigned account manager
        first_name:
          type: string
          description: First name
        middle_name:
          type: string
          description: Middle name
        last_name:
          type: string
          description: Last name
        date_of_birth:
          type: string
          format: date
          description: Date of birth (for individuals)
        billing_email:
          type: string
          format: email
          description: Email address for billing communications
        timezone:
          type: string
          description: Preferred timezone
        language:
          type: string
          description: Preferred language for communications
        currency:
          type: string
          description: Preferred currency for billing
        tax_status:
          type: string
          enum:
            - TAXABLE
            - TAX_EXEMPT
            - REVERSE_CHARGE
          description: Tax status of the customer
        address_line1:
          type: string
          description: First line of address
        address_line2:
          type: string
          description: Second line of address
        city:
          type: string
          description: City name
        state:
          type: string
          description: State or province
        country:
          type: string
          description: Country name
        zip_code:
          type: string
          description: ZIP or postal code
        shipping_address_line1:
          type: string
          description: First line of shipping address
        shipping_address_line2:
          type: string
          description: Second line of shipping address
        shipping_city:
          type: string
          description: Shipping city name
        shipping_state:
          type: string
          description: Shipping state or province
        shipping_country:
          type: string
          description: Shipping country name
        shipping_zip_code:
          type: string
          description: Shipping ZIP or postal code
        billing_configuration:
          $ref: '#/components/schemas/BillingConfiguration'
        tax_identifications:
          type: array
          items:
            $ref: '#/components/schemas/TaxIdentification'
          description: Array of tax identification numbers
        contact_people:
          type: array
          items:
            $ref: '#/components/schemas/ContactPerson'
          description: List of contact persons for the business
        payment_terms:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTerm'
          description: Payment terms configuration
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddress'
          description: List of additional email addresses
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
          description: List of additional phone numbers
        documents:
          type: object
          description: Optional documents to attach to the customer
      required:
        - customer_type
        - customer_key
        - primary_email
    CustomerCreateResponse:
      type: object
      properties:
        message:
          type: string
          example: Customer Created
        data:
          $ref: '#/components/schemas/CustomerEntity'
        status:
          type: string
          example: created
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
    BillingConfiguration:
      type: object
      properties:
        preferred_payment_gateway:
          type: string
          description: Preferred payment gateway
        preferred_payment_method:
          type: string
          description: Preferred payment method
        billing_email:
          type: string
          format: email
          description: Email address for billing communications
        billing_address:
          type: string
          description: Billing address
        payment_reminder_days:
          type: integer
          description: Number of days before payment reminder
      additionalProperties: true
    TaxIdentification:
      type: object
      properties:
        type:
          type: string
          description: Type of tax identification (e.g., EIN, VAT, GST)
        number:
          type: string
          description: Tax identification number
        country:
          type: string
          description: Country where tax ID is registered
      required:
        - type
        - number
        - country
    ContactPerson:
      type: object
      properties:
        first_name:
          type: string
          description: First name of contact person
        last_name:
          type: string
          description: Last name of contact person
        email_address:
          type: string
          format: email
          description: Email address of contact person
        designation:
          type: string
          description: Job title or designation
        department:
          type: string
          description: Department name
        is_primary:
          type: boolean
          default: false
          description: Whether this is the primary contact person
        phone_number:
          type: string
          description: Phone number for this contact person
      required:
        - first_name
        - last_name
        - email_address
    PaymentTerm:
      type: object
      properties:
        type:
          type: string
          description: Type of payment term (e.g., Net 30, Net 15)
        value:
          type: string
          description: Payment term value
      required:
        - type
        - value
    EmailAddress:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address
        is_primary:
          type: boolean
          default: false
          description: Whether this is the primary email address
      required:
        - email
    PhoneNumber:
      type: object
      properties:
        phone_number:
          type: string
          description: Phone number
        country_code:
          type: string
          description: Country code (e.g., +1, +44)
        is_primary:
          type: boolean
          default: false
          description: Whether this is the primary phone number
      required:
        - phone_number
        - country_code
    CustomerEntity:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique customer identifier in the Metrifox system
        primary_email:
          type: string
          format: email
          description: Primary email address
        primary_phone:
          type: string
          description: Primary phone number
        legal_name:
          type: string
          description: Legal business name
        display_name:
          type: string
          description: Display name for the business
        legal_number:
          type: string
          description: Legal registration number
        tax_identification_number:
          type: string
          description: Tax identification number
        logo_url:
          type: string
          format: uri
          description: URL to company logo
        website_url:
          type: string
          format: uri
          description: Company website URL
        account_manager:
          type: string
          description: Assigned account manager
        first_name:
          type: string
          description: First name
        middle_name:
          type: string
          description: Middle name
        last_name:
          type: string
          description: Last name
        full_name:
          type: string
          description: Full name
        billing_email:
          type: string
          format: email
          description: Email address for billing communications
        timezone:
          type: string
          description: Preferred timezone
        language:
          type: string
          description: Preferred language for communications
        currency:
          type: string
          description: Preferred currency for billing
        tax_status:
          type: string
          enum:
            - TAXABLE
            - TAX_EXEMPT
            - REVERSE_CHARGE
          description: Tax status of the customer
        address_line1:
          type: string
          description: First line of address
        address_line2:
          type: string
          description: Second line of address
        city:
          type: string
          description: City name
        state:
          type: string
          description: State or province
        country:
          type: string
          description: Country name
        zip_code:
          type: string
          description: ZIP or postal code
        shipping_address_line1:
          type: string
          description: First line of shipping address
        shipping_address_line2:
          type: string
          description: Second line of shipping address
        shipping_city:
          type: string
          description: Shipping city name
        shipping_state:
          type: string
          description: Shipping state or province
        shipping_country:
          type: string
          description: Shipping country name
        shipping_zip_code:
          type: string
          description: Shipping ZIP or postal code
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        customer_type:
          type: string
          enum:
            - BUSINESS
            - INDIVIDUAL
          description: Type of customer
        customer_key:
          type: string
          description: Customer key if available
        phone_numbers:
          type: array
          items:
            type: object
            additionalProperties: true
          description: List of phone numbers
        email_addresses:
          type: array
          items:
            type: object
            additionalProperties: true
          description: List of email addresses
        billing_configuration:
          $ref: '#/components/schemas/BillingConfiguration'
        tax_identifications:
          type: array
          items:
            $ref: '#/components/schemas/TaxIdentification'
          description: Array of tax identification numbers
        contact_people:
          type: array
          items:
            $ref: '#/components/schemas/ContactPerson'
          description: List of contact persons for the business
        payment_terms:
          type: array
          items:
            $ref: '#/components/schemas/PaymentTerm'
          description: Payment terms configuration
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata
        date_of_birth:
          type: string
          format: date
          description: Date of birth (for individuals)
        documents:
          type: object
          description: Attached documents
        mid_cycle_invoice_consolidation:
          type: boolean
          description: Whether to consolidate invoices mid-cycle
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````