---
title: "Create a new tenant"
method: POST
path: "/v1/entities/tenants"
tags: ["Tenants"]
---

# Create a new tenant

`POST /v1/entities/tenants`

## Request

- Base URL: `https://api.tesser.xyz`
- URL: `https://api.tesser.xyz/v1/entities/tenants`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/tesser/apis/tesser-api/docs/v1/entities/tenants/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new tenant for your workspace. Tenants are business customers that can have their own counterparties and accounts.

Tenants can be assigned to counterparties to organize your workspace by customer.

**Required fields:** business_legal_name

## Request body

- CreateTenantRequestDto
  - `business_legal_name` string, required: Legal business name (required)
  - `business_dba` string, nullable: DBA - Doing Business As name
  - `business_address_country` string, nullable: Country code in ISO 3166-1 alpha-2 or alpha-3 format
  - `webhook_url` string, uri, nullable: HTTPS webhook URL for payment creation notifications; omit the port or use port 443
  - `business_street_address1` string, nullable: Street address line 1
  - `business_street_address2` string, nullable: Street address line 2
  - `business_city` string, nullable: City
  - `business_state` string, nullable: State/region
  - `business_postal_code` string, nullable: Postal code
  - `business_legal_entity_identifier` string, nullable: Legal Entity Identifier

## Response `201`

Tenant created successfully

- CreateTenantResponseDto
  - `data` CreateTenantData, required
    - `tenant` TenantData, required
      - `id` string, required: Unique identifier for the tenant
      - `workspace_id` string, required: Workspace ID the tenant belongs to
      - `name` string, required: Display name derived from business fields
      - `business_legal_name` string, nullable: Legal business name
      - `business_dba` string, nullable: DBA - Doing Business As
      - `business_address_country` string, nullable: Country code in ISO 3166-1 format
      - `webhook_url` string, nullable: Webhook URL for payment creation notifications
      - `business_street_address1` string, nullable: Street address line 1
      - `business_street_address2` string, nullable: Street address line 2
      - `business_city` string, nullable: City
      - `business_state` string, nullable: State/region
      - `business_postal_code` string, nullable: Postal code
      - `business_legal_entity_identifier` string, nullable: Legal Entity Identifier
      - `created_at` string, required: Creation timestamp in ISO 8601 format
      - `updated_at` string, required: Last update timestamp in ISO 8601 format

## Other responses

- `400`: Invalid request data
- `401`: Authentication required or invalid credentials
- `500`: Internal server error

---

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