---
title: "Create or Update an Organization"
method: POST
path: "/organizations"
tags: ["Users", "Organizations"]
---

# Create or Update an Organization

`POST /organizations`

Group your users by company, team, or any organizational structure that makes sense for your business.

Provide an `externalOrganizationId` to identify the organization—your ID from your own system. Don't worry about whether it already exists; we'll create it if it's new or update it if it already exists. This makes syncing organization data effortless.

Reference this organization when creating users (via `/users`) or logging messages (via `/messages`) using the same `externalOrganizationId`. Perfect for B2B products where you need to track which company each user belongs to.

## Request body

- CreateOrganizationRequest — Request payload for creating a new organization.
  - `externalOrganizationId` string, required — Your unique identifier for the organization. Use this same ID in other API calls to reference this organization.
  - `name` string — The organization's name.
  - `properties` object — Custom organization properties.

## Response `200`

Organization created or updated successfully

- CreateOrganizationResponse — Success response for organization creation.
  - `success` boolean, required — Whether the API call was successful.
  - `organization` TenantOrganization, required — The organization that was created or updated.
    - `id` string, required — The Greenflash organization ID.
    - `externalId` string — Your external organization ID.
    - `name` string — The organization name.
    - `properties` object, required — Custom organization properties.
    - `createdAt` string, date-time — When the organization was first created.
    - `updatedAt` string, date-time — When the organization was last updated.

## Other responses

- `400` — Bad request - invalid input data
- `500` — Server error

## Changes

- **2025-11-24** `c1998d918478` — 2 breaking, 1 warning, 4 info
  - removed the required property `organization/metadata` from the response with the `200` status
  - removed the required property `organization/tenantId` from the response with the `200` status
  - removed the request property `metadata`
  - api tag `Organizations` added
  - …3 more
- **2025-10-09** `48adb6bfe01d` — 2 breaking
  - the `organization/createdAt` response's property type/format changed from `string`/`date` to `string`/`date-time` for status `200`
  - the `organization/updatedAt` response's property type/format changed from `string`/`date` to `string`/`date-time` for status `200`
- **2025-10-09** `e2ce5771d0c3` — 2 breaking
  - the response property `organization/createdAt` became optional for the status `200`
  - the response property `organization/updatedAt` became optional for the status `200`
- **2025-10-06** `8ac2a6f673ac` — 1 breaking, 1 warning, 7 info
  - the request property `externalOrganizationId` became required
  - removed the request property `organizationId`
  - added the new optional request property `metadata`
  - the request property `name` became optional
  - …5 more
- **2025-09-27** `647d988db470` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/changes/organizations/post.md)

---

[API](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference.md) · [All operations](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenflash-ai/greenflash-api-reference/revisions/c566e560677d/schema)