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



## OpenAPI

````yaml /api-reference/openapi.json post /v1/partner/customer-sessions
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 your webhook endpoint 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: Required Actions
    description: >-
      Actions doola needs you to take on a company, such as supplying new name
      options after a state rejection.
  - name: Customers
    description: Create and look up customers under your partner tenant.
  - name: Documents
    description: List and download a company's formation documents.
  - name: Compliance
    description: Track a company's compliance obligations and their due dates.
  - name: Annual Report Filing
    description: >-
      File a company's annual report with its state: what to collect, what it
      costs, submission, confirmation and status.
  - name: Customer sessions
    description: Mint the token the doola SDK uses in your customer's browser.
  - 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/customer-sessions:
    post:
      tags:
        - Customer sessions
      summary: Create a customer session
      operationId: createSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerSessionRequest'
        required: true
      responses:
        '200':
          description: Token issued.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CustomerSessionDto'
        '400':
          description: E_VALIDATION_FAILED
        '409':
          description: >-
            E_EMAIL_IN_USE: no customer can be provisioned for this email —
            either it belongs to an account outside your tenant, or it is bound
            to a non-customer principal such as a portal user.
components:
  schemas:
    CreateCustomerSessionRequest:
      type: object
      description: Send this from your server, never the browser.
      properties:
        email:
          type: string
          description: >-
            The customer's email. If no customer exists for it under your
            tenant, one is created.
          example: founder@example.com
          minLength: 1
        externalCustomerId:
          type: string
          description: >-
            Your own id for this customer. Optional, and the recommended
            integration: it is matched before the email, so a customer who
            changes their address in your system stays the same doola customer
            instead of being provisioned again with an empty wizard. Unique per
            tenant.
          example: usr_8f21c
          maxLength: 255
          minLength: 0
        firstName:
          type: string
          description: Only used when provisioning a new customer.
          example: Ada
        lastName:
          type: string
          description: Only used when provisioning a new customer.
          example: Lovelace
        countryOfResidence:
          type: string
          description: ISO 3166-1 alpha-3. Only used when provisioning a new customer.
          example: USA
        phoneNumber:
          type: string
          description: E.164 format. Only used when provisioning a new customer.
          example: '+12125550100'
      required:
        - email
    CustomerSessionDto:
      type: object
      description: A short-lived token for one of your customers.
      properties:
        accessToken:
          type: string
          description: >-
            Return this to your frontend and hand it to the SDK. It acts only on
            this customer.
        expiresAt:
          type: string
          format: date-time
          description: When the token stops being accepted. Renew before this, not after.
        expiresIn:
          type: integer
          format: int64
          description: >-
            Remaining lifetime in seconds at mint. Schedule renewal from this,
            not from expiresAt: a relative timer keeps the end user's device
            clock out of the arithmetic.
          example: 600
  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

````