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

# Create Customer

> Create a new customer.

**Scope:** `customers:write`


## OpenAPI

````yaml /openapi/customers.yaml post /v1/customers
openapi: 3.1.0
info:
  title: Customers API
  version: '1.0'
servers:
  - url: https://api.monk.com
    description: Production
  - url: https://api-sandbox.monk.com
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /v1/customers:
    post:
      summary: Create Customer
      description: Create a new customer.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - contacts
              properties:
                name:
                  type: string
                  description: Display name
                legalName:
                  type: string
                  description: Legal/registered business name
                externalCustomerId:
                  type: string
                  description: Your own external customer ID
                paymentProviderId:
                  type: string
                  description: >-
                    Payment provider customer ID (e.g. Stripe `cus_xxx`).
                    Requires `provider`.
                provider:
                  type: string
                  enum:
                    - stripe
                  description: Payment provider. Requires `paymentProviderId`.
                tags:
                  type: array
                  items:
                    type: string
                billingAddress:
                  type: object
                  description: >-
                    Billing address for tax calculation. Required when your
                    organization has sales tax (Anrok) enabled.
                  properties:
                    address1:
                      type: string
                      description: Street address line 1
                    address2:
                      type: string
                      description: Street address line 2
                    city:
                      type: string
                      description: City
                    region:
                      type: string
                      description: State/province/region code (e.g. "CA", "NY")
                    postalCode:
                      type: string
                      description: Postal/ZIP code
                    country:
                      type: string
                      description: ISO 3166-1 alpha-2 country code (e.g. "US", "CA", "GB")
                  required:
                    - address1
                    - city
                    - region
                    - postalCode
                    - country
                contacts:
                  type: array
                  minItems: 1
                  description: >-
                    At least one contact is required. Each contact must have an
                    email and at least one role.
                  items:
                    type: object
                    required:
                      - name
                      - email
                      - roles
                    properties:
                      name:
                        type: string
                        description: Contact full name
                      email:
                        type: string
                        format: email
                        description: Contact email address
                      roles:
                        type: array
                        minItems: 1
                        items:
                          type: string
                          enum:
                            - accounts_payable
                            - primary
                            - signatory
                            - csm
                            - account_manager
                            - other
                        description: Contact roles. At least one required.
                      emailRecipientType:
                        type: string
                        enum:
                          - to
                          - cc
                          - bcc
                        default: to
                        description: >-
                          Email recipient type for invoice emails. Defaults to
                          `to`.
                paymentMethodId:
                  type: string
                  description: >-
                    Stripe Payment Method ID (`pm_xxx`). Sets the customer's
                    default payment method. Requires `paymentMethodType`.
                paymentMethodType:
                  type: string
                  enum:
                    - card
                    - us_bank_account
                  description: >-
                    Type of payment method. Required when `paymentMethodId` is
                    provided.
            example:
              name: Acme Corp
              legalName: Acme Corporation Inc.
              tags:
                - enterprise
              contacts:
                - name: John Doe
                  email: john@acme.com
                  roles:
                    - accounts_payable
                  emailRecipientType: to
              billingAddress:
                address1: 123 Main St
                city: San Francisco
                region: CA
                postalCode: '94105'
                country: US
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
              example:
                data:
                  id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: Acme Corp
                  legalName: Acme Corporation Inc.
                  tags:
                    - enterprise
                  isPaused: false
                  pausedAt: null
                  pausedUntil: null
                  metadata:
                    externalCustomerId: my-crm-id-123
                    externalCompanyIds: []
                  createdAt: '2024-01-01T00:00:00.000Z'
                  updatedAt: '2024-01-01T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Payment provider customer already linked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        legalName:
          type:
            - string
            - 'null'
        tags:
          type: array
          items:
            type: string
        isPaused:
          type: boolean
        pausedAt:
          type:
            - string
            - 'null'
        pausedUntil:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Date when customer-level invoice sending resumes automatically
            (`YYYY-MM-DD`), or `null` for no auto-resume date.
        metadata:
          type: object
          properties:
            externalCustomerId:
              type:
                - string
                - 'null'
            externalCompanyIds:
              type: array
              items:
                type: string
        externalIds:
          type: array
          items:
            $ref: '#/components/schemas/ExternalId'
        billingContacts:
          type: array
          description: >-
            Customer-level billing contacts (`accounts_payable` / Accounts
            Payable). Does not include contract- or invoice-specific contacts.
          items:
            $ref: '#/components/schemas/BillingContact'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
    ExternalId:
      type: object
      properties:
        provider:
          type: string
          enum:
            - hubspot
            - quickbooks
            - stripe
            - salesforce
            - netsuite
        entityType:
          type: string
          enum:
            - customer
        id:
          type: string
    BillingContact:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type:
            - string
            - 'null'
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````