API ReferenceOrganizations

Create

Onboards the authenticated user's partner Organization: creates the local Organization + the creator's admin membership atomically, then mirrors it to WorkOS (creates the WorkOS org and binds the creator as admin). A user may hold several organizations and selects which one a request acts as with the `X-Vitable-Organization` header. The founder's email domain is claimed only when no other organization holds it, so a taken domain is left with its owner rather than rejected.

Authentication

AuthorizationBearer

API Key or Access Token authentication using Bearer token in Authorization header. API keys use the vit_apk_ prefix, access tokens use the vit_at_ prefix.

Request

This endpoint expects an object.
namestringRequired1-255 characters
Legal or trading name of the organization.
typeenum or nullOptional
Category of organization being onboarded.

Response headers

X-RateLimit-Limitinteger
Maximum number of requests allowed within the rate limit window
X-RateLimit-Remaininginteger
Number of requests remaining in the current rate limit window
X-RateLimit-Resetinteger

Unix timestamp (seconds) when the rate limit window resets

Response

idstring

Prefixed organization identifier (org_<base64-encoded-uuid>).

namestring

Human-readable organization name.

typeenum or null

Partner type (e.g. BROKERAGE, TPA).

  • BROKERAGE - Brokerage
  • TPA - TPA
  • GENERAL_AGENT - General Agent
  • CHANNEL_PARTNER - Channel Partner
  • CONSULTING_FIRM - Consulting Firm
  • API_PLATFORM - API Platform
idp_org_idstring or null

IdP-issued tenant id (WorkOS org id).

idp_providerenum or null

IdP that minted idp_org_id (e.g. ‘workos’).

  • workos - WorkOS
  • vitable - Vitable
super_inboolean
Whether this organization reads across every organization.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error