This article explains how to retrieve the list of groups in your organization, how to create a group via API, and how to interpret the platform's responses.
What it is for
The Grupos (Groups) section of the SMARTFENSE API includes these operations:
| Operation | Endpoint | Use |
|---|---|---|
| List groups | GET /api/v1/groups | Retrieve all groups in the organization with their identifier. |
| Create or get a group | POST /api/v1/groups | Create a group or, if an equivalent one already exists, retrieve it. |
| Add or remove users from a group | POST /api/v1/groups/{group_id}/users | Add users to or remove users from a group. |
Both operations covered in this article return the group identifier (id), which is the value you need to work with that group.
To add or remove users, see Cómo agregar y quitar usuarios de un grupo por API.
Before you begin
You need an application registered in Configuración > Integraciones > Aplicaciones registradas, with the scopes each operation requires:
- Leer grupos (
read_groups): to list groups. - Escribir grupos (
write_groups): to create or get a group.
The full registration procedure is described in Integración de APIs en SMARTFENSE.
The API supports the OAuth 2.0 authorization_code and client_credentials flows. Every request must include the token in the Authorization header.
List groups
GET /api/v1/groups
Returns all groups in the organization, including groups with no users and inactive groups.
The list does not include áreas funcionales (functional areas), niveles jerárquicos (hierarchical levels) or grupos inteligentes (smart groups).
Query parameters
- page (integer): page number to retrieve. Default value: 1.
- page_size (integer): number of records per page. Default value: 100. Maximum value: 1,000.
Response
{
"count": 123,
"next": "https://tenantname.takesecurity.com/api/v1/groups?page=2",
"previous": null,
"results": [
{
"id": 0,
"name": "string",
"is_active": true
}
]
}- count: total number of groups.
- next / previous: links to the next and previous pages.
- results: the groups on the page, with their id, name and is_active flag.
How to go through all pages
Results are sorted by id. To retrieve the full list:
- Request the first page.
- Add the groups in results to your list.
- If next has a value, request that URL and repeat step 2.
- When next is null, you have reached the end.
If you request a page that does not exist, the platform responds with 404 (
NOT_FOUND). This means you have already reached the end.
Create or get a group
POST /api/v1/groups
Creates a group or, if an equivalent one already exists, returns it without creating another.
Request body
The request must be sent with the application/json content type:
{
"name": "campaign-2026-09"
}- name (string, required): group name, from 1 to 150 characters.
The name accepts Unicode characters, with these restrictions:
- It cannot start with
=,+,-,@, a comma or a semicolon. - It cannot contain characters the platform modifies when saving, such as
<,>,&or the non-breaking space. - It cannot contain control characters.
When two names are equivalent
Two names are equivalent if they match after removing leading and trailing spaces, regardless of upper or lower case.
For example, campaign-2026-09 and Campaign-2026-09 refer to the same group.
Response
{
"id": 4832,
"name": "campaign-2026-09",
"is_active": true,
"outcome": "existing"
}The outcome field indicates what the platform did:
- created: the group was created. The response is 201.
- existing: an equivalent group already existed and that group is returned. The response is 200.
Repeating the same request is safe. The first one responds 201 with outcome: created, and the following ones respond 200 with outcome: existing and the same id. Two simultaneous requests with equivalent names also resolve to the same group.
The response returns the name as it is stored. Its capitalization may differ from the name you sent.
Group behavior
- The created group is active.
- The group is kept even if users are later imported from a file.
- An existing group is returned as is: if it is inactive, it is not reactivated, and it keeps its type.
Specific errors
| Code | Meaning |
|---|---|
| 400 | The request is not valid. Possible codes: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE and INVALID_GROUP_NAME. |
| 409 | More than one equivalent group exists (AMBIGUOUS_GROUP_NAME). The response includes their identifiers in group_ids and nothing is created. |
| 415 | The content type is not application/json (UNSUPPORTED_MEDIA_TYPE). |
| 503 | Another request for an equivalent name is still in progress (TRY_AGAIN). Try again after the number of seconds indicated in the Retry-After header. |
If you receive 409, review the groups listed in
group_idsto decide which one to work with. As long as several equivalent groups exist, the request will keep responding 409.
Errors common to both operations
| Code | Meaning |
|---|---|
| 401 | The token is missing or not valid (AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED). |
| 403 | The token does not have the required scope (PERMISSION_DENIED), or the organization is deactivated or expired (TENANT_INACTIVE). |
| 429 | The allowed request limit was exceeded. |
Rate limit
The platform may limit the number of requests per minute for each organization. The limit counts all requests to the API, not only those related to groups.
If the limit is active and exceeded, the response is 429 with the Retry-After header. Wait the number of seconds indicated in that header before retrying.
💡 Best practices
- Use Create or get a group instead of listing and then creating: the operation already prevents duplicates and can be repeated safely.
- Store the id returned in the response and use it in subsequent operations, instead of the name.
- Check the is_active field when outcome is existing: an inactive group is not reactivated via API.
- Always go through the full list by following the next link, instead of calculating the number of pages.
- Use a high page_size (up to 1,000) to reduce the number of requests in organizations with many groups.
- Respect the Retry-After header after a 429 or 503 response, instead of retrying immediately.
- Register one application per integration, with the minimum scopes that integration needs.