Teams

The teams API manages who is on your BrokerBot team: list members, add them in bulk, remove them, and read your groups. All endpoints use a team API key and are served under https://api.brokerbot.ai/v1/teams.

Choosing a team

Every endpoint comes in two forms:

{teamId} can be the team’s ID or its slug (the name in its BrokerBot URL, for example lincoln-park in app.brokerbot.ai/lincoln-park). A team outside your key’s tree returns 404:

{ "error": "Team not found or not accessible with this API key" }

Member object

A member who has signed in at least once is claimed. A member who was added but has never signed in is unclaimed.

Pagination

List endpoints that page take page (from 1, default 1) and pageSize (1–100, default 10), and return:

{
  "pagination": {
    "totalCount": 42,
    "totalPages": 5,
    "currentPage": 1,
    "pageSize": 10
  }
}

List members

GET /v1/teams/members GET /v1/teams/{teamId}/members

Lists the members of the team itself. Members of its sub-teams aren’t included unless they’re also on this team.

curl "https://api.brokerbot.ai/v1/teams/members?search=jane&filter=claimed&sortBy=name&sortOrder=asc" \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

Query parameters:

Response (200):

{
  "members": [
    {
      "id": "usr_123",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+13125550100",
      "image": null,
      "role": "member",
      "lastSeenAt": "2026-09-28T15:04:05.000Z"
    }
  ],
  "pagination": { "totalCount": 1, "totalPages": 1, "currentPage": 1, "pageSize": 10 }
}

Errors: 400 for an invalid page, pageSize, filter, sortBy, or sortOrder.

Add members

POST /v1/teams/members POST /v1/teams/{teamId}/members

Adds one or more people to the team.

curl -X POST https://api.brokerbot.ai/v1/teams/lincoln-park/members \
  -H "Authorization: Bearer $BROKERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "email": "[email protected]", "role": "member" },
      { "phone": "(312) 555-0100", "role": "team_leader" }
    ],
    "sendInvite": true
  }'

Request body:

How it behaves:

• All or nothing. Every entry is validated first. If any entry is missing both email and phone, or has an invalid role, nothing is added and you get 400.
• New people are created. If no BrokerBot user matches the email or phone, one is created.
• Existing members are left alone. Someone who is already on this team is returned as they are; their role is not changed.
• Invites. With sendInvite: true, people who were newly added and have an email get one. People who have never signed in get an invitation to set up their account. People who already use BrokerBot get a notice that they were added. Nobody already on the team is emailed.

Response (200):

{
  "success": true,
  "members": [
    {
      "id": "usr_123",
      "teamId": "team_456",
      "role": "member",
      "createdAt": "2026-09-30T17:00:00.000Z",
      "updatedAt": "2026-09-30T17:00:00.000Z"
    }
  ]
}

Errors: 400 if members is missing or empty, or an entry is invalid.

Remove a member

DELETE /v1/teams/members DELETE /v1/teams/{teamId}/members

Removes a person from the team and all of its sub-teams. Their BrokerBot account isn’t deleted.

Pass email or phone as a query parameter:

curl -X DELETE "https://api.brokerbot.ai/v1/teams/[email protected]" \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

or in a JSON body:

curl -X DELETE https://api.brokerbot.ai/v1/teams/members \
  -H "Authorization: Bearer $BROKERBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+13125550100"}'

Query parameters take priority over the body.

Response (200):

{ "success": true }

List groups

GET /v1/teams/groups GET /v1/teams/{teamId}/groups

Lists the team’s groups: its direct sub-teams, sorted by name. Sub-teams of those groups aren’t included; call this again with the group’s ID to list them.

curl "https://api.brokerbot.ai/v1/teams/groups?pageSize=50" \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

Query parameters: page and pageSize. See Pagination.

Response (200):

{
  "groups": [
    { "id": "team_789", "name": "Lincoln Park", "slug": "lincoln-park", "memberCount": 24 }
  ],
  "pagination": { "totalCount": 1, "totalPages": 1, "currentPage": 1, "pageSize": 50 }
}

List group members

GET /v1/teams/groups/{groupId}/members GET /v1/teams/{teamId}/groups/{groupId}/members

Lists everyone in a group. The group must be a direct sub-team of the team in the path (or of your top-level team, for the first form); otherwise you get 404:

{ "error": "Group not found or not a sub-group of this team" }

{groupId} must be the group’s ID, not its slug.

This list isn’t paginated, and members don’t include image.

curl https://api.brokerbot.ai/v1/teams/groups/team_789/members \
  -H "Authorization: Bearer $BROKERBOT_API_KEY"

Response (200):

{
  "members": [
    {
      "id": "usr_123",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+13125550100",
      "role": "member",
      "lastSeenAt": "2026-09-28T15:04:05.000Z"
    }
  ]
}