API – User import
- To import a single user, you need to send a POST request to the following URI /api/v2/users-import/single
- The body of the request must contain a JSON object with information about the user.
- The query must contain the headings Content-Type: application/json;charset=UTF-8 and Authorization: Bearer xxxxxx.
Request example:
curl 'https://your-domain.com/api/v2/users-import/single' -H 'Authorization: Bearer xxxxxx' -H 'Content-Type: application/json;charset=UTF-8' --data-binary '{"uid":"cl123456", "secondname":"Smith", "firstname":"John", "patronymic":"", "login":"john.smith", "email":"[email protected]", "password":"123456", "birth_date":"26.07.1988", "gender":0, "is_active":1, "city":"Kyiv", "department":"Main Office", "position":"CEO", "tags":"tag1", "phone":"+380971111111", "user_field1":"Cluster1", "user_field2":"Top Management", "user_field3":"Ukraine", "user_field4":"string", "user_field5":"string" }'
Format of the object with user information
* Mandatory fields are marked with an asterisk
| Field | Type | Description |
|---|---|---|
| uid* | String | Unique identifier |
| secondname* | String | Second name |
| firstname* | String | First name |
| patronymic | String | Third name |
| login* | String | Login |
| email* | String | |
| password | String | Password |
| birth_date | String | Date of birth, in the format DD.MM.YYYYY or YYYY-MM-DD, for example 26.07.1988 or 1988-07-26 |
| gender | Number | Gender, 0 - male, 1 - female, if the field is not set - it is ignored |
| is_active | Number | Checkbox indicating whether the user is enabled in the system, 1 - enabled, 0 - blocked |
| city | String | City |
| department | String | Department |
| position | String | Position |
| phone | String | Phone number, in international format, for example +380971234567 |
| tags | String | Comma-separated list of tags |
| facebook_id | String | Facebook user id |
| google_id | String | Google user id |
| date_of_employment | String | Date of employment, in the format DD.MM.YYYY or YYYY-MM-DD, for example 26.07.1988 or 1988-07-26 |
| work_contact | String | Working contacts |
| date_of_assignment_current_position | String | Date of current position assignment, in the format DD.MM.YYYY or YYYY-MM-DD, for example 26.07.1988 or 1988-07-26 |
| structure_uid | String | Department code for automatic assignment of the user to a subdivision of the organizational structure |
| user_field1 | String | Additional field in the user profile |
| user_field2 | String | Additional field in the user profile |
| user_field3 | String | Additional field in the user profile |
| customInfo | String | optional. Designed to transfer service information about the user in JSON format using BASE64 encoding. It is not displayed in the user's profile. Example of data that are encoded: {"projects":["mtr-1", "mto-232"], "vacation_days":21, "sick_leave_days":9} |
| language | String | optional. The language of the user interface is specified, if it differs from the main language. Possible values: EN, UK, DE (German), ES (Spanish), ET (Estonian), TR (Turkish), RU (Russian). |
| user_field4 | String | Additional field in the user profile |
| user_field5 | String | Additional field in the user profile |
| role_id | String | optional. You can transfer id of role, that will be assigned to the user after import |
| position_level | String | optional. User Position level |
| manager_id | String | optional. Indicates internal user manager id |
| manager_uid | String | optional. Indicates external user manager id |
The value of the role id for the role_id attribute you can find out from Technical Support. More about roles in the system: Roles in the system.
manager_id and manager_uid at the same time, priority has manager_id.id during the next import, this manager will stop being manager for this subordinate.That is, if you pass the field empty, then previously assigned managers will be deleted from the user.
If previously 2 managers were transmitted, and now only one is indicated, then only 1 will remain for the user after import.
You can pass multiple managers in the manager_id or manager_uid field. More information about manager importing find in article Imported managers.
The structure_uid field can contain multiple departments if the necessary settings are enabled (only for detecting subordinates by import value mode).
Answer
- In case of successful request (HTTP response code - 200), there will be reply in JSON format with information about number of processed records:
{"created_count":1,"updated_count":0,"blocked_count":0,"unblocked_count":0}
created_count - will be 1, if a new user was created in the system
updated_count - will be 1, if the existing user has been updated in the system
blocked_count - will be 1, if the previously active user was blocked during the update process
unblocked_count - will be 1, if the previously blocked user was enabled during the update process
- In case of error (HTTP response code - 400, 500) it returns JSON object with error information:
{"error":"Required fields: uid, login, email, firstname, secondname, position"}