Skip to main content

How to add and remove users from a group via API

  • Updated

This article explains how to add and remove users from a group via API, identifying them by their email address, and how to interpret the platform's response.

What it is for

A group's membership can be modified from the administrative interface or through user import and synchronization. The API adds a third way, meant for cases where group membership is decided by an external system: an onboarding process that adds each new person to the group they belong to, an HR system that reflects a change of department, or a process that builds a one-off group for a campaign.

If you are looking for group management from the platform, see How to manage users and groups in SMARTFENSE.

Before you start

You need an application registered under Configuración > Integraciones > API, with the Write groups scope selected. The full registration procedure is in API Integration in SMARTFENSE.

You also need the group identifier you are going to operate on. You can obtain it with the Read groups scope, which returns the organization's groups with their identifier and name.

Adding or removing users

 
POST /api/v1/groups/{id_del_grupo}/users

The request body indicates the action and the list of emails:

 
json
{
  "action": "add",
  "emails": ["ana.perez@ejemplo.com", "juan.gomez@ejemplo.com"]
}
  • action: add to add the users to the group, remove to remove them. A single request does only one of the two.
  • emails: up to 200 addresses per request. Emails repeated within the same request are processed only once.

Adding a user who already belongs to the group, or removing one who does not, does not produce an error: the platform leaves the group in the state the request asks for.

Response

 
json
{
  "action": "add",
  "group_id": 2,
  "group_name": "Comité de Seguridad",
  "processed": ["ana.perez@ejemplo.com"],
  "skipped": ["no.existe@ejemplo.com"],
  "details": { "total_processed": 1, "total_skipped": 1 }
}
  • processed: the emails the action was applied to.
  • skipped: the emails that do not match any user in the organization. A skipped email does not stop the request: the rest is still processed.

Always review skipped. An email that appears there almost always means the user does not yet exist in SMARTFENSE, or is written differently from how it is stored: the platform matches it case-insensitively, but does not correct spelling differences.

If the group identifier does not match any group in the organization, the request is not processed and the platform responds that it could not find it.

Audit log

Each user added or removed is logged in the administration audit trail as an edit to that user, with groups among the modified fields. You can find this under Audit > Administration.

💡 Best practices

  • Create users before assigning them to a group: the API does not create users, it only modifies the group's membership.
  • Send emails in batches of up to 200 and review the skipped block of each response before considering the operation complete.
  • If the same process both adds and removes users, send two requests: one with add and another with remove.
  • Register one application per integration, with the minimum scopes that integration needs.

Related articles