---
title: "Create a customer session"
method: POST
path: "/v1/partner/customer-sessions"
tags: ["Customer sessions"]
---

# Create a customer session

`POST /v1/partner/customer-sessions`

## Request

- Base URL: `https://api.test.doola.com`
- URL: `https://api.test.doola.com/v1/partner/customer-sessions`
- Auth: API key in header `Authorization`

## Request body

- CreateCustomerSessionRequest: Send this from your server, never the browser.
  - `email` string, required: The customer's email. If no customer exists for it under your tenant, one is created.
  - `externalCustomerId` string: 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.
  - `firstName` string: Only used when provisioning a new customer.
  - `lastName` string: Only used when provisioning a new customer.
  - `countryOfResidence` string: ISO 3166-1 alpha-3. Only used when provisioning a new customer.
  - `phoneNumber` string: E.164 format. Only used when provisioning a new customer.

## Response `200`

Token issued.

- CustomerSessionDto: A short-lived token for one of your customers.
  - `accessToken` string: Return this to your frontend and hand it to the SDK. It acts only on this customer.
  - `expiresAt` string, date-time: When the token stops being accepted. Renew before this, not after.
  - `expiresIn` integer: 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.

## Other responses

- `400`: E_VALIDATION_FAILED
- `409`: E_EMAIL_IN_USE: the email cannot be this customer's, because it belongs to an account outside your tenant, to a non-customer principal such as a portal user, or to another account the customer would be renamed onto. E_RESOURCE_CONFLICT: the matched customer is bound to a different externalCustomerId, this externalCustomerId is bound to another customer, or the customer predates IAM and cannot take a new email. E_CUSTOMER_REVOKED: the customer was deactivated.
- `429`: E_RATE_LIMITED: too many sessions for your tenant. Retry after the Retry-After header's seconds.

## Changes

- **2026-11-03** `f607744a8927`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/doola/apis/doola-partner-api/changes/v1/partner/customer-sessions/post.md)

---

[API](https://skmtc.dev/doola/apis/doola-partner-api.md) - [All operations](https://skmtc.dev/doola/apis/doola-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/doola/apis/doola-partner-api/revisions/f607744a8927?raw)