This article explains how to create and update up to 1,000 users per request using the SMARTFENSE API, and how to check the result of each operation.
What it is for
Users can be loaded from the administrative interface or through the different import and synchronization sources. The bulk create and update API adds a path designed for cases where an external system decides who must exist in the platform: a human resources system, an onboarding process, or a custom integration built by the organization or the partner.
The operation works in two steps:
-
Send the users with
POST /api/v1/users/bulk-upsert. The platform validates the request and queues it. -
Check the result with
GET /api/v1/users/bulk-upsert/{request_id}, using the identifier returned in the previous step.
Before you start
You need an application registered in Settings > Integrations > Registered applications. The full registration procedure is described in API integration in SMARTFENSE.
Select the following scopes according to what the integration needs:
| Scope | What it is used for |
|---|---|
write_users |
Required. Create and update users, and check the status of the operation. |
read_users |
Query the user list. |
read_groups |
List existing groups. |
write_groups |
Create groups with POST /api/v1/groups. |
The API supports the OAuth 2.0 Authorization code and Client Credentials flows. For server-to-server integrations, Client Credentials is recommended.
All requests are made to the base URL
https://tenant.takesecurity.com/. Replacetenantwith the subdomain of your SMARTFENSE instance.
Step 1 — Send the users
POST /api/v1/users/bulk-upsert Content-Type: application/json Authorization: Bearer <token>
The body contains the users list, with between 1 and 1,000 records:
{
"users": [
{
"username": "ana.perez",
"first_name": "Ana",
"last_name": "Pérez",
"email": "ana.perez@example.com",
"group": "Finance",
"is_active": true,
"language_code": "en-us"
},
{
"username": "juan.gomez",
"group": "Security Committee"
}
]
}In the example, the first record creates a new user and the second adds a group to an existing user.
Create or update
Each user is identified by its username:
- If the username does not exist, the platform creates the user. The record must include all fields.
- If the username exists, only the fields sent are modified. An omitted field keeps its current value.
A record that only includes the
usernameis rejected withNO_UPDATE_FIELDS, because it does not specify anything to modify.
Record fields
| Field | Type | Description |
|---|---|---|
username |
string, up to 150 characters | Always required. User identity. |
first_name |
string, up to 150 characters | First name. Required when creating. |
last_name |
string, up to 150 characters | Last name. Required when creating. |
email |
string, up to 254 characters | Email. Required when creating. |
group |
string, up to 150 characters | Name of an existing group. Required when creating. |
is_active |
boolean | User status. Required when creating. |
language_code |
string | User language. Required when creating. |
username
- Leading and trailing spaces are removed, and the value is converted to lowercase. The lookup is case-insensitive.
- It cannot contain spaces or control characters, start with
=,+,-,@, comma or semicolon, or contain<,>or&. - To create a user, it only accepts letters, numbers and the characters
@ . + - _.
This operation never changes the username of an existing account, except to convert it to lowercase.
first_name and last_name
They do not accept control characters, the prefixes =, +, -, @, comma or semicolon, or the characters <, >, & or the non-breaking space.
- It is stored in lowercase.
- It cannot belong to another user in the platform or be repeated between two users in the same request. In both cases the record fails with
USER_CONFLICT. -
It is not the user identity. The identity is the
username.
group
- The assignment is additive: the indicated group is added and the groups the user already had are kept.
- The group is not created from this endpoint. If it does not exist, the record fails with
GROUP_NOT_FOUND. Create it first withPOST /api/v1/groups.
To remove users from a group, see How to add and remove users from a group via API.
is_active
It must be a JSON boolean (true or false), not text.
language_code
It must be one of these codes, case-insensitive:
ar-sa, id-id, ms-my, bg-bg, ca-ca, cs-cz, da-dk, de-de, et-ee, el-gr, en-au, en-nz, en-gb, en-us, es-ar, es-es, es-eu, es-me, fr-ca, fr-fr, gl-gl, ko-kr, hi-in, hr-hr, it-it, he-il, sw-ke, lv-lv, lt-lt, hu-hu, nl-nl, ja-jp, nb-no, pt-br, pl-pl, pt-pt, ro-ro, ru-ru, sq-al, sk-sk, sl-si, sr-latn, fi-fi, sv-se, th-th, vi-vn, tr-tr, uk-ua, zh-cn, zh-hk, zh-tw.
If the user changed their language from the platform, the language sent is not applied and the record does not report it as a change.
Values not allowed
-
null, empty or whitespace-only values are rejected withEMPTY_FIELD. - A field not listed in the table above is rejected with
UNKNOWN_FIELD. - If the same
usernameappears more than once in the request, all its occurrences fail withDUPLICATE_USERNAME.
Response
If the request can be read, the platform responds with 202 and queues the operation:
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "queued",
"status_url": "https://tenant.takesecurity.com/api/v1/users/bulk-upsert/3f2b9a1e-..."
}Save the request_id. You need it to check the result.
A
202means the request was accepted, not that the users have already been applied. The result of each record is available in step 2.
Errors affecting the entire request
These errors reject the entire request. No user is applied.
| HTTP code | Cause |
|---|---|
400 |
The request cannot be read: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE or EMPTY_FIELD. |
401 |
The token is missing or invalid: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
The token does not have the write_users scope (PERMISSION_DENIED), or the organization is deactivated or expired (TENANT_INACTIVE). |
413 |
More than 1,000 users (TOO_MANY_RECORDS) or more than 4 MB (PAYLOAD_TOO_LARGE). |
415 |
The content type is not application/json. |
429 |
The request limit was exceeded. Wait the number of seconds indicated in the Retry-After header before retrying. |
Step 2 — Check the result
GET /api/v1/users/bulk-upsert/{request_id}
Authorization: Bearer <token>Replace {request_id} with the identifier returned in step 1. This endpoint also requires the write_users scope.
A batch of 1,000 users finishes in a few minutes at most. Check the status every 5 to 10 seconds until the operation finishes.
Response
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "completed",
"received_at": "2026-10-01T12:00:00Z",
"started_at": "2026-10-01T12:00:01Z",
"finished_at": "2026-10-01T12:00:31Z",
"progress": {
"processed": 1000,
"total": 1000
},
"totals": {
"received": 1000,
"created": 740,
"updated": 230,
"unchanged": 29,
"failed": 1
},
"errors": [ ... ]
}-
status: status of the operation.
queuedmeans it is queued andcompletedmeans it has finished. - progress: number of records processed out of the total.
-
totals: summary of the result.
- created: users created.
- updated: existing users with at least one modified field.
- unchanged: records that produced no changes, for example because they had already been applied.
- failed: rejected records.
- errors: details of the records that failed, with their error code.
The result of each operation can be checked for 30 days. After that period, the query responds with
404.
Query errors
| HTTP code | Cause |
|---|---|
401 |
The token is missing or invalid: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
The token does not have the write_users scope (PERMISSION_DENIED), or the organization is deactivated or expired (TENANT_INACTIVE). |
404 |
JOB_NOT_FOUND: the identifier is not valid, there is no operation with that identifier for this application, or its query period has expired. |
429 |
The request limit was exceeded. Wait the number of seconds indicated in Retry-After. |
The operation can only be checked with the same application that sent it.
How to interpret record-level errors
Each user is applied completely or not at all. A record that fails does not leave partial changes or prevent the others from being applied.
| Code | What it means | What to do |
|---|---|---|
MISSING_REQUIRED_FIELD |
A required field to create the user is missing. | Send all fields when creating. |
NO_UPDATE_FIELDS |
The record only includes the username. |
Add at least one field to modify. |
EMPTY_FIELD |
A field is null, empty or whitespace only. |
Fill in the value or omit the field. |
UNKNOWN_FIELD |
A field that is not supported was sent. | Use only the documented fields. |
INVALID_RECORD |
The record does not have a valid format. | Review the record structure. |
INVALID_FIELD_TYPE |
A field has the wrong data type, for example is_active as text. |
Send the type indicated in the fields table. |
INVALID_USERNAME |
The username does not meet the format rules. |
Review the allowed characters. |
INVALID_FIELD_VALUE |
A value does not meet the field rules. | Review the field restrictions. |
INVALID_EMAIL |
The email does not have a valid format. | Correct the address. |
UNSUPPORTED_LANGUAGE |
The language_code is not in the supported list. |
Use one of the listed codes. |
INVALID_GROUP_NAME |
The group name does not have a valid format. | Review the group value. |
GROUP_NOT_FOUND |
The group does not exist. | Create it first with POST /api/v1/groups. |
AMBIGUOUS_GROUP_NAME |
The name does not identify a single group. | Check the groups with that name. |
DUPLICATE_USERNAME |
The username is repeated in the same request. |
Send each user only once. |
USER_CONFLICT |
The email belongs to another user or is repeated in the request, or the user changed during the operation. | Correct the email. If the user changed during the operation, resend the record. |
INTERNAL_ERROR |
Internal error while processing the record. | Resend the record. |
NOT_PROCESSED |
The record was not processed. | Resend the record. |
INTERNAL_ERROR,NOT_PROCESSEDandUSER_CONFLICT(when the user changed during the operation) are resolved by resending the record.
Retries and concurrency
-
Repeating a request is safe. It never creates a duplicate user, nor duplicates or removes groups. Records already applied are reported as
unchanged. - Two simultaneous operations on the same user are applied one after the other. The last one prevails, without mixing fields from both.
Rate limit
The platform may limit the number of requests per minute for each organization, counting all requests to the API, not just those to this endpoint. If the limit is active and exceeded, the response is 429 with the Retry-After header. Wait that number of seconds before retrying.
💡 Best practices
- Create the groups before sending the users. This endpoint does not create groups and the record fails with
GROUP_NOT_FOUND. - Send batches of up to 1,000 users and make sure the body does not exceed 4 MB.
- Save the
request_idof each submission and check the status every 5 to 10 seconds, without exceeding that rate. - Always review
totals.failedand theerrorsblock before considering the load complete. - Resend only the records with
INTERNAL_ERROR,NOT_PROCESSEDorUSER_CONFLICTdue to a concurrent change. Resending the full batch is also safe, but consumes more requests. - Use a stable
usernamethat does not change in the source system. The platform does not modify it on existing accounts. - Send
is_activeas a JSON boolean, not as text. - Respect the
Retry-Afterheader on a429instead of retrying immediately. - Register one application per integration, with the minimum scopes that integration needs.