> For the complete documentation index, see [llms.txt](https://guides.tability.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.tability.io/api/tability-api/api-reference/memberships.md).

# Memberships

### Notes

Tability uses a model where users can be part of multiple workspaces with the same account.

As such, access management in a workspaces is done via the memberships model.

### `GET` all the memberships in a specific workspace

<mark style="color:blue;">`GET`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships`

#### Path Parameters

| Name                                           | Type   | Description                |
| ---------------------------------------------- | ------ | -------------------------- |
| :workspaceID<mark style="color:red;">\*</mark> | String | Unique ID of the workspace |

#### Request Body

| Name | Type   | Description                                                                                                                |
| ---- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| page | number | Identifier of the page results to fetch                                                                                    |
| name | string | Name or email of a specific user to search                                                                                 |
| role | string | <p>Return the list of users corresponding to a specific role.</p><p></p><p>One of 'owner', 'admin', 'user', 'readonly'</p> |

{% tabs %}
{% tab title="200: OK" %}

```json
[
    {
        "id": "62e10e3c-b227-427a-9500-7c528c8f915a",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "8abfb48d-53f8-4e4e-8f14-9667187170b4",
        "role": "readonly",
        "created_at": "2024-12-27T12:34:40.529Z",
        "updated_at": "2025-01-22T00:51:17.896Z",
        "cached_email": "john.doe@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": "1810e8d9-5c91-4e5b-8e5d-2e621e1741a0"
    },
    {
        "id": "e992f480-482c-489c-9660-7233c5d52f23",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "81c05928-95a5-4f13-84c0-80d8bc87da8f",
        "role": "owner",
        "created_at": "2024-12-27T12:34:40.863Z",
        "updated_at": "2024-12-27T12:34:40.863Z",
        "cached_email": "jane.smith@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    },
    {
        "id": "aafbc166-456a-456c-8fca-aec45173348a",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "bf88170d-1f6f-4c60-b400-82f50588440d",
        "role": "user",
        "created_at": "2024-12-27T12:34:41.204Z",
        "updated_at": "2024-12-27T12:34:41.204Z",
        "cached_email": "mike.adams@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    }
]
   
```

{% endtab %}
{% endtabs %}

### `GET` the details for a specific membership

<mark style="color:blue;">`GET`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/:membershipID`

#### Path Parameters

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| :workspaceID<mark style="color:red;">\*</mark>  | String | Unique ID of the workspace  |
| :membershipID<mark style="color:red;">\*</mark> | String | Unique ID of the membership |

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "id": "03277b3b-4808-4ef1-b23f-5d97850f0c7c",
    "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
    "user_id": "1506021e-f066-4c01-8bdd-0a736fe7d46b",
    "role": "user",
    "created_at": "2024-12-03T05:41:43.649Z",
    "updated_at": "2025-01-11T03:41:04.053Z",
    "cached_email": "sten.pittet@gmail.com",
    "cached_firstname": "Sten",
    "cached_lastname": "Pittet",
    "cached_avatar_url": "",
    "outcome_progress_prct": 0.0,
    "initiative_progress_prct": 0.0,
    "red_outcomes_count": 0,
    "yellow_outcomes_count": 1,
    "green_outcomes_count": 0,
    "grey_outcomes_count": 0,
    "total_outcomes_count": 1,
    "pending_checkins_count": 0,
    "ncs": 0.0,
    "total_initiatives_count": 0,
    "closed_initiatives_count": 0,
    "manager_id": "63bd699b-69cc-4a99-bef9-1649963257aa"
}
```

{% endtab %}
{% endtabs %}

### GET the manager for a specific membership

<mark style="color:blue;">`GET`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/:membershipID/manager`

#### Path Parameters

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| :workspaceID<mark style="color:red;">\*</mark>  | String | Unique ID of the workspace  |
| :membershipID<mark style="color:red;">\*</mark> | String | Unique ID of the membership |

{% tabs %}
{% tab title="200: OK OK" %}

```json
{
    "id": "63bd699b-69cc-4a99-bef9-1649963257aa",
    "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
    "user_id": "59f5655c-25b3-4e1a-bf97-2e99be39b870",
    "role": "owner",
    "created_at": "2024-12-03T04:45:17.916Z",
    "updated_at": "2025-01-22T01:05:36.229Z",
    "cached_email": "sten@tability.io",
    "cached_firstname": "Sten",
    "cached_lastname": "Pittet",
    "cached_avatar_url": "https://res.cloudinary.com/tability-dev/image/upload/c_thumb,g_face,w_250,z_0.75/v1712371048/2.0-dev/59f5655c-25b3-4e1a-bf97-2e99be39b870/3f39d28c-540c-4eee-8c75-e60cd2cc0664.jpg",
    "outcome_progress_prct": 0.0717241379310345,
    "initiative_progress_prct": 0.0,
    "red_outcomes_count": 1,
    "yellow_outcomes_count": 2,
    "green_outcomes_count": 3,
    "grey_outcomes_count": 24,
    "total_outcomes_count": 30,
    "pending_checkins_count": 2,
    "ncs": 6.66666666666667,
    "total_initiatives_count": 5,
    "closed_initiatives_count": 0,
    "manager_id": "62e10e3c-b227-427a-9500-7c528c8f915a"
}
```

{% endtab %}
{% endtabs %}

### `GET` the direct reports for a specific membership

<mark style="color:blue;">`GET`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/:membershipID/direct_reports`

#### Path Parameters

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| :workspaceID<mark style="color:red;">\*</mark>  | String | Unique ID of the workspace  |
| :membershipID<mark style="color:red;">\*</mark> | String | Unique ID of the membership |

{% tabs %}
{% tab title="200: OK" %}

```json
[
    {
        "id": "d5bd715c-7427-45ce-a81f-c00912eaead7",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "3ff8aa24-f0d1-46f6-9f3a-3a89d4627836",
        "role": "readonly",
        "created_at": "2024-12-27T12:35:00.419Z",
        "updated_at": "2025-01-11T11:51:10.207Z",
        "cached_email": "a4@email.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": "63bd699b-69cc-4a99-bef9-1649963257aa"
    },
    {
        "id": "1810e8d9-5c91-4e5b-8e5d-2e621e1741a0",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "58b797b1-65fc-4329-9ba7-1b557bec2b28",
        "role": "readonly",
        "created_at": "2024-12-27T12:35:00.753Z",
        "updated_at": "2025-01-11T11:51:13.276Z",
        "cached_email": "a5@email.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": "63bd699b-69cc-4a99-bef9-1649963257aa"
    },
    {
        "id": "803ac79e-80b9-43d8-af8a-8920bf46aad3",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "5340315f-f14d-4168-ae39-7faa2dabd5bc",
        "role": "user",
        "created_at": "2024-12-27T12:36:11.335Z",
        "updated_at": "2025-01-11T11:51:37.589Z",
        "cached_email": "b1@email.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": "63bd699b-69cc-4a99-bef9-1649963257aa"
    }
]
```

{% endtab %}
{% endtabs %}

### `UPDATE` the details for a specific membership

<mark style="color:blue;">`PUT`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/:membershipID`

#### Path Parameters

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| :workspaceID<mark style="color:red;">\*</mark>  | String | Unique ID of the workspace  |
| :membershipID<mark style="color:red;">\*</mark> | String | Unique ID of the membership |

#### Body

| Name         | Type   | Description                                                   |
| ------------ | ------ | ------------------------------------------------------------- |
| :role        | String | Role of the user. One of 'owner', 'admin', 'user', 'readonly' |
| :manager\_id | String | Unique ID of the membership corresponding to the manager      |

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "id": "03277b3b-4808-4ef1-b23f-5d97850f0c7c",
    "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
    "user_id": "1506021e-f066-4c01-8bdd-0a736fe7d46b",
    "role": "user",
    "created_at": "2024-12-03T05:41:43.649Z",
    "updated_at": "2025-01-11T03:41:04.053Z",
    "cached_email": "sten.pittet@gmail.com",
    "cached_firstname": "Sten",
    "cached_lastname": "Pittet",
    "cached_avatar_url": "",
    "outcome_progress_prct": 0.0,
    "initiative_progress_prct": 0.0,
    "red_outcomes_count": 0,
    "yellow_outcomes_count": 1,
    "green_outcomes_count": 0,
    "grey_outcomes_count": 0,
    "total_outcomes_count": 1,
    "pending_checkins_count": 0,
    "ncs": 0.0,
    "total_initiatives_count": 0,
    "closed_initiatives_count": 0,
    "manager_id": "63bd699b-69cc-4a99-bef9-1649963257aa"
}
```

{% endtab %}
{% endtabs %}

### `DELETE` a specific membership

<mark style="color:blue;">`DELETE`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/:membershipID`

#### Path Parameters

| Name                                            | Type   | Description                               |
| ----------------------------------------------- | ------ | ----------------------------------------- |
| :workspaceID<mark style="color:red;">\*</mark>  | String | Unique ID of the workspace                |
| :membershipID<mark style="color:red;">\*</mark> | String | Unique ID of the membership (can be UUID) |

{% tabs %}
{% tab title="204: No Content" %}

{% endtab %}
{% endtabs %}

### `POST` Add new users to your workspace

<mark style="color:blue;">`POST`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/`

#### Path Parameters

| Name                                           | Type            | Description                                           |
| ---------------------------------------------- | --------------- | ----------------------------------------------------- |
| :workspaceID<mark style="color:red;">\*</mark> | String          | Unique ID of the workspace                            |
| :emails<mark style="color:red;">\*</mark>      | Array of emails | Array of all emails to add, limited to 50 per request |

{% tabs %}
{% tab title="201: CREATED" %}

```json
[
    {
        "id": "81309a30-b8c2-44cc-91d6-7b6166a3390f",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "100ab081-db6b-453f-81c3-d70168b23249",
        "role": "user",
        "created_at": "2025-01-22T01:38:28.355Z",
        "updated_at": "2025-01-22T01:38:28.355Z",
        "cached_email": "john@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    },
    {
        "id": "143c6253-9175-40db-ba85-bc2bf7853852",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "7b02d6d4-7fee-42e4-b290-72c89dee8ceb",
        "role": "user",
        "created_at": "2025-01-22T01:38:28.710Z",
        "updated_at": "2025-01-22T01:38:28.710Z",
        "cached_email": "david@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    },
    {
        "id": "7df68be2-b6fb-4f76-963c-df194ea0f475",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "e29db59e-68e9-49c5-8078-3ee38b3f5e2b",
        "role": "user",
        "created_at": "2025-01-22T01:38:29.070Z",
        "updated_at": "2025-01-22T01:38:29.070Z",
        "cached_email": "eva@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    }
]
```

{% endtab %}
{% endtabs %}

### `POST` Add readonly users to your workspace

<mark style="color:blue;">`POST`</mark> `https://api.tability.app/v2/workspaces/:workspaceID/memberships/free`

#### Path Parameters

| Name                                           | Type            | Description                                           |
| ---------------------------------------------- | --------------- | ----------------------------------------------------- |
| :workspaceID<mark style="color:red;">\*</mark> | String          | Unique ID of the workspace                            |
| :emails<mark style="color:red;">\*</mark>      | Array of emails | Array of all emails to add, limited to 50 per request |

{% tabs %}
{% tab title="201: CREATED" %}

```json
[
    {
        "id": "81309a30-b8c2-44cc-91d6-7b6166a3390f",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "100ab081-db6b-453f-81c3-d70168b23249",
        "role": "readonly",
        "created_at": "2025-01-22T01:38:28.355Z",
        "updated_at": "2025-01-22T01:38:28.355Z",
        "cached_email": "john@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    },
    {
        "id": "143c6253-9175-40db-ba85-bc2bf7853852",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "7b02d6d4-7fee-42e4-b290-72c89dee8ceb",
        "role": "readonly",
        "created_at": "2025-01-22T01:38:28.710Z",
        "updated_at": "2025-01-22T01:38:28.710Z",
        "cached_email": "david@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    },
    {
        "id": "7df68be2-b6fb-4f76-963c-df194ea0f475",
        "workspace_id": "6bd9a8cf-72fd-44eb-980e-e7311a5f2de2",
        "user_id": "e29db59e-68e9-49c5-8078-3ee38b3f5e2b",
        "role": "readonly",
        "created_at": "2025-01-22T01:38:29.070Z",
        "updated_at": "2025-01-22T01:38:29.070Z",
        "cached_email": "eva@company.com",
        "cached_firstname": "",
        "cached_lastname": "",
        "cached_avatar_url": "",
        "outcome_progress_prct": 0.0,
        "initiative_progress_prct": 0.0,
        "red_outcomes_count": 0,
        "yellow_outcomes_count": 0,
        "green_outcomes_count": 0,
        "grey_outcomes_count": 0,
        "total_outcomes_count": 0,
        "pending_checkins_count": 0,
        "ncs": 0.0,
        "total_initiatives_count": 0,
        "closed_initiatives_count": 0,
        "manager_id": null
    }
]
```

{% endtab %}
{% endtabs %}