> ## 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.

# Get Customers

> Retrieve all your customer details



## OpenAPI

````yaml GET /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:
    get:
      tags:
        - Customers
      summary: Retrieves customers
      operationId: listCustomers
      parameters:
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: Number of records per page
          schema:
            type: integer
      responses:
        '200':
          description: Customers fetched
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Customers fetched
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerEntity'
              examples:
                customers_response:
                  summary: Customers Response Example
                  value:
                    statusCode: 200
                    message: Customers fetched
                    meta:
                      current_page: 1
                      prev_page: null
                      next_page: null
                      per_page: 25
                      total_pages: 1
                      total_records: 2
                    data:
                      - id: 764c80e3-ed59-44a5-ba07-7ee5ba547774
                        primary_email: john@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 Ave
                        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: '2025-08-22T13:15:18.434Z'
                        updated_at: '2025-08-22T13:15:18.434Z'
                        customer_type: BUSINESS
                        customer_key: acme-corp-001
                        phone_numbers: []
                        email_addresses: []
                        billing_configuration: {}
                        tax_identifications: []
                        contact_people: []
                        payment_terms: []
                        metadata: {}
                        date_of_birth: null
                        documents: {}
                      - id: 864c80e3-ed59-44a5-ba07-7ee5ba547775
                        primary_email: jane.doe@example.com
                        primary_phone: '+1987654321'
                        legal_name: null
                        display_name: Jane Doe
                        legal_number: null
                        tax_identification_number: null
                        logo_url: null
                        website_url: null
                        account_manager: null
                        first_name: Jane
                        middle_name: Marie
                        last_name: Doe
                        full_name: Jane Doe
                        billing_email: jane.doe@example.com
                        timezone: America/Los_Angeles
                        language: en
                        currency: USD
                        tax_status: TAXABLE
                        address_line1: 123 Main Street
                        address_line2: Apt 4B
                        city: Los Angeles
                        state: CA
                        country: United States
                        zip_code: '90210'
                        shipping_address_line1: null
                        shipping_address_line2: null
                        shipping_city: null
                        shipping_state: null
                        shipping_country: null
                        shipping_zip_code: null
                        created_at: '2025-08-22T14:20:30.123Z'
                        updated_at: '2025-08-22T14:20:30.123Z'
                        customer_type: INDIVIDUAL
                        customer_key: jane-doe-001
                        phone_numbers: []
                        email_addresses: []
                        billing_configuration: {}
                        tax_identifications: []
                        contact_people: []
                        payment_terms: []
                        metadata: {}
                        date_of_birth: '1985-06-15'
                        documents: {}
        '401':
          description: Unauthorized
          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")

            # Get all customers with optional pagination
            response = client.customers.list({
                "page": 1,
                "per_page": 25
            })
        - lang: js
          label: JavaScript SDK
          source: |
            import { init } from "metrifox-js";

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

            // Get all customers with optional pagination
            const response = await metrifoxClient.customers.list({
              page: 1,
              per_page: 25
            });
        - lang: ruby
          label: Ruby SDK
          source: |
            require 'metrifox-sdk'

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

            # Get all customers with optional pagination
            response = METRIFOX_SDK.customers.list({ 
              page: 1, 
              per_page: 25 
            })
components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          description: Current page number
        prev_page:
          type: integer
          nullable: true
          description: Previous page number (null if on first page)
        next_page:
          type: integer
          nullable: true
          description: Next page number (null if on last page)
        per_page:
          type: integer
          description: Number of records per page
        total_pages:
          type: integer
          description: Total number of pages
        total_records:
          type: integer
          description: Total number of records
    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
    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
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````