Create new users

Creating new users in Connecteam is intuitive and straightforward. However, there are some important guidelines to follow:

• Unique Phone Number: In Connecteam, phone numbers serve as the unique identifier for users, which is understandable given the platform's focus on deskless employees. Unlike emails, which are not mandatory for users with user permissions, the phone number is required.
  Once an employee is created, both the phone number and the userId are unique within the system.
• Permissions: There are three user permission types in Connecteam - Owner, Admin, and User. While an email address is not mandatory for users with 'User' permissions, it is required for users with 'Admin' and 'Owner' permissions when creating a new user.
• userType:In Connecteam, there are three main user types in the system: Owner, Admin (Manager), and User. Currently our API supports 'user' and 'admin' types only. When creating a new user, it will be created with 'user' type. In order to promote the user to an admin, use the users/v1/admin endpoint.
• isArchived: While archiving a user upon creation is uncommon, there are certain use cases where creating a user in an archived status might be beneficial. There is no need to specify this field if you wish to create the user in an active status, as it defaults to false.
• Custom Fields: Custom fields in Connecteam allow you to tailor user profiles to meet the specific needs of your organization. These fields can be used to gather additional information that is relevant to your operations or workforce management. There are 2 types of custom fields: Dropdown and Custom. We will discuss about specifying custom fields values to new users.
• Custom Fields Types: Assigning custom fields values when creating (or updating) new users in the system via API, it's important to follow the correct format according to the custom field type. The following table represents what our API expects to receive for each custom field (except dropdown):

📘

Good to know

If you wish to create only a single user, you still need to wrap the object in an array.

• Dropdown Custom Fields Type: Assigning a dropdown custom field type to a user is a bit more complex but still easy to implement. Each custom field structure is as follows:
  • Custom Field Id: The unique identifier of the custom field.
  • Value: Unlike regular custom fields, here you should specify the id of the chosen value.
    For example, if there are three options in the dropdown - 'test2', 'test44', 'test3' - then id: 1 will represent the first option in the dropdown, which in this case is 'test2'.
  • In case of multiple selected options, separate each id with a column
    Below you can find a JSON example of how to pass the dropdown type correctly.

🚧

Important Note

For the most up-to-date payload and response structures, please refer to the API Reference page. It is recommended to visit this page before testing any API calls.

Payload example for creating user with required fields:

[
  {
    "userType": "user",
    "firstName": "Omer",
    "lastName": "Vered",
    "phoneNumber": "+12124567890",
    "userType": "user"
  }
]

Response example for creating user with required fields:

{
  "requestId": "xxxxxxxx-a8e2-4457-9909-xxxxxxxxxxxxx",
  "data": {
    "results": [
      {
        "firstName": "Omer",
        "lastName": "Vered",
        "phoneNumber": "+1(212) 4567890",
        "userType": "user",
        "customFields": [],
        "isArchived": false,
        "userId": 8015532
      }
    ]
  }
}

Creating user with specified custom fields

As previously mentioned, there are two types of custom fields: Dropdown and Custom. The following is an example of creating a user that incorporates both types of custom fields.

Payload Example for Creating a User with Custom Fields:

• Lines 6-11 demonstrate an example of a custom field of Dropdown type. The id represents the selected value from the dropdown options (indexed by its order in the platform). In line 11 there is an added value (in case of multiple selected options).
• Lines 14-17 demonstrate an example of a custom field of Custom type.

[
    {
        "userType": "user",
        "customFields": [
            {
                "customFieldId": 6208757, //dropdown custom field id
                "value": [
                    {
                        "id": 2, //the id of the value of the dropdown options
                      	"id": 3 // In case of multiple select options, specify the id of the other options
                    }
                ]
            },
            {
                "customFieldId": 6208755, 
                "value": "Cleaner" //regular custom field str type 
        ],
        "firstName": "Omer",
        "lastName": "Vered",
        "phoneNumber": "+12125667789"
    }
]

• Sending Activation: An activation SMS containing an invitation link to download the app can be sent to the user's mobile device upon creating a new user. To enable this, simply add the field sendActivation set to true to the query parameters. If no parameter is specified, this flag defaults to 'false', meaning no activation SMS will be sent to the user.
  Example of url with activation flag set to true:

url: 'https://api.connecteam.com/users/v1/users?sendActivation=true'

Create users API reference