User_importers

>>>

GET /(/:locale)/api_integration/user_importers
List user_importers

List user_importers

Examples

{
  "user_importers": [
    {
      "id": 61,
      "company_id": 1,
      "state": "done",
      "user_importer_data_id": 61,
      "created_at": "2018-04-16T17:31:35.019-03:00",
      "import_errors": [],
      "progress": "100.0%"
    },
    {
      "id": 62,
      "company_id": 1,
      "state": "done",
      "user_importer_data_id": 62,
      "created_at": "2018-04-16T17:35:27.993-03:00",
      "import_errors": [],
      "progress": "100.0%"
    }
  ]
}

Params

Param name Description
include
optional

Optional data to be included in the response. Values must be separated by comma.

Validations:

  • Must be one of: progress.
>>>

GET /(/:locale)/api_integration/user_importers/:id
Show a user_importer

Show user_importer

Examples

{
  "user_importer": {
    "id": 61,
    "company_id": 1,
    "state": "done",
    "user_importer_data_id": 61,
    "created_at": "2018-04-16T17:31:35.019-03:00",
    "import_errors": [],
    "progress": "100.0%"
  }
}

Params

Param name Description
include
optional

Optional data to be included in the response. Values must be separated by comma.

Validations:

  • Must be one of: progress.
>>>

POST /(/:locale)/api_integration/user_importers
Create a UserImporter, that will manage the creation or update of the users you pass as data.

Creates or updates multiple users based on the received data.

The provided tags will be added to existing users.

Attention: The importing process will enqueue an async job that might take some minutes to get executed. You may check the import progress by including `include=progress` in the request params.

You can add 1500 user records per user importer.

> A very common error is to get the response after making this POST request and think that the user is created instantly.

The users will only be imported when the user_importer.state = 'done'

You may check errors on user_importer.import_errors and calling user_importer_items endpoint with the param with_errors=true

Finding a user ↑

By default, the importer finds a given user by email. If you want to find a user by CPF or username, you should send the field user_login

Note that, if you send CPF and email without user_login (which defaults to email), the importer will find or create the user with the email, and it will update the CPF. If you send user_login = 'cpf', the importer will find or create the user with the CPF, and it will update the field email and username. If you send user_login = 'username', the importer will find or create the user with the username, and it will update the field email and CPF.

A common mistake it to send cpf: “xxxxxxxxx”, email: “” without sending user_login. You may get the error that the that CPF is already being used for another user. In that case, user user_login: “cpf” and don't send the email field.

Inactivating contracts ↑

The consequences of inactivating a contract are:

  • Users can't interact with it. For instance: sending feedback, answering a review, answering a 1:1, etc.

  • Users can, though, see data from past interactions, such as received feedbacks or reviews.

Triggered system actions: ↑

  1. Contract is removed from shared objectives

  2. Feedback requests sent by contract are inactivated

  3. Contract is removed from all teams

  4. Contract is removed as supervisor of other contracts

  5. Pulse survey participations are inactivated

  • Note that none of those actions will be reversed if you reactivate the contract.

***

Custom Fields ↑

If you need to sync custom attributes, like “t-shirt size”, you may use Custom Contract Fields.

If you need to get them programmatically, follow the steps on this article to get each field key: help.qulture.rocks/pt-BR/articles/4075294-api-da-plataforma-beta

Otherwise, you may access the Platform as a company editor (or ask HR) -> Company profile -> User Importers, and click on “Export Template”. That spreadsheet has all the available fields. For the custom fields, just copy the key in the header.

After that, you may send the key's value as you key.

E.G. for the following ContractField:

“contractField”: {

"name": "T-Shirt size",
"key": "add55b58-3640-4ad8-aba2-b118b6e6472c"

}

you may add to your post payload:

“data”: [

{
  "name": "joao",
  "active": true,
  "email": "joao@example.com.br",
  "add55b58-3640-4ad8-aba2-b118b6e6472c": "SMALL"
}

Best practices ↑

This importer was built to receive many users at a time, so we recommend sending all your users in one importer. By doing so, you only need to control one enpoint and wait it to be finished in order to check for errors.

Supported Formats

json

Errors

Code Description Metadata
401 Unauthorized - Returned when token is invalid 
:error: You are not authorized to perform this action
400 Bad Request - Returned when data format is invalid 
:status: '400'
:error: Bad Request

Examples

Request

{
  "user_importer": {
    "send_invite_mails": true,
    "data": [
      {
        "name": "joao",
        "active": true,
        "email": "joao@example.com.br",
        "tags": ["consultor"],
        "supervisor_email": "davi@example.com.br",
        "supervisor_cpf": "30312345689",
        "area": "North",
        "location": "Westeros",
        "level": "Reborn",
        "rg": "123456789",
        "cpf": "43000086390",
        "country": "Westeros",
        "education": "N/A",
        "department": "Ice",
        "job_title": "King in the North",
        "nickname": "Knows nothing",
        "sex": "male",
        "gender": "cis_man",
        "remove_supervisor": false,
        "termination_reason": null,
        "termination_cause": null,
        "birth_date": "1990-01-30",
        "termination_date": null,
        "admission_date": "2015-11-01",
        "last_career_move_date": "2016-01-30"
      },
      {
        "name": "davi",
        "active": true,
        "email": "davi@example.com.br",
        "tags": ["consultor", "gerente"]
      }
    ]
  }
}

Response

Status: 201 Created

{
  "user_importer": {
      "id": 17,
      "company_id": 1,
      "state": "enqueued",
      "user_importer_data_id": 17,
      "created_at": "2018-03-15T20:30:13.354-03:00"
  }
}

Params

Param name Description
user_importer
required

Importer JSON object

Validations:

  • Must be a Hash
user_importer[send_invite_mails]
optional

Sends invitations to all the active users created on the import.

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data]
required

Array of users to be imported

Validations:

  • Must be an Array of nested elements
user_importer[data][name]
required

User name

Validations:

  • Must be a String
user_importer[data][active]
required

Boolean indicating if the user is active

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][default_contract_for_user]
optional

Boolean indicating if the contract is default_contract_for_user, i.e., if this company should be the default to be opened at login for this user (only needed if user has more than one company)

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][blocked]
optional

Boolean indicating if the contract is blocked, i.e. can not login nor receive emails but still appears in the platform as active

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][email]
optional

User email (unique user identifier).

  • Must be unique;

  • Must match regular expression (?i-mx:\A([^@\s]+)@((?:[-a-z0-9]\.)[a-z]{2,})\z);

  • Must not be in use in other company;

Validations:

  • Must be a String
user_importer[data][supervisor_email]
optional

User supervisor email.

  • The supervisor email cannot be the same as the user email;

  • Must match regular expression (?i-mx:\A([^@\s]+)@((?:[-a-z0-9]\.)[a-z]{2,})\z);

  • The supervisor can't be bellow user in company's hierarchy;

Validations:

  • Must be a String
user_importer[data][tags]
optional

Array of strings representing in what tags the user is included

Validations:

  • Must be an array of String
user_importer[data][tags_admin_only]
optional

Array of strings representing in what tags that are only visible for admins the user is included

Validations:

  • Must be an array of String
user_importer[data][supervisor_cpf]
optional

Supervisor CPF (Use either supervisor_email or CPF to find a contract and assign it as the current user's supervisor).

  • Only digits are accepted;

  • Must be a valid CPF number;

  • The supervisor CPF cannot be the same as the user CPF;

  • The supervisor can't be bellow user in company's hierarchy;

Validations:

  • Must be a number or string.
user_importer[data][area]
optional

Area

Validations:

  • Must be a String
user_importer[data][location]
optional

Location

Validations:

  • Must be a String
user_importer[data][level]
optional

Level

Validations:

  • Must be a String
user_importer[data][rg]
optional

RG

Validations:

  • Must be a String
user_importer[data][cpf]
optional

User CPF may be used as unique identifier, instead of email OR username.

  • Must be unique;

  • Only digits are accepted;

  • Must be a valid CPF number;

Validations:

  • Must be a number or string.
user_importer[data][cpf_password_prefix]
optional

Password prefix for users. When provided, the system will generate a password using this prefix combined with the first 6 digits of the user's CPF.

  • Requires CPF to be present;

  • Generated password format: {prefix}{first_6_cpf_digits}#A1

Validations:

  • Must be a String
user_importer[data][force_update_password]
optional

Force update password. When provided, the system will update the password of the user with cpf_password_prefix even if it already exists.

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][username]
optional

User username may be used as unique identifier, instead of email or CPF.

  • Must be unique;

  • Only digits and letters are accepted;

Validations:

  • Must be a String
user_importer[data][identifier]
optional

Custom User identifier

Validations:

  • Must be a String
user_importer[data][external_uid]
optional

If company setting enable_external_uid is active, you may use this field as the login identifier for SSO, in addition to email

Validations:

  • Must be a String
user_importer[data][country]
optional

Country

Validations:

  • Must be a String
user_importer[data][education]
optional

Education

Validations:

  • Must be a String
user_importer[data][department]
optional

Department

Validations:

  • Must be a String
user_importer[data][job_title]
optional

Job Title

Validations:

  • Must be a String
user_importer[data][nickname]
optional

Nickname

Validations:

  • Must be a String
user_importer[data][sex]
optional

User's sex

Validations:

  • Must be one of: female, male.
user_importer[data][gender]
optional

User's gender

Validations:

  • Must be one of: cis_woman, cis_man, trans_woman, trans_man, travestite, non_binary, agender, rather_not_answer, none_of_the_others.
user_importer[data][user_login]
optional

Email is the default user identifier. You may use cpf or username if you need to import users that don't have email or CPF, or for changing users' emails.

Validations:

  • Must be one of: email, cpf, username.
user_importer[data][preferred_language]
optional

User's default language

Validations:

  • Must be one of: pt, en, es.
user_importer[data][termination_reason]
optional

Termination reason

Validations:

  • Must be one of: voluntary, involuntary.
user_importer[data][termination_cause]
optional

Termination cause.

  • Termination Reason is required;

  • With termination_reason as involuntary:

    • Must be one of: low_performance,project_time,staff_reduction,incompatible_culture_and_values,behavioural_problems,policy_violation,illegal_behavior,insubordination,information_security_problems,damage_to_property,contract_expiration;

  • With termination_reason as voluntary

    • Must be one of: career_opportunity,change_of_career,remuneration,leadership,team_relationship,benefits,culture_and_values,organizational_climate,diversity_and_inclusion,personal_motives,workload;

Validations:

  • Must be one of: career_opportunity, change_of_career, remuneration, leadership, team_relationship, benefits, culture_and_values, organizational_climate, diversity_and_inclusion, personal_motives, workload, low_performance, project_time, staff_reduction, incompatible_culture_and_values, behavioural_problems, policy_violation, illegal_behavior, insubordination, information_security_problems, damage_to_property, contract_expiration.
user_importer[data][birth_date]
optional

Birth date (YYYY-MM-DD)

Validations:

  • Must match regular expression /\d{4}-\d{2}-\d{2}/.
user_importer[data][termination_date]
optional

Termination date (YYYY-MM-DD)

Validations:

  • Must match regular expression /\d{4}-\d{2}-\d{2}/.
user_importer[data][admission_date]
optional

Admission date (YYYY-MM-DD)

Validations:

  • Must match regular expression /\d{4}-\d{2}-\d{2}/.
user_importer[data][last_career_move_date]
optional

Last caree move date (YYYY-MM-DD)

Validations:

  • Must match regular expression /\d{4}-\d{2}-\d{2}/.
user_importer[data][remove_supervisor]
optional

Warning: this is a destructive param. You you are not sure, please avoid using it. By setting this to true, the system will remove the supervisor from the contract.

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][destroy_taggings]
optional

Warning: this is a destructive param. You you are not sure, please avoid using it. By setting this to true, the system will remove all tags from user. That may alter the visibility of questions for ongoing reviews, for instance.

Validations:

  • Must be one of: true, false, 1, 0.
user_importer[data][destroy_taggings_ignore_tags]
optional

Array of strings representing which tags should be ignored by the “destroy_taggings” option. Cannot be used with :destroy_taggins_restrict_tags option.

Validations:

  • Must be an array of String
user_importer[data][destroy_taggings_restrict_tags]
optional

Array of strings representing which tags should be considered by the “destroy_taggings” option. Cannout be used with the :destroy_taggins_ignore_tags option.

Validations:

  • Must be an array of String
user_importer[data][one_on_one_segment_member]
optional

Boolean indicating whether a contract should be added in the 1:1 access segment or if should be removed. If set to true, the contract will be added to the segment. If set to false, the contract will be removed from the segment.

Validations:

  • Must be one of: true, false, 1, 0.
include
optional

Optional data to be included in the response. Values must be separated by comma.

Validations:

  • Must be one of: progress.