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"
  }
}

Org Settings > 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.

Org Settings > Remove a member

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.

Members > How to remove a member

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.

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.
Get in touch
About Tallyfy