No-code docs

Creating a workspace for your customer

For every customer that you want to onboard onto WhatsApp in your platform you should create a separate workspace in Bird CRM. This will ensure that your customers resources including phone numbers, messages templates and channels are kept separate from other customers.

Once you have created a workspace you should associate the workspace ID with the customer account in your platform.

Note: As best practice you can also create an access key, role and policy scoped to each customer workspace. See the following documentations to create access keys, policies and roles programmatically.

To create a new workspace make the following request. The region parameter you specify will determine where your customers data is hosted in Bird CRM. The following workspaces are available as options:

  • eu-west-1

  • ap-south-1

  • us-west-1

Create workspace

post

Create a workspace for the organization.

Authorizations
Path parameters
organizationIdstringRequired

The organization ID

Body
namestring · min: 1 · max: 256Required

The display name for the workspace

descriptionstring · min: 1 · max: 256Optional

The description for the workspace

userUsernamestring | nullableOptional

The username of the user that is creating the workspace.

Pattern: ^[a-z0-9._-]+$
flavorsstring[] | nullableOptional
Responses
201
Created
application/json
post
POST /organizations/{organizationId}/workspaces HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 201

{
  "name": "text",
  "description": "text",
  "dataPolicy": {
    "group": "eu-west-1",
    "regions": [
      {
        "region": "eu-west-1",
        "priority": 1
      }
    ]
  },
  "configuration": {
    "domain": "example.com"
  },
  "userUsername": "text",
  "flavors": [
    "text"
  ]
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "statusTransitions": [
    {
      "fromStatus": "active",
      "toStatus": "active",
      "reason": "org-banned",
      "comment": "text",
      "transitionedAt": "2025-07-13T03:25:52.223Z",
      "transitionedBy": {
        "type": "user",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  ],
  "name": "text",
  "description": "text",
  "dataPolicy": {
    "group": "eu-west-1",
    "regions": [
      {
        "region": "eu-west-1",
        "priority": 1
      }
    ],
    "piiStrategy": "default"
  },
  "configuration": {
    "domain": "example.com"
  },
  "createdAt": "2025-07-13T03:25:52.223Z",
  "updatedAt": "2025-07-13T03:25:52.223Z"
}
curl --location 'https://api.bird.com/organizations/{{orgId}}/workspaces' \
--header 'Content-Type: application/json' \
--header 'Authorization: AccessKey {{key}}' \
--data '{
    "name":"{{name}}",
    "Description":"{{description}}",
    "dataPolicy":{
        "Group":"{{region}}"
        "regions":[{"region":"{{region}}","priority":0}]
    }
}'
Buying a number through Bird

Last updated

Was this helpful?