Skip to content

Remove member

Endpoint

DELETE /organizations/{org_id}/users/{user_id}

This endpoint removes a member from your Tallyfy organization. The user is removed from this specific organization but their global account may remain. Their assigned tasks might become unassigned or require reassignment.

Two-step deletion process

Important: Tallyfy uses a two-step deletion process for safety. Members must be disabled first before permanent deletion:

  1. Step 1 - Disable: DELETE /organizations/{org_id}/users/{user_id}/disable
  2. Step 2 - Delete: DELETE /organizations/{org_id}/users/{user_id}/delete

If you attempt to delete an active member directly, you’ll receive an error: "Please disable the user before deletion"

Request

Replace {org_id} with your Organization ID and {user_id} with the numeric ID of the member to remove.

Headers

  • Authorization: Bearer {your_access_token}
  • Accept: application/json
  • X-Tallyfy-Client: APIClient

Query parameters (optional)

The API provides optional parameters for handling reassignment of the removed member’s tasks:

  • with_reassignment (boolean): Set to true if you want to reassign tasks.
  • to (integer): If with_reassignment=true, provide the User ID of the member to whom tasks should be reassigned.

Example: ?with_reassignment=true&to=1002

Body

No request body is needed for this DELETE request.

Code samples

const accessToken = 'YOUR_PERSONAL_ACCESS_TOKEN';
const orgId = 'YOUR_ORGANIZATION_ID';
const userId = 12345; // ID of the member to remove
const reassignToUserId = null; // Optional: Set to ID (number) of member to reassign tasks to


// Construct query string if reassigning
const params = new URLSearchParams();
if (reassignToUserId != null) {
  params.append('with_reassignment', 'true');
  params.append('to', reassignToUserId.toString());
}
const queryStr = params.toString();
const apiUrl = `https://go.tallyfy.com/api/organizations/${orgId}/users/${userId}${queryStr ? '?' + queryStr : ''}`;


const headers = new Headers();
headers.append('Authorization', `Bearer ${accessToken}`);
headers.append('Accept', 'application/json');
headers.append('X-Tallyfy-Client', 'APIClient');


fetch(apiUrl, {
    method: 'DELETE',
    headers: headers
})
.then(response => {
    if (!response.ok) { // Expect 200 OK on success usually
        // Try to parse error JSON, fallback to text
        return response.json()
            .catch(() => response.text())
            .then(errData => {
                console.error(`Failed to remove member ${userId}. Status: ${response.status}`, errData);
                throw new Error(`HTTP error! status: ${response.status}`);
            });
    }
    console.log(`Successfully removed member ${userId}. Status: ${response.status}`);
    // API might return the details of the removed user
    // Use response.text() first as body might be empty or non-json on 200 OK
    return response.text().then(text => {
        try {
            return text ? JSON.parse(text) : null;
        } catch (e) {
            console.warn("Could not parse response body as JSON:", text);
            return null;
        }
    });
})
.then(data => {
    if (data) {
      console.log('Removed member details (if returned):');
      console.log(JSON.stringify(data, null, 2));
    }
})
.catch(error => {
    console.error(`Error during removal of member ${userId}:`, error.message);
});

Response

A successful request returns a 200 OK status code and a JSON object containing the removed member’s data.

Common error responses

400 Bad Request

{
  "error": "Please disable the user before deletion"
}

Solution: Use the disable endpoint first, then attempt deletion.

403 Forbidden

{
  "error": "Cannot modify the default administrator"
}

Solution: Transfer the default administrator role to another user first.

{
  "error": "Cannot disable the last administrator"
}

Solution: Promote another member to administrator role before removal.

404 Not Found

{
  "error": "User not found"
}

Solution: Verify the user ID is correct and the member exists in this organization.

Success response example

{
  "data": {
    "id": 12345,
    "email": "john.doe@example.com.deleted.12345",
    "first_name": "John",
    "last_name": "Doe (Deleted)",
    "role": "standard",
    "status": "deleted",
    "deleted_at": "2025-01-15T10:30:00Z"
  }
}


## Related articles
<CardGrid>
<LinkTitleCard header="<b>Org Settings > Member deletion</b>" href="/products/pro/settings/org-settings/troubleshooting-member-deletion/" > This comprehensive guide addresses common issues and solutions when removing organization members from Tallyfy including error message troubleshooting and system behavior details for administrators managing member deactivation and deletion processes. </LinkTitleCard>
<LinkTitleCard header="<b>Org Settings > Remove a member</b>" href="/products/pro/settings/org-settings/how-can-i-remove-a-member-from-my-tallyfy-organization/" > Administrators can remove members from their Tallyfy organization through the Settings panel by deactivating the member and reassigning their existing tasks to other active members to prevent work loss. </LinkTitleCard>
<LinkTitleCard header="<b>Members > How to remove a member</b>" href="/products/pro/documenting/members/how-can-i-remove-a-member-from-my-tallyfy-organization/" > Administrators can permanently deactivate organization members by navigating to Settings > Organization > Members and clicking Deactivate Account while choosing to either reassign their current tasks to other members or leave them unassigned for later redistribution. </LinkTitleCard>
<LinkTitleCard header="<b>Groups > Delete group</b>" href="/products/pro/integrations/open-api/code-samples/groups/delete-group/" > A DELETE endpoint removes organizational groups while maintaining individual member and guest accounts by requiring authentication headers and returning status codes 200 or 204 upon successful deletion. </LinkTitleCard>
</CardGrid>
Get in touch
About Tallyfy