Logo
Sign Up

Organizations API

Create organizations, read/update/delete by id, and manage organization members.

Organizations API

Overview

This API lets you manage organization accounts (teams) and their members. Use the base route to create organizations. Use the id route to read, update, or delete an organization. Manage memberships under a nested members route.

Base path: /api/v1/organizations

Authentication

All endpoints require authentication. Include a valid Bearer token in the Authorization header: Authorization: Bearer <access_token>.

Response envelope

{
  "success": true,
  "message": "optional human readable message",
  "data": {},
  "count": 1,
  "error": "error text"
}

Endpoints

Create organization

POST /api/v1/organizations

Body (JSON):

  • name (string, required)
  • primary_owner_user_id (uuid, required)

Notes

  • Personal accounts cannot be created here; organizations are created with is_personal_account=false.

Response 201 — created organization object in data.

Get organization

GET /api/v1/organizations/:id

Path parameters

  • id (uuid)

Response 200 — organization object in data.

Update organization

PUT /api/v1/organizations/:id

Path parameters

  • id (uuid)

Body (JSON):

  • Mutable fields such as name, email, picture_url, public_data

Response 200 — updated organization object in data.

Delete organization

DELETE /api/v1/organizations/:id

Path parameters

  • id (uuid)

Response 204 — organization deleted. Response 409 — organization has dependent records and cannot be deleted.

Notes

  • Personal accounts cannot be deleted through this endpoint.
  • Deletion is subject to the caller's authorization for the organization.

List organization members

GET /api/v1/organizations/:id/members

Path parameters

  • id (uuid) — organization id

Response 200 — data is an array of memberships from accounts_memberships for the organization, with count.

Add member to organization

POST /api/v1/organizations/:id/members

Path parameters

  • id (uuid)

Body (JSON):

  • userId (uuid, required) — existing user id
  • role (string, required) — role name to assign

Response 201 — created membership record in data.

Remove member from organization

DELETE /api/v1/organizations/:id/members/:userId

Path parameters

  • id (uuid)
  • userId (uuid)

Response 204 / success envelope with no content.

Notes

  • Attempting to remove the primary owner will fail.

Notes

  • Sorting and pagination conventions apply on list endpoints where provided.