Browse the docs

Create organization

POST /v2/api-gateway/organizations

Creates a child organization. When parent_organization_id is omitted the new organization is attached to the caller's top-level organization; when given, the parent must be owned by the caller.

Request

Authentication: your API key in the x-api-key header.

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Body

Field	Type	Description
`name` required	string	Display name of the new organization.
`parent_organization_id`	string, uuid	Parent under which to create it. Omit to create a child of your top-level organization.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v2/api-gateway/organizations' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "name": "string",
       "parent_organization_id": "8d2cd518-5ef2-4280-91e8-63b1a0e672e7"
     }'

Responses

201 Success

Field	Type	Description
`id` required	string	Organization id.
`name` required	string
`parent_organization_id` required	string, nullable	Parent organization, or null for a root organization.
`created_at` required	string, nullable
`updated_at` required	string, nullable

JSON

{
  "id": "5c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "name": "Acme Inc.",
  "parent_organization_id": null,
  "created_at": "2026-07-14T11:03:20.000Z",
  "updated_at": "2026-08-16T17:51:01.000Z"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).