---
title: "Create an Organization"
method: POST
path: "/v1/organizations"
tags: ["Organizations API"]
---

# Create an Organization

`POST /v1/organizations`

Use this endpoint to create an Organization. You can create multiple Organizations, but they must be added one at a time.

## Headers

- `Content-Type` string
- `X-Request-Id` string, uuid
- `Authorization` string

## Request body

- CreateOrganizationRequest
  - `legalName` string, required — The legal name of the Organization.
  - `parentOrganizationId` string, uuid, nullable — The unique identifier of the parent Organization.
  - `doingBusinessAs` string, nullable — The trade name of the Organization.
  - `legalDocument` string, required — Official tax ID, company registration number, or other legal identification.
  - `status` StatusOrganizationRequest — An object containing information about the status. **Important**: If not provided, the default status will be 'ACTIVE'.
    - `code` string — The name of the status.
    - `description` string, nullable — The description of the status.
  - `address` AddressOrganization — An object containing information about the address of the Organization.
    - `line1` string, required — The first line of the address. Usually used to inform the name of the street and the number of the building.
    - `line2` string — The second line of the address. Usually used to inform about any complements such as the number of the apartment.
    - `zipCode` string, required — The postal code (only numbers).
    - `city` string, required — The name of the city where the Organization is established.
    - `state` string, required — The two-letter abbreviation that represents the State where the Organization is.
    - `country` string, required — The two-letter code (ISO 3166-1 alpha2) that represents the country where the Organization is.
    - `description` string — A descriptive label for the address (e.g., "Home", "Office", "Billing").
  - `metadata` Metadata — An object containing key-value pairs to add as metadata, where the field `name` is the key and the field `value` is the value. For example, to add a Cost Center, use `'costCenter': 'BR_11101997'`. **Constraints:** keys must be at most 100 characters; string values at most 2000 characters. Nested objects are not allowed (values must be string, number, or boolean), the structure may not exceed a maximum depth of 10, and a maximum of 100 keys is permitted.

## Response `201`

Indicates that the resource was successfully created and the operation was completed as expected.

- CreateOrganizationResponse
  - `id` string, uuid — The unique identifier of the Organization.
  - `legalName` string — The legal name of the Organization.
  - `parentOrganizationId` string, uuid, nullable — The unique identifier of the parent Organization.
  - `doingBusinessAs` string, nullable — The trade name of the Organization.
  - `legalDocument` string — Official tax ID, company registration number, or other legal identification.
  - `status` StatusOrganization — An object containing information about the status.
    - `code` string — The name of the status.
    - `description` string, nullable — The description of the status.
  - `address` AddressOrganization — An object containing information about the address of the Organization.
    - `line1` string, required — The first line of the address. Usually used to inform the name of the street and the number of the building.
    - `line2` string — The second line of the address. Usually used to inform about any complements such as the number of the apartment.
    - `zipCode` string, required — The postal code (only numbers).
    - `city` string, required — The name of the city where the Organization is established.
    - `state` string, required — The two-letter abbreviation that represents the State where the Organization is.
    - `country` string, required — The two-letter code (ISO 3166-1 alpha2) that represents the country where the Organization is.
    - `description` string — A descriptive label for the address (e.g., "Home", "Office", "Billing").
  - `metadata` Metadata — An object containing key-value pairs to add as metadata, where the field `name` is the key and the field `value` is the value. For example, to add a Cost Center, use `'costCenter': 'BR_11101997'`. **Constraints:** keys must be at most 100 characters; string values at most 2000 characters. Nested objects are not allowed (values must be string, number, or boolean), the structure may not exceed a maximum depth of 10, and a maximum of 100 keys is permitted.
  - `createdAt` string, date-time — Timestamp of creation (UTC).
  - `updatedAt` string, date-time — Timestamp of last update (UTC).
  - `deletedAt` string, date-time, nullable — Timestamp of soft deletion, if applicable (UTC).

## Other responses

- `400`
- `401` — Unauthorized
- `403` — Forbidden
- `404`
- `500` — Internal Server Error

---

[API](https://skmtc.net/lerian/apis/identity-plugin.md) · [All operations](https://skmtc.net/lerian/apis/identity-plugin/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lerian/identity-plugin/versions/25daba385532/schema)