---
title: "Add Tenant"
method: POST
path: "/tenants/"
tags: ["authenticated", "service-titan-tenant"]
---

# Add Tenant

`POST /tenants/`

## Request

- Base URL: `https://api-docs.upsmith.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.upsmith.com/tenants/`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Request the ServiceTitan app install for the caller's own organization.

The tenant name is the authenticated organization's, never the client's. Submitting
the tenant the organization is already connected to is answered from stored state,
so a replay reports the same single request instead of failing.

## Headers

- `organization-id` string, nullable
- `x-user-id` string, nullable
- `timezone` string
- `x-actor-email` string, nullable
- `x-request-source` string, nullable
- `x-operation-id` string, nullable
- `x-commit-message` string, nullable
- `x-confirmation-id` string, nullable
- `x-chat-id` string, nullable

## Request body

- AddTenantRequest
  - `tenant_id` string, required
  - `environment` 'production' | 'integration': Which ServiceTitan environment a tenant belongs to. Three spellings are in play: the API and the onboarding draft use these values, ServiceTitan reports its own capitalised, and the column stores JSON. ``parse`` is the only place that reconciles them.
  - `replace` boolean

## Response `200`

Successful Response

- AddServiceTitanOrgResponse: Response from ``POST /tenants`` — newly initialized tenant integration.
  - `status` 'enabled' | 'pending' | 'error' | 'disabled', required
  - `success` boolean, required
  - `message` string, required

## Other responses

- `422`: Validation Error

---

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