User management
Upsert users bulk
Upsert users in bulk.
PUT
Upsert users bulk
Create new users or update existing ones.
Merging successive calls with
A payload above the limit of 200 has to be split across several calls, and each
call would otherwise create its own import — all queued behind one another.
Pass
How to use user attributes
If you want to add custom columns to your user table, create them inQobra settings > User attributes first.
Variable api keys
This endpoint is based on dynamic fields. This mean that all annotations that look like<variable-key>, will have to or will be replaced by their
actual API keys.
Asynchronous upsert
This endpoint does not apply your payload during the request: it stores it and creates an import that applies it in the background. The response gives you theimport_id of that import, and the number of items your request contained.
200 therefore means the import was created, not the payload was applied.
To know how it went, fetch the import with the
Fetch import route until its
status is finished, then read its error flag:
error: false— every item of your payload has been upserted.error: true— readtitleindata_tables_details[].errorto know what happened.ValidationErrormeans the payload was refused and nothing was upserted,descriptionlisting the invalid items.PartialFailuremeans part of it was applied:descriptioncounts the items that reported an issue, andparsing_error_detailsnames the skipped ones — the most recent 100 — each with itsline_number,rowanddetails.
scheduled
for a while when another one is already running.
A 400 is still returned during the request itself, for a malformed body or a
payload above the limit — in that case no import is created.
Merging successive calls with debounce
A payload above the limit of 200 has to be split across several calls, and each
call would otherwise create its own import — all queued behind one another.
Pass debounce, a number of seconds, to hold the import open: every call to
the same endpoint made during that window joins the same import instead of
queuing a new one, and they all return the same import_id. The window is
opened by the first call, and a later call joins it without pushing its start
further.
Each payload keeps its own validation. A refused payload upserts nothing, but
the payloads merged beside it are still applied — the import then reports the
reason of every refusal in data_tables_details[].error.
Only calls to the same endpoint are merged: users, manager attributions and
group attributions always get their own import. This is deliberate, since
attributions need the users they reference to exist already — send your users
first, wait for their import to finish, then send the attributions.
Behavior
- Conflict Rule and upsert: Be careful, email field on user is unique. For each user, if it already exist (according to email), we will update the existing one and if it does not exist yet, we will create it.
- Transaction: If there is at least one user that triggers an error at import, none of the users of your call are upserted and the import finishes in error. You have to fix your payload and send it to us again. And if the import finishes without error, it means that every users you sent us have been upserted. This all-or-nothing applies to the payload of your own call: when several calls share an import through
debounce, a refused payload does not prevent the others from being applied - Repeated users: sending the same user twice in one payload does not refuse
the call. The first occurrence is upserted, and each later one is skipped and
reported in
parsing_error_detailswith adetailssuch as"email: duplicated (jane@qobra.co)". Two users are the same when they share the identifier we match on, compared case-insensitively for an email - Empty Field Rule: If you don’t specify a field in upsert, this field won’t be modified. If you want to empty a field, you have to send us a value null associated to the given field api key
- Limit: you can’t upsert more than 200 users at a time.
- Error behavior: a refused payload upserts none of its users, but a user skipped on its own — a repeated user, or one we could not write — leaves all the others upserted. Read the import rather than assuming an all-or-nothing outcome
Authorizations
Query Parameters
Optional (minimum: 0): debounce is the number of seconds we wait before starting the import. Every call to this endpoint made during that window joins the same import instead of queuing a new one, and they all return the same import_id. Use it when a payload above the limit of 200 has to be split across several calls. Only calls to this same endpoint are merged: users, manager attributions and group attributions always get their own import.
Body
application/json
The body contains the list of user data necessary to create a new user in Qobra
Response
Import created
The upsert is performed as a background import: the response identifies the import you just created, not the upserted objects. Fetch the import to know how it went.