Team APIs

Team APIs provide comprehensive team management capabilities including creating, updating, and managing teams within your organization. These APIs enable you to organize users into teams, assign roles, and control access permissions across your iMBRACE workspace.

1. Create Team

Create a new team within your organization.

This API allows you to create a new team with specified name, description, mode, and other team properties. Teams are used to organize users and control access to various features and data within your workspace.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v1/backend/teams

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v1/backend/teams

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v1/backend/teams

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body (JSON)

    {
    "business_unit_id": "{{business_unit_id}}",
    "name": "Sales",
    "mode": "grab",
    "icon_url": "",
    "description": "Sales team"
}

  • Request Parameters:

    • business_unit_id (string, required): The unique identifier of the business unit

    • name (string, required): The name of the team

    • mode (string, required): The team mode (e.g., "grab", "assign", "round_robin")

    • icon_url (string, optional): URL of the team icon

    • description (string, optional): Description of the team

  • Result:

    • Status code: 200 OK

    {
    "object_name": "team",
    "id": "t_35d4663e-ace7-4698-9348-dc30d5638c99",
    "organization_id": "org_imbrace",
    "business_unit_id": "bu_imbrace_testing",
    "name": "Sales",
    "icon_url": "",
    "description": "Sales team",
    "created_at": "2022-04-01T08:28:13.541Z",
    "updated_at": "2022-04-01T08:28:13.541Z",
    "team_user_ids": [
        "tu_974ef6cd-863d-418c-90c3-2b8ab1c3a7a8"
    ],
    "team_users": [
        {
            "object_name": "team_user",
            "id": "tu_974ef6cd-863d-418c-90c3-2b8ab1c3a7a8",
            "organization_id": "org_imbrace",
            "business_unit_id": "bu_imbrace_testing",
            "user_id": "u_imbrace_admin",
            "role": "admin",
            "created_at": "2022-04-01T08:28:13.545Z",
            "updated_at": "2022-04-01T08:28:13.545Z"
        }
    ]
}

  • Error Responses:

    • Status code: 400 Bad Request

    {
    "code": 40000,
    "message": "Team already exist"
}

    • Status code: 403 Forbidden

    {
    "code": 40003,
    "message": "Forbidden, insufficient permission"
}

  • Example:

    curl --location 'https://app-gateway.dev.imbrace.co/v1/backend/teams' \
--header 'X-Access-Token: acc_7c769464-4577-49da-abc4-b27b3866fcb9' \
--header 'Content-Type: application/json' \
--data '{
    "business_unit_id": "bu_imbrace_testing",
    "name": "Sales",
    "mode": "grab",
    "icon_url": "",
    "description": "Sales team"
}'

2. Add Multiple Users to Team

Add multiple users to an existing team in a single operation.

This API allows you to add multiple users to a team with their respective roles in one request. This is more efficient than adding users one by one and supports bulk operations.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/_add_users

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/_add_users

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/_add_users

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body (JSON)

  • Request Parameters:

    • team_id (string, required): The unique identifier of the team

    • reserve_leave (boolean, required): Whether to reserve leave for existing team members

    • users (array, required): Array of user objects to add to the team

      • user_id (string, required): The unique identifier of the user

      • role (string, required): The role to assign to the user

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

  • Example:

3. Join Team (for administrators)

Join an existing team as the current user.

This API allows the authenticated user to join a specific team. The user will be added to the team with appropriate permissions based on the team's configuration.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/_join_team

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/_join_team

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/_join_team

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body (JSON)

  • Request Parameters:

    • team_id (string, required): The unique identifier of the team to join

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

  • Example:

4. Request to Join Team

Request to join a specific team (requires team approval).

This API allows users to send a join request to a team. The request will need to be approved by team administrators before the user is added to the team.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/{team_id}/join_request

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}/join_request

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}/join_request

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team to request joining

  • Request Body:

    • No request body required

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

5. Get My Teams

Retrieve all teams that the current user is a member of.

This API allows users to fetch all teams they belong to, including their role within each team. This is useful for displaying team memberships in user interfaces and determining access permissions.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v2/backend/teams/my

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v2/backend/teams/my

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v2/backend/teams/my

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • None

  • Result:

    • Status code: 200 OK

  • Empty Result:

    • Status code: 200 OK (when user is not a member of any teams)

  • Example:

6. Get All Teams

Retrieve all teams within the organization that the user has access to.

This API allows users to fetch all teams in their organization, regardless of whether they are members or not. This is useful for administrative purposes, team discovery, and management interfaces.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v1/backend/teams/all

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v1/backend/teams/all

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v1/backend/teams/all

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • None

  • Result:

    • Status code: 200 OK

  • Example:

7. Get Teams with Filtering and Pagination

Retrieve teams with advanced filtering, pagination, and sorting options.

This API allows you to fetch teams with specific filters, pagination controls, and sorting. It's useful for building team management interfaces with search, filtering, and pagination capabilities.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v2/backend/teams?type=business_unit_id&limit=20&skip=0&sort=-created_at&q=bu_6cc91e00-d704-47e6-a21e-169bc96fe416

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v2/backend/teams?type=business_unit_id&limit=20&skip=0&sort=-created_at&q=bu_6cc91e00-d704-47e6-a21e-169bc96fe416

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v2/backend/teams?type=business_unit_id&limit=20&skip=0&sort=-created_at&q=bu_6cc91e00-d704-47e6-a21e-169bc96fe416

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • type (string, optional): Filter type (e.g., "business_unit_id")

    • limit (number, optional): Number of results per page (default: 20)

    • skip (number, optional): Number of results to skip for pagination (default: 0)

    • sort (string, optional): Sort field and direction (e.g., "-created_at" for descending)

    • q (string, optional): Filter value (e.g., business unit ID)

  • Result:

    • Status code: 200 OK

  • Example:

8. Get Team Users with Filtering and Pagination

Retrieve team members with advanced filtering, pagination, and detailed user information.

This API allows you to fetch team members with specific filters, pagination controls, and complete user details. It's useful for building team member management interfaces with search, filtering, and detailed user profiles.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v2/backend/team_users?type=team_id&q=t_imbrace_default_team&limit=20&skip=0

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v2/backend/team_users?type=team_id&q=t_imbrace_default_team&limit=20&skip=0

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v2/backend/team_users?type=team_id&q=t_imbrace_default_team&limit=20&skip=0

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • type (string, required): Filter type (e.g., "team_id")

    • q (string, required): Filter value (e.g., team ID)

    • limit (number, optional): Number of results per page (default: 20)

    • skip (number, optional): Number of results to skip for pagination (default: 0)

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 403 Forbidden

  • Example:

9. Get Team Invite List

Retrieve users who can be invited to join a specific team.

This API allows you to fetch a list of users who are eligible to be invited to join a team. This is useful for team management interfaces where you need to show available users for team invitations.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v2/backend/team_users/_invite_list?type=team_id&team_id=t_imbrace_default_team

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v2/backend/team_users/_invite_list?type=team_id&team_id=t_imbrace_default_team

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v2/backend/team_users/_invite_list?type=team_id&team_id=t_imbrace_default_team

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • type (string, required): Filter type (e.g., "team_id")

    • team_id (string, required): The team ID to get invite list for

  • Result:

    • Status code: 200 OK

  • Example:

10. Get Team Users by Team ID

Retrieve all users belonging to a specific team with detailed user information.

This API allows you to fetch all team members for a specific team with complete user profiles. It's useful for displaying team member lists, user directories, and team management interfaces.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v1/backend/team/{team_id}/users

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v1/backend/team/{team_id}/users

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v1/backend/team/{team_id}/users

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team

  • Result:

    • Status code: 200 OK

  • Example:

11. Update Team

Update an existing team's information including name, icon, and status.

This API allows you to modify team properties such as name, icon URL, and disabled status. It's useful for team management interfaces where administrators need to update team settings and configurations.

  • Endpoint for Product: PUT https://app-gateway.imbrace.co/v2/backend/teams/{team_id}

  • Endpoint for Demo: PUT https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}

  • Endpoint for Dev: PUT https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team to update

  • Request Body (JSON)

  • Request Parameters:

    • name (string, optional): The new name of the team

    • icon_url (string, optional): URL of the team icon

    • is_disabled (boolean, optional): Whether to disable the team

  • Result:

    • Status code: 200 OK (when successful)

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

12. Update User Role in Team

Update a specific user's role within a team.

This API allows you to change a user's role (e.g., from member to admin) within a specific team. It's useful for team management interfaces where administrators need to promote or demote team members.

  • Endpoint for Product: PUT https://app-gateway.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/role

  • Endpoint for Demo: PUT https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/role

  • Endpoint for Dev: PUT https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/role

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team

    • user_id (string, required): The unique identifier of the user

  • Request Body (JSON)

  • Request Parameters:

    • role (string, required): The new role for the user (e.g., "admin", "member")

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

13. Accept Team Join Request

Accept a user's request to join a team.

This API allows team administrators to approve pending join requests from users who have requested to join the team. It's useful for team management workflows where join requests require approval.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/accept

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/accept

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}/user/{user_id}/accept

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body:

    • No request body required

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

14. Delete Team

Delete an existing team from the organization.

This API allows you to permanently delete a team and all its associated data. It's useful for team management interfaces where administrators need to remove teams that are no longer needed.

  • Endpoint for Product: DELETE https://app-gateway.imbrace.co/v2/backend/teams/{team_id}

  • Endpoint for Demo: DELETE https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}

  • Endpoint for Dev: DELETE https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team to delete

  • Request Body:

    • No request body required

  • Result:

    • Status code: 200 OK (when successful)

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

15. Remove Multiple Users from Team

Remove multiple users from a team in a single operation.

This API allows you to remove multiple users from a team simultaneously. It's useful for team management interfaces where administrators need to perform bulk user removal operations.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/_remove_users

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/_remove_users

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/_remove_users

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body (JSON)

  • Request Parameters:

    • team_id (string, required): The unique identifier of the team

    • user_ids (array, required): Array of user IDs to remove from the team

  • Result:

    • Status code: 200 OK (when successful)

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

  • Example:

16. Leave Team

Allow the current user to leave a team.

This API allows authenticated users to voluntarily leave a team they are currently a member of. It's useful for team management interfaces where users need to remove themselves from teams.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/_leave

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/_leave

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/_leave

  • Headers:

    • Content-Type: application/json

    • X-Access-Token: Your Access TokenYour Access Token

  • Request Body (JSON)

  • Request Parameters:

    • team_id (string, required): The unique identifier of the team to leave

  • Result:

    • Status code: 200 OK (when successful)

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

  • Example:

17. Approve Team User with Role

Approve a team user request and assign a specific role.

This API allows team administrators to approve pending team user requests and assign a specific role to the user. It's useful for team management workflows where join requests require approval and role assignment.

  • Endpoint for Product: POST https://app-gateway.imbrace.co/v2/backend/teams/{team_id}/user/{team_user_id}/approve

  • Endpoint for Demo: POST https://app-gateway.demo.imbrace.co/v2/backend/teams/{team_id}/user/{team_user_id}/approve

  • Endpoint for Dev: POST https://app-gateway.dev.imbrace.co/v2/backend/teams/{team_id}/user/{team_user_id}/approve

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team

    • team_user_id (string, required): The unique identifier of the team user relationship

  • Request Body (JSON)

  • Request Parameters:

    • role (string, required): The role to assign to the user (e.g., "admin", "member")

  • Result:

    • Status code: 200 OK

  • Error Responses:

    • Status code: 400 Bad Request

    • Status code: 401 Unauthorized

    • Status code: 403 Forbidden

    • Status code: 404 Not Found

  • Example:

18. Get All Teams for Assignment

Retrieve all teams available for assignment to a specific conversation.

This API allows you to fetch all teams that can be assigned to a conversation, including their assignment status. It's useful for conversation management interfaces where you need to show available teams for assignment.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v1/backend/assign/teams/all?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v1/backend/assign/teams/all?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v1/backend/assign/teams/all?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Query Parameters:

    • conversation_id (string, required): The unique identifier of the conversation

  • Result:

    • Status code: 200 OK

  • Example:

19. Get Team Observers for Conversation

Retrieve all team members who can observe a specific conversation.

This API allows you to fetch all team members who have observer access to a specific conversation. It's useful for conversation management interfaces where you need to show which team members can observe the conversation.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v1/backend/assign/team/{team_id}/observers?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v1/backend/assign/team/{team_id}/observers?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v1/backend/assign/team/{team_id}/observers?conversation_id=conv_d9337f16-b206-4e9a-be6e-accced8e8ecc

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team

  • Query Parameters:

    • conversation_id (string, required): The unique identifier of the conversation

  • Result:

    • Status code: 200 OK

  • Example:

20. Get Team Workflows

Retrieve all workflows associated with a specific team.

This API allows you to fetch all workflows that are associated with a team, including their active status. It's useful for team management interfaces where you need to show which workflows are available for the team.

  • Endpoint for Product: GET https://app-gateway.imbrace.co/v1/backend/teams/{team_id}/workflows

  • Endpoint for Demo: GET https://app-gateway.demo.imbrace.co/v1/backend/teams/{team_id}/workflows

  • Endpoint for Dev: GET https://app-gateway.dev.imbrace.co/v1/backend/teams/{team_id}/workflows

  • Headers:

    • X-Access-Token: Your Access TokenYour Access Token

  • Path Parameters:

    • team_id (string, required): The unique identifier of the team

  • Result:

    • Status code: 200 OK

  • Example:

PreviousSetting APIsNextWorkflow APIs

Last updated