Bulk Archive Users

POST /clients/{client_id}/users/archive

Archive one or more users. Archived users retain their historical data (badged in UI) but no new data is collected or attributed. This operation is idempotent -- archiving an already-archived user is treated as a success.

Archiving is reversible via Bulk Activate Users or Update User.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization

Request Body

Field	Type	Required	Description
user_ids	string (uuid)[]	Yes	List of user IDs to archive

Example Request Body

{
  "user_ids": [
    "a1d97031-04e2-4907-a249-093f7436207b",
    "b2e08142-15f3-5018-b350-104g8547318c"
  ]
}

Response

Returns a BulkUserControlResult with status 200 OK.

All succeeded

{
  "succeeded": [
    "a1d97031-04e2-4907-a249-093f7436207b",
    "b2e08142-15f3-5018-b350-104g8547318c"
  ],
  "failed": []
}

Partial success -- deleted user cannot be archived

{
  "succeeded": [
    "a1d97031-04e2-4907-a249-093f7436207b"
  ],
  "failed": [
    {
      "id": "b2e08142-15f3-5018-b350-104g8547318c",
      "error": "Cannot archive a deleted user"
    }
  ]
}

Business Rules

• Atomic per-user -- one failure does not roll back others.
• Archiving an already-archived user succeeds (idempotent).
• Deleted users cannot be archived (reported in failed).
• If the client is deleted, the entire operation is rejected (400).
• One audit log entry created per affected user.
• Scales to 10,000 users.

Example Request

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "a1d97031-04e2-4907-a249-093f7436207b"
    ]
  }'

Error Responses

Status	Description
400	Invalid request (empty user_ids, client is deleted)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Update User - Update a single user's status
• Bulk Activate Users - Reactivate collection for multiple users
• Bulk Delete Users - Soft-delete multiple users
• Collection Control Audit Log - Audit trail of all collection control changes