API – User import
Use the API token for authorization. Read more in the article API token
- 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" }'
Instead of a local address https://your-domain.com you need to use your instance address.
To transfer values in JSON format, the order of the fields does not matter, the data is imported by field name.
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 |
| manager_id | String | optional. Indicates internal user manager id |
| manager_uid | String | optional. Indicates external user manager id |
When transmitting
manager_id and manager_uid at the same time, priority has manager_id.If the manager field does not pass his 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.
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.
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"}