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

# Create a customer

> Creates a customer under the authenticated partner tenant. Returns `201 Created` for a new customer, or `200 OK` when a customer with the same email already exists and is returned instead of duplicated (`created: false`). Idempotent on the `Idempotency-Key` header: replaying the same key returns the original result — the same response and status as the first call — never a duplicate. If a create fails before it commits, the key is released; fix the request and retry with the same key.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/partner/customers
openapi: 3.1.0
info:
  title: doola Partner API
  description: >-
    REST API for doola partners to create and manage customers and companies,
    retrieve formation documents, and look up reference data.


    Authenticate every request with a partner API key in the `Authorization`
    header. Generate keys and manage webhooks and event subscriptions in the
    doola Partner Portal.
  contact:
    name: doola
    url: https://www.doola.com
  version: v1
servers:
  - url: https://api.test.doola.com
    description: Sandbox — use test keys (dk_test_…)
  - url: https://api.doola.com
    description: Production — use live keys (dk_live_…)
security:
  - PartnerApiKey: []
tags:
  - name: Playground (sandbox only)
    description: >-
      Sandbox-only helpers to drive a test company through the Formation and
      EinCreation milestones end to end.
  - name: Customers
    description: Create and look up customers under your partner tenant.
  - name: Documents
    description: List and download a company's formation documents.
  - name: Signatures
    description: Request embedded signing sessions for pending company documents.
  - name: Companies
    description: Create companies for your customers, then track formation status.
  - name: Reference data
    description: >-
      Static lookups for building company-creation requests: NAICS codes,
      states, countries, and state filing fees.
paths:
  /v1/partner/customers:
    post:
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Creates a customer under the authenticated partner tenant. Returns `201
        Created` for a new customer, or `200 OK` when a customer with the same
        email already exists and is returned instead of duplicated (`created:
        false`). Idempotent on the `Idempotency-Key` header: replaying the same
        key returns the original result — the same response and status as the
        first call — never a duplicate. If a create fails before it commits, the
        key is released; fix the request and retry with the same key.
      operationId: createCustomer
      parameters:
        - name: Idempotency-Key
          in: header
          description: >-
            Unique key that makes the create safe to retry. Reuse the same value
            to retry; if the create fails before committing, the key is
            released, so retry with the same value.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequestDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PartnerCustomerResponseDto'
components:
  schemas:
    CreateCustomerRequestDto:
      type: object
      description: Request body to create a customer under your partner tenant.
      properties:
        email:
          type: string
          description: Customer email address.
          example: founder@example.com
          minLength: 1
        firstName:
          type: string
          description: Customer legal first name.
          example: Ada
          minLength: 1
        lastName:
          type: string
          description: Customer legal last name.
          example: Lovelace
          minLength: 1
        countryOfResidence:
          type: string
          description: ISO 3166-1 alpha-3 country of residence (e.g. USA).
          example: USA
          minLength: 1
        phoneNumber:
          type: string
          description: Customer phone number in E.164 format. Optional.
          example: '+12125550100'
      required:
        - countryOfResidence
        - email
        - firstName
        - lastName
    PartnerCustomerResponseDto:
      type: object
      description: A partner customer.
      properties:
        doolaCustomerId:
          type: string
          description: doola customer ID (KSUID).
        email:
          type: string
          description: Customer email address.
          example: founder@example.com
        firstName:
          type: string
          example: Ada
        lastName:
          type: string
          example: Lovelace
        countryOfResidence:
          type: string
          description: ISO 3166-1 alpha-3 country of residence (e.g. USA).
          example: USA
        phoneNumber:
          type: string
          example: '+12125550100'
        source:
          type: string
          description: How the customer was created.
          enum:
            - MCP
            - PARTNER_API
            - WHOP_APP
            - DOOLA_DASHBOARDS
        created:
          type: boolean
          description: >-
            True if this request created the customer; false if it already
            existed.
        companies:
          type: array
          description: Companies owned by this customer. Returned only on the get endpoint.
          items:
            $ref: '#/components/schemas/PartnerCompanyRef'
    PartnerCompanyRef:
      type: object
      description: A lightweight reference to a company, used inside a customer response.
      properties:
        doolaCompanyId:
          type: string
          description: doola company ID (KSUID).
        name:
          type: string
          description: Company name.
          example: Acme Labs LLC
        entityType:
          type: string
          description: Entity type.
          example: LLC
        state:
          type: string
          description: State of formation.
          example: DE
  securitySchemes:
    PartnerApiKey:
      type: apiKey
      description: >-
        Partner API key. Send the raw key as the `Authorization` header value —
        e.g. `dk_test_…` in sandbox or `dk_live_…` in production. Generate and
        rotate keys in the doola Partner Portal.
      name: Authorization
      in: header

````