Organizations

Overview

Whatomate is multi-tenant — each organization has its own isolated data (contacts, conversations, templates, etc.). Users can belong to multiple organizations with different roles in each.

List Organizations

Retrieve all organizations. Requires super admin or organizations:read permission.

GET /api/organizations

Response

{
  "status": "success",
  "data": {
    "organizations": [
      {
        "id": "uuid",
        "name": "Acme Corp",
        "slug": "acme-corp-a1b2c3d4",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Current Organization

Retrieve the current organization’s details.

GET /api/organizations/current

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Acme Corp",
    "slug": "acme-corp-a1b2c3d4",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Create Organization

Create a new organization. The creator is automatically added as an admin. System roles (Admin, Manager, Agent) and default chatbot settings are seeded automatically.

POST /api/organizations

Note

Requires organizations:write permission.

Request Body

{
  "name": "New Organization"
}

Field	Type	Required	Description
name	string	Yes	Organization name

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "New Organization",
    "slug": "new-organization-a1b2c3d4",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Organization Members

Manage which users have access to an organization. Members are users from other organizations who have been granted access with a specific role.

List Members

Retrieve all members of the current organization.

GET /api/organizations/members

Note

Requires organizations:read permission.

Query Parameters

Parameter	Type	Description
search	string	Filter by name or email
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50)

Response

{
  "status": "success",
  "data": {
    "members": [
      {
        "id": "uuid",
        "user_id": "uuid",
        "organization_id": "uuid",
        "role_id": "uuid",
        "role_name": "agent",
        "is_default": true,
        "email": "user@example.com",
        "full_name": "John Doe",
        "is_active": true,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Add Member

Add an existing user to the organization. The user can be identified by user_id or email.

POST /api/organizations/members

Note

Requires organizations:assign permission.

Request Body

{
  "user_id": "uuid",
  "role_id": "uuid"
}

Or by email:

{
  "email": "user@example.com",
  "role_id": "uuid"
}

Field	Type	Required	Description
user_id	string	One of user_id or email	UUID of the user to add
email	string	One of user_id or email	Email of the user to add
role_id	string	No	Role to assign. If omitted, uses the organization’s default role

Response

{
  "status": "success",
  "data": {
    "message": "Member added successfully"
  }
}

Update Member Role

Change a member’s role within the organization.

PUT /api/organizations/members/{member_id}

Note

Requires organizations:assign permission. The member_id is the user’s UUID.

Request Body

{
  "role_id": "uuid"
}

Response

{
  "status": "success",
  "data": {
    "message": "Member role updated successfully"
  }
}

Remove Member

Remove a user from the organization. This only removes the membership — the user’s account remains intact.

DELETE /api/organizations/members/{member_id}

Note

Requires organizations:assign permission.

Caution

You cannot remove yourself from the organization.

Response

{
  "status": "success",
  "data": {
    "message": "Member removed successfully"
  }
}

Organization Settings

Get Settings

GET /api/organizations/settings

Response

{
  "status": "success",
  "data": {
    "name": "Acme Corp",
    "settings": {
      "mask_phone_numbers": false,
      "timezone": "UTC",
      "date_format": "YYYY-MM-DD"
    }
  }
}

Update Settings

PUT /api/organizations/settings

Request Body

{
  "name": "Updated Name",
  "mask_phone_numbers": true,
  "timezone": "Asia/Kolkata",
  "date_format": "DD/MM/YYYY"
}

All fields are optional — only provided fields are updated.

See Also

• Authentication - Organization switching via POST /api/auth/switch-org
• Users - User management within an organization
• Roles & Permissions - Permission system details