> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Organizations and workspaces: your team and your brands

> Group your people and your brands, and decide who sees what: an administrator sees every workspace, a member only the ones it was given.

An agency runs WhatsApp for twelve shops: one organization, with a workspace for each shop. A workspace holds one [WhatsApp connection](https://heythere.io/docs/concepts/whatsapp-connection) with its [contacts](https://heythere.io/docs/concepts/contacts), [conversations](https://heythere.io/docs/concepts/conversations), [message templates](https://heythere.io/docs/concepts/message-templates), and [automations](https://heythere.io/docs/concepts/automations). Karim, who owns the garage, wants to answer his own customers, without seeing the customers of the eleven other shops.

## Who sees which workspace?

A member's access is `admin` or `member`:

- An administrator of the organization administers every workspace. Its creator becomes the first one, and it always keeps one.
- A member works only in the workspaces it was given, with the role `admin` or `member` in each. Karim gets the garage's workspace, and nothing else reaches him: not the other shops' contacts, conversations, or notifications, nor the organization's members. A freelancer handling two shops gets those two.

## What does an administrator do that a member cannot?

In a workspace, only its administrators connect WhatsApp, send a [broadcast](https://heythere.io/docs/concepts/broadcasts), and publish an automation [version](https://heythere.io/docs/concepts/versions), since these message contacts. Every member works with its contacts, conversations, templates, and automations, and `listWorkspaceMembers` shows who else does.

Only an administrator of the organization renames or deletes it, manages its workspaces, invites people, reads its [usage](https://heythere.io/docs/concepts/usage), and changes what each member works in with `updateOrganizationMemberAccess`.

## How does a person join an organization?

An administrator invites their phone number, as an administrator or into chosen workspaces. Heythere sends no message, so tell Karim to sign in to Heythere with that number within 7 days, and he joins with the invited access.

## What does a workspace's map show?

Every WhatsApp number of the workspace, each with its [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-), the events it starts at, and its latest [broadcasts](https://heythere.io/docs/concepts/broadcasts), with how far each went. The console shows it on the automations page, and `getWorkspaceMap` returns it to an agent.

## How does an agent choose an organization and a workspace?

An agent or [API key](https://heythere.io/docs/concepts/api-access) acts as its user, and sees what that user sees. `listOrganizations` and then `listOrganizationWorkspaces` give the IDs that every other operation names in its path.

Deleting a workspace or an organization is permanent: it erases their contacts, conversations, messages, and automations.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `createOrganization`: Create an organization. `POST /api/organizations`
- `listOrganizations`: List joined organizations. `GET /api/organizations`
- `getOrganization`: Get an organization. `GET /api/organizations/{organizationId}`
- `updateOrganization`: Update an organization. `PATCH /api/organizations/{organizationId}`
- `deleteOrganization`: Delete an organization. `DELETE /api/organizations/{organizationId}`
- `listOrganizationMembers`: List organization members. `GET /api/organizations/{organizationId}/members`
- `updateOrganizationMemberAccess`: Replace what an organization member works in. `PUT /api/organizations/{organizationId}/members/{memberId}/access`
- `removeOrganizationMember`: Remove an organization member. `DELETE /api/organizations/{organizationId}/members/{memberId}`
- `inviteOrganizationMember`: Invite an organization member. `POST /api/organizations/{organizationId}/invitations`
- `listOrganizationInvitations`: List organization invitations. `GET /api/organizations/{organizationId}/invitations`
- `getOrganizationInvitation`: Get an organization invitation. `GET /api/organizations/{organizationId}/invitations/{invitationId}`
- `revokeOrganizationInvitation`: Revoke an organization invitation. `DELETE /api/organizations/{organizationId}/invitations/{invitationId}`
- `listReceivedOrganizationInvitations`: List received organization invitations. `GET /api/organization-invitations`
- `acceptOrganizationInvitation`: Accept an organization invitation. `POST /api/organization-invitations/{invitationId}/acceptance`
- `declineOrganizationInvitation`: Decline an organization invitation. `DELETE /api/organization-invitations/{invitationId}`
- `createWorkspace`: Create a workspace. `POST /api/organizations/{organizationId}/workspaces`
- `listOrganizationWorkspaces`: List organization workspaces. `GET /api/organizations/{organizationId}/workspaces`
- `getWorkspace`: Get a workspace. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}`
- `listWorkspaceMembers`: List the people who work in a workspace. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/members`
- `renameWorkspace`: Rename a workspace. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}`
- `deleteWorkspace`: Delete a workspace. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}`
- `getWorkspaceMap`: Get the workspace map. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/map`
