> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert users bulk
> Upsert users in bulk.
Create new users or update existing ones.
## How to use user attributes
If you want to add custom columns to your user table, create them in `Qobra
settings > User attributes` first.
Those attributes will have an auto-generated API key that you can overwrite. This key will allow you to provide value for those attribute at user creation through API.
## Variable api keys
This endpoint is based on dynamic fields. This mean that all annotations
that look like ``, will have to or will be replaced by their
actual API keys.
## 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, we return you an error and import nothing. You have to fix your payload and send it to us again. And if the answer is a success, it means that every users you sent us have been upserted
* **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**: In case of any error, your users wont be upserted
## OpenAPI
````yaml put /v1/users/bulk
openapi: 3.0.2
info:
version: 1.0.0
title: Qobra API
description: API documentation for Qobra
servers:
- url: https://api.qobra.co
description: API
security: []
paths:
/v1/users/bulk:
put:
tags:
- public_api
- v1
- users
summary: Upsert users bulk
description: Upsert users in bulk.
operationId: PUT_/v1/users/bulk
requestBody:
description: >-
The body contains the list of user data necessary to create a new user
in Qobra
content:
application/json:
schema:
$ref: '#/components/schemas/PutManyInputModel_UserPutBodyModel'
examples:
user-bulk-body:
$ref: >-
#/components/examples/PutManyInputModel_UserPutBodyModelExample
required: true
responses:
'200':
description: Success operation
content:
application/json:
schema:
$ref: '#/components/schemas/UsersBulkPutSuccessModelResponse'
examples:
user-bulk-success:
$ref: >-
#/components/examples/UsersBulkPutSuccessModelResponseExample
'400':
description: ClientError operation
content:
application/json:
schema:
$ref: '#/components/schemas/UsersBulkPutClientErrorModelResponse'
examples:
user-bulk-errors:
$ref: >-
#/components/examples/UsersBulkPutClientErrorModelResponseExample
security:
- api_key: []
components:
schemas:
PutManyInputModel_UserPutBodyModel:
type: object
properties:
data:
title: Data
type: array
items:
$ref: '#/components/schemas/UserPutBodyModel'
required:
- data
title: PutManyInputModel[UserPutBodyModel]
UsersBulkPutSuccessModelResponse:
type: object
properties:
count:
description: Upserted user count
type: integer
data:
description: Array of upserted users
type: array
items:
$ref: '#/components/schemas/UsersBulkSuccessModelResponse'
required:
- count
- data
title: UsersBulkPutSuccessModelResponse
UsersBulkPutClientErrorModelResponse:
type: object
properties:
count:
description: Errors count
type: integer
errors:
description: Array of errors
type: array
items:
$ref: '#/components/schemas/UsersBulkClientErrorModelResponse'
required:
- count
- errors
title: UsersBulkPutClientErrorModelResponse
UserPutBodyModel:
type: object
properties:
email:
title: Email
type: string
description: Email of the user
format: email
name:
title: Name
type: string
description: Name of the user
role:
title: Role
type: string
description: >-
The role of the user you want to create. This will default to
default role in Qobra, if no role is provided
currency:
$ref: '#/components/schemas/CurrencyCode'
calculation_currency:
$ref: '#/components/schemas/CurrencyCode'
:
type: string
description: Value of user attribute 1
:
type: string
description: Value of user attribute 2
required:
- email
- name
title: UserPutBodyModel
UsersBulkSuccessModelResponse:
type: object
properties:
id:
description: Id of the upserted user
type: string
format: email
email:
description: Email of the user
type: string
format: email
name:
description: Name of the user
type: string
role:
description: The role of the user
type: string
currency:
$ref: '#/components/schemas/CurrencyCode'
calculation_currency:
$ref: '#/components/schemas/CurrencyCode'
required:
- id
- email
- name
- role
- currency
- calculation_currency
additionalProperties:
oneOf:
- type: string
- type: integer
title: UsersBulkSuccessModelResponse
UsersBulkClientErrorModelResponse:
type: object
properties:
error:
description: Type of the error
type: string
user:
description: Email of the user upserted in error
type: string
format: email
resource:
description: Related resource in error
type: string
description:
description: Description of the error
type: string
required:
- error
- user
- resource
- description
title: UsersBulkClientErrorModelResponse
CurrencyCode:
description: Allowed currency codes.
type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BOV
- BRL
- BSD
- BTN
- BWP
- BYR
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNY
- COP
- COU
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLL
- SOS
- SRD
- STD
- SVC
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYI
- UYU
- UZS
- VEF
- VND
- VUV
- WST
- XAG
- XAU
- XCD
- XPD
- XPT
- XSU
- YER
- ZAR
- ZMK
- ZWL
title: CurrencyCode
examples:
PutManyInputModel_UserPutBodyModelExample:
value:
data:
- email: user-test-1@company.com
name: User 1
role: Sales Rep
currency: EUR
calculation_currency: USD
country: France
code: AO32ND56
arrival_date: '2023-12-01'
junior: true
- email: user-test-2@company.com
name: User 2
role: Manager
currency: USD
calculation_currency: USD
country: Germany
code: AO32ND57
arrival_date: '2024-01-01'
junior: false
- ...
UsersBulkPutSuccessModelResponseExample:
value:
count:
data:
- id: 5537a5b05d6e4824940e9e1bb9a5ebb8
email: user-test-1@company.com
name: User 1
role: Sales Rep
currency: EUR
calculation_currency: USD
country: France
code: AO32ND56
arrival_date: '2023-12-30'
junior: true
- id: 5537a5b05d6e4824940e9e1bb9a5ebb9
email: user-test-2@company.com
name: User 2
role: Manager
currency: USD
calculation_currency: USD
country: Germany
code: AO32ND57
arrival_date: '2024-01-01'
junior: false
- ...
UsersBulkPutClientErrorModelResponseExample:
value:
count:
errors:
- error: ConflictError
resource:
user: user-test-3@company.com
description: This unique user attribute is used for another user
- error: NotFoundError
user: user-test-3@company.com
resource: user_attribute
description: User attribute not found
- error: ParsingError
user: user-test-4@company.com
resource:
description: >-
We had issues parsing the provided : value
- ...
securitySchemes:
api_key:
type: apiKey
name: X-API-Key
in: header
````