Skip to main content
POST
Create organization

Authorizations

X-API-Key
string
header
required

Body

application/json
name
string
required

Organization name.

country
string<iso3166-alpha2>
required

ISO 3166-1 alpha-2 country code.

Required string length: 2
Pattern: ^[A-Za-z]{2}$
is_brand
boolean
default:false

Whether this organization is a brand owner.

is_recall_observer
boolean
default:false

Opt this organization into the global recall feed as an observer at creation time. No catalog onboarding (product, brand, or GTIN claim) is required — this is the complete signup path for an observer subscriber (C-4355).

issue_api_key
boolean
default:false

Return a manager-role API key for the new organization in this response.

An API key acts only on the organization it belongs to, and keys cannot mint keys, so this is how an integrator that provisions organizations obtains a credential for each one. The key is scoped to the new organization only, is shown exactly once, and is never retrievable again — store it before doing anything else. Further keys must be created by a signed-in member.

Required when the caller is an API key, which must hold the manager role on its own organization: without it the caller would create an organization it can never read, change or remove.

provision_billing
boolean
default:true

Whether to queue Stripe provisioning for the new organization.

Left true (the default), creating an organization queues a task that creates a live Stripe Customer and Subscription on the FREE tier. That is right for a human signup and wrong for a bulk import: seeding one organization per imported retailer and brand would request thousands of Stripe objects for organizations with no human in them. Sending false skips only that task and records the omission on the organization, so the missing subscription is a visible state rather than a side effect nobody can account for. Everything else is unchanged: the caller still becomes OWNER, the retention policy is still created, and the organization is immediately invite-ready.

false requires a staff account or the catalog-import service account; any other caller sending it is rejected with 403.

A service account must send this field explicitly — true or false — and is rejected with 422 if it omits it. The default is for interactive callers and is not inherited by a script: an importer that simply forgot the flag would silently request thousands of live Stripe customers, which is the outcome the option exists to prevent.

Response

OK

id
string<shortuuid>
required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
name
string
required

Organization name.

country
string
required

ISO 3166-1 alpha-2 country code.

is_brand
boolean
required

Whether this organization is a brand owner.

is_recall_observer
boolean
required

Whether this organization is subscribed to the global recall feed as an observer — webhook endpoints on this organization receive every recall lifecycle event, not just ones affecting products it owns. Independent of is_brand and of owning any products.

metadata
Metadata · object

Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.

api_key
string | null

The new organization's founding API key (manager role), present only when the request sent issue_api_key: true. Shown once; it cannot be retrieved later.