# Workspace

Workspaces are bank accounts. They have independent balances, statements, operations and permissions. The only property that is shared between your workspaces is the link they have to your organization, which carries your basic information, such as tax ID, name, etc...

The main reason for automating the creation of multiple Workspaces is to use our infrastructure to divide your own customers into different buckets, setting them up with isolated balances and statements.

### The Workspace object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique identifier for the workspace. |
| `allowedTaxIds` | LIST OF STRINGS | Tax IDs allowed to send Deposits to this workspace. If empty, all are allowed. |
| `created` | STRING | Creation datetime of the workspace. Example: "2020-04-23T23:00:00.000000+00:00". |
| `name` | STRING | Display name of the workspace shown in the Web Banking interface. |
| `organizationId` | STRING | ID of the organization that owns this workspace. |
| `pictureUrl` | STRING | URL of the workspace profile picture. |
| `status` | STRING | Current workspace status. Options: "active", "blocked", "frozen" or "closed". |
| `username` | STRING | Unique URL-safe identifier for the workspace. This is part of the Workspace Web Banking URL. |

### Create a Workspace

`POST /v2/workspace`

Here you can create a brand new Workspace.

Note: Only [Organization](https://docs.starkbank.com/api.md#authentication) credentials are able to create Workspaces.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `name` | REQUIRED | This string will show up to identify your Workspace when you log into it at our Web Banking. Example: 'My Workspace' |
| `username` | REQUIRED | This string uniquely identifies the Workspace in our entire database. It is also part of the Workspace Web Banking URL and must, therefore, be URL-safe. For example, if a Workspace in Sandbox has the 'my-workspace' username, its URL would be "https://my-workspace.sandbox.starkbank.com" |
| `allowedTaxIds` | OPTIONAL | List of tax IDs that will be allowed to send Deposits to this Workspace. If empty, all are allowed. Example: ``` ["012.345.678-90", "20.018.183/0001-80"] ``` |

**Request**

```python
import starkbank

workspace = starkbank.workspace.create(
    username="iron-bank-123",
    name="Iron Bank #123"
)

print(workspace)
```

**Response**

```python
  Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656,
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

### List Workspaces

`GET /v2/workspace`

Get a list of Workspaces your credentials have access to in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of IDs of the Workspaces to be retrieved. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `username` | OPTIONAL | Workspace username to be searched. |

**Request**

```python
import starkbank

workspaces = starkbank.workspace.query()

for workspace in workspaces:
    print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000,
)
```

### Get a Workspace

`GET /v2/workspace/:id`

Get a single workspace by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the workspace entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

workspace = starkbank.workspace.get("6225875037061120")

print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=iron-bank-123,
    name=Iron Bank #123,
    allowed_tax_ids=[],
    status=active,
    organization_id=5656565656565656
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

### Update a Workspace

`PATCH /v2/workspace/:id`

Update a workspace by passing its id and the fields you want to update.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the workspace. |
| `allowedTaxIds` | OPTIONAL | List of tax IDs that will be allowed to send Deposits to this Workspace. If empty, all are allowed. Example: ``` ["012.345.678-90", "20.018.183/0001-80"] ``` |
| `name` | OPTIONAL | Full name that identifies the Workspace. This name will appear when people access the Workspace on our platform, for example. Example: 'Stark Bank Workspace' |
| `picture` | OPTIONAL | Binary buffer of the picture. Example: open("path/to/picture.png", "rb").read() |
| `pictureType` | CONDITIONALLY REQUIRED | Picture mime type. This parameter will be required if the picture parameter is informed. Example: 'image/png' or 'image/jpeg' |
| `status` | OPTIONAL | You can block or activate a specific Workspace. Example: 'active' or 'blocked' |
| `username` | OPTIONAL | Simplified name to define the workspace URL. This name must be unique across all Stark Bank Workspaces. Example: 'starkbank-workspace' |

**Request**

```python
import starkbank

picture = open("path/to/picture.png", "rb").read()

workspace = starkbank.workspace.update(
    "6225875037061120",
    username="new-username",
    name="New Name",
    allowed_tax_ids=["012.345.678-90"],
    picture=picture,
    picture_type="image/png",
    status="blocked",
)

print(workspace)
```

**Response**

```python
Workspace(
    id=6225875037061120,
    username=new-username,
    name=New Name,
    allowed_tax_ids=['012.345.678-90'],
    status=blocked,
    organization_id=5656565656565656,
    picture_url=https://storage.googleapis.com/api-ms-workspace-sbx.appspot.com/pictures/workspace/6341320293482496.png?20230314201348,
    created=2020-04-23 23:00:00.000000
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/workspace-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/workspace-node.md)
- [PHP](https://docs.starkbank.com/api/v2/workspace-php.md)
- [Java](https://docs.starkbank.com/api/v2/workspace-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/workspace-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/workspace-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/workspace-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/workspace-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/workspace-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/workspace-curl.md)