Remove a teammate without stranding their work

When someone leaves the team, their open conversations and leads do not close by themselves. This recipe covers two questions. What still belongs to that person. And who it goes to once they are gone.

Trap

Suspending someone stops new assignments; it does not move what they already had

PUT /memberships/{id} with account_status: "suspended" takes the person out of rotation from that moment on: nobody suspended gets a new conversation or lead. But their ALREADY-assigned threads and leads do not move by themselves, and they keep counting as open until someone reassigns them by hand. To reassign everything they own, use DELETE /memberships/{id}, as this recipe shows.

Before you start

memberships:read to see what belongs to someone before taking them off.
memberships:write to delete the membership and decide the handover.
Roles, statuses and the rest of a member's lifecycle live in Team; this recipe covers only the exit.

1. Look at what belongs to them before taking them off

curl https://api.vitrinadev.com/api/v1/memberships/b7b65979-fc3b-49f5-8973-63ca8f7759dc/handover-preview \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "userId": "87185d14-5120-4c77-8d75-07af52412494",
    "openConversations": 1,
    "openLeads": 1,
    "candidates": [
      { "userId": "3197957f-5fb6-4c7a-837d-1fe296bc548d", "openConversations": 1 }
    ]
  }
}

openConversations and openLeads are what actually needs moving. It is not a historical count: a resolved conversation, or a lead that was won or lost, keeps its original owner even after that person is gone. candidates is the active people who already show up in some routing roster: a channel, a rule, a team. It carries everyone's current load, to decide whether round robin splits the load evenly.

2. Choose how to split the work and take the person off

curl -X DELETE "https://api.vitrinadev.com/api/v1/memberships/b7b65979-fc3b-49f5-8973-63ca8f7759dc?handover=round_robin" \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "mode": "round_robin",
    "conversationsMoved": 1,
    "leadsMoved": 1,
    "perAssignee": { "3197957f-5fb6-4c7a-837d-1fe296bc548d": 2 }
  }
}

handover takes three modes. unassign, the one that runs if you send nothing, drops everything into «Unassigned»: visible, but nobody gets told. user moves everything to one person with handover_assignee_id. round_robin, this example's mode, splits across the candidates from step 1.

The membership is deleted only after the work is handed over. If the handover fails, the person stays on the team and nothing is left without an owner.

perAssignee counts what each person received, conversations and leads added together. Here both landed on the same candidate, so her count reaches two.

3. Confirm nothing got stranded

curl https://api.vitrinadev.com/api/v1/conversations/01a0ce18-5dd9-7182-baa6-f08b5bdd5dfc \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "data": { "id": "01a0ce18-5dd9-7182-baa6-f08b5bdd5dfc", "assignee_user_id": "3197957f-5fb6-4c7a-837d-1fe296bc548d" } }

The conversation's assignee_user_id and the lead's owner_user_id should point at the candidate from the receipt, never at the id you just deleted. The deleted membership no longer resolves. GET /memberships/{id}/handover-preview on a deleted id answers 404. That is the simplest confirmation the person is genuinely out of rotation.

The removal also takes the person off channels, rules and teams, so they do not receive new conversations or leads.

In the app: taking someone off the team, with the same handover dialog, happens from Team → member → Remove.

Vitrina's handover dialog: how many open conversations and opportunities the person holds, and the three ways to reassign them

When it fails

Asking for handover=user with no handover_assignee_id answers 400 before touching a single conversation:

curl -X DELETE "https://api.vitrinadev.com/api/v1/memberships/17016480-260a-4781-a7e1-8e4e19897ebd?handover=user" \
  -H "Authorization: Bearer $VITRINA_KEY"

{ "error": { "code": "VALIDATION_ERROR", "message": "handover mode \"user\" needs an assignee" } }

The membership is still there: the handover gets validated in full before moving anything, never halfway. Asking to hand the work back to the very person leaving fails the same way, with the same code. Deleting the workspace's last active owner answers 403, rather than leaving the workspace with nobody to administer it.