# 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](/api/accounts-api/api-reference/organizations/workspaces.md) you should associate the workspace ID with the customer account in your platform.

{% hint style="info" %}
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.
{% endhint %}

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

> Create a workspace for the organization.

```json
{"openapi":"3.0.3","info":{"title":"Accounts","version":"v1"},"tags":[{"description":"Manage organization workspaces.","name":"organization_workspace"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWorkspace":{"type":"object","additionalProperties":false,"properties":{"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicyCreate"},"configuration":{"nullable":true,"$ref":"#/components/schemas/WorkspaceConfiguration"},"userUsername":{"nullable":true,"description":"The username of the user that is creating the workspace.","$ref":"#/components/schemas/WorkspaceIdentifier"},"flavors":{"nullable":true,"type":"array","items":{"type":"string"}}},"required":["name","dataPolicy"]},"WorkspaceName":{"type":"string","description":"The display name for the workspace","minLength":1,"maxLength":256},"WorkspaceDescription":{"type":"string","description":"The description for the workspace","minLength":1,"maxLength":256},"DataPolicyCreate":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage. Must be one of `us-west-2`, `eu-west-1`, or `ap-south-1`."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region. Must be one of `us-west-2`, `eu-west-1`, or `ap-south-1`."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}}},"required":["group","regions"]},"WorkspaceConfiguration":{"type":"object","additionalProperties":false,"properties":{"domain":{"$ref":"#/components/schemas/DomainName"}}},"DomainName":{"type":"string","description":"Domain name.","format":"domain","pattern":"^(([a-zA-Z0-9]([a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z]{2,})?$","maxLength":253},"WorkspaceIdentifier":{"type":"string","pattern":"^[a-z0-9._-]+$","description":"The identifier of the resource inside the workspace.  Takes the form of the user component of an email address.\n"},"Workspace":{"title":"Workspace","description":"The workspace record.","type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Workspace ID.","format":"uuid"},"organizationId":{"type":"string","description":"ID of the organization this workspace is part of.","format":"uuid"},"status":{"$ref":"#/components/schemas/WorkspaceStatus"},"statusTransitions":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceStatusTransition"}},"name":{"$ref":"#/components/schemas/WorkspaceName"},"description":{"$ref":"#/components/schemas/WorkspaceDescription"},"dataPolicy":{"$ref":"#/components/schemas/DataPolicy"},"configuration":{"$ref":"#/components/schemas/WorkspaceConfiguration"},"createdAt":{"type":"string","format":"date-time","description":"When the workspace was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the workspace was last updated."}},"required":["id","organizationId","status","name","dataPolicy","createdAt","updatedAt"]},"WorkspaceStatus":{"type":"string","description":"Status of the workspace","enum":["active","disabled","terminated","deleted"]},"WorkspaceStatusTransition":{"type":"object","description":"Workspace status transition","required":["fromStatus","toStatus","reason","transitionedAt","transitionedBy"],"properties":{"fromStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"toStatus":{"$ref":"#/components/schemas/WorkspaceStatus"},"reason":{"type":"string","enum":["org-banned","user-initiated","payment-default","inactivity"]},"comment":{"type":"string"},"transitionedAt":{"type":"string","format":"date-time"},"transitionedBy":{"$ref":"#/components/schemas/RequestSubject"}}},"RequestSubject":{"required":["type","id"],"properties":{"type":{"$ref":"#/components/schemas/RequestSubjectType"},"id":{"type":"string","format":"uuid"}}},"RequestSubjectType":{"type":"string","enum":["user","accesskey","contact"]},"DataPolicy":{"type":"object","title":"DataPolicy","description":"The data storage policy for a resource.","properties":{"group":{"type":"string","description":"The name of the region group used for storage."},"regions":{"type":"array","items":{"type":"object","title":"RegionPriority","properties":{"region":{"type":"string","description":"The name of the AWS region."},"priority":{"type":"integer","minimum":0,"description":"The priority to give to this region when storing data."}},"required":["region","priority"]}},"piiStrategy":{"type":"string","enum":["default","strict"]}},"required":["group","regions","piiStrategy"]},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"}}},"DetailedError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Unique identifier for the error that occurred"},"message":{"type":"string","description":"Description of the error that occurred, aimed at API consumers"},"details":{"type":"object","description":"Detailed information on where the error exists, usually the field name on the request payload","additionalProperties":{"type":"array","description":"The error description for the specific detail","items":{"type":"string"}}}}}},"responses":{"notFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Resource not found"},"invalidRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedError"}}},"description":"Request validation failed"}}},"paths":{"/organizations/{organizationId}/workspaces":{"post":{"description":"Create a workspace for the organization.","operationId":"createWorkspace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspace"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}},"description":"Created"},"404":{"$ref":"#/components/responses/notFound"},"422":{"$ref":"#/components/responses/invalidRequest"}},"summary":"Create workspace","tags":["organization_workspace"]}}}}
```

{% tabs %}
{% tab title="Example request" %}
{% code overflow="wrap" %}

```bash
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}]
    }
}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% content-ref url="/pages/cz8SN6Vjwh2V0LIGwB3T" %}
[Buying a number through Bird](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/setting-up-your-customer-workspaces/buying-a-number-through-bird.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/setting-up-your-customer-workspaces/creating-a-workspace-for-your-customer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.