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

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstringRequired

The organization ID

Body

application/json

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

404

Resource not found

application/json

422

Request validation failed

application/json

post

/organizations/{organizationId}/workspaces

HTTPcURLJavaScriptPython

POST /organizations/{organizationId}/workspaces HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
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": "2026-01-27T16:24:46.664Z",
      "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": "2026-01-27T16:24:46.664Z",
  "updatedAt": "2026-01-27T16:24:46.664Z"
}

Example request

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