Get users
The "Get Users" endpoint in Connecteam provides a simple yet powerful way to retrieve a list of all users associated with your account. This method allows for optional filtering by user ID, status, name, phone number, email, and various date parameters, making it a flexible tool for managing user data.
Important Note
When passing query parameters in the request, it is very important to use the correct format to avoid error responses.
On this page, you can find helpful information to assist you in retrieving user data from Connecteam to your desired endpoint.
You can specify various query parameters to tailor the results to fit your needs:
- limit (integer): Defines the maximum number of results to display per page. It can range from 1 to 500, with a default value of 10.
- offset (integer): Indicates the resource offset of the last successfully read resource, allowing for pagination. It must be greater than or equal to 0, with a default of 0.
- sort (string): Specifies the sorting criteria for the results. Currently you can sort by the time the user was created in the system
- order (string): Determines the order of the results. The default is ascending (asc). This should only be set if a sort key is also specified.
- userIds (array of integers): A list of user IDs to filter the results. This allows for focused retrieval of specific users.
- userStatus (string): Filters users based on their status. The default status is 'active', but you can adjust it as needed.
- fullNames (array of strings): Enables filtering by user names. The full name must be specified exactly as it appears in the platform, including spaces and case sensitivity.
- phoneNumbers (array of strings): Filters the results by phone numbers in the expected format (e.g., +1234567890).
- emailAddresses (array of strings): Filters users based on provided email addresses using standard email format (e.g., [email protected]).
- createdAt (integer): Filters users created after a specified date in Unix format (in seconds).
- modifiedAt (integer): Filters users whose fields were updated after a specified date in Unix format (in seconds).
Url with query params example to retrieve user (by full name and created after the specified date):
'https://api.connecteam.com/users/v1/users?userIds=&fullNames=Omer%20Vered&createdAt=11111111'
The API returns user details in a structured format, typically including information such as firstName, lastName, phoneNumber, userType, customFields, isArchived, and userId. See the comments next to some of the response objects.
Did you know?
The user response object is updated periodically as we continuously improve our API experience. For the most recent updated payload examples, please refer to our API Reference page.
Payload example for the response when retrieving a user that exists in the system:
{
"requestId": "e40bff49-5e00-4549-a2d2-e339026drtc3",
"data": {
"users": [
{
"firstName": "Omer",
"lastName": "Vered",
"phoneNumber": "+9720548888888",
"userType": "owner",
"email": "[email protected]",
"customFields": [
{
"customFieldId": 6208755,
"value": "Solution Engineer",
"type": "str",
"name": "Title" //job title
},
{
"customFieldId": 6208756,
"value": "30/03/2024",
"type": "date",
"name": "Employment Start Date"
},
{
"customFieldId": 6208760,
"value": 7053346,
"type": "directManager",
"name": "Direct manager"
},
{
"customFieldId": 6663247,
"value": [
{
"id": 2,
"value": "yes"
}
],
"type": "dropdown",
"name": "Onboarded?"
},
{
"customFieldId": 7056222, //'regular' custom field type
"value": "14/01/2024",
"type": "date",
"name": "Special date"
},
{
"customFieldId": 7214214,
"value": 19,
"type": "number",
"name": "Number of days left"
},
{
"customFieldId": 7367254, //dropdown custom field type
"value": [
{
"id": 1,
"value": "yes"
}
],
"type": "dropdown",
"name": "sent file?"
}
],
"isArchived": false,
"userId": 7031021,
"createdAt": 1712573537, // In unix timestamp
"modifiedAt": 1723640035, //In unix timestamp
"lastLogin": 1723640035, //In unix timestamp
"smartGroupsIds": [ //The smart group ids the user is part of
2359154,
2359155,
2392800
]
},
},
"paging": {
"offset": 0
}
}
For larger datasets, you may receive paginated results. Make sure to utilize the limit and offset parameters effectively to navigate through multiple pages of results.
Url with pagination query params example to retrieve user
https://api.connecteam.com/users/v1/users?limit=100&offset=50 //retrieve the first 100 users after the 50th user
This method is particularly useful for retrieving user lists for administrative tasks, generating reports, or managing user roles and permissions. By applying filters, you can quickly access the specific user information you require.
Use Case:
Scenario: Your company uses Connecteam to manage employees and a CRM system (like Salesforce) for customer relations. Whenever a new employee is created in Connecteam, you want to make sure their information is also in the CRM.
Steps:
- Create a New Employee in Connecteam:
- An HR manager adds a new employee (e.g., Alice) in Connecteam.
- Automatic Update: Every 24 hours, your system checks for new employees created in the last 24 hours. It retrieves their details (using the 'createdAt' query params)
- Send Employee Data to CRM: The system then automatically sends Alice’s information (name, email, phone number) to the CRM to create a new contact record.
Use Case:
Scenario: Your CRM holds important information about employees that needs to be updated in Connecteam. For example, if an employee's role changes in the CRM, it should also be updated in Connecteam.
Steps:
- Change Employee Info in CRM:
- A CRM admin updates Alice's role from "Sales Rep" to "Manager."
Send Notification: - The CRM sends a notification to your system that Alice's information has changed.
Get Current Employee Info from Connecteam (by Alice's full name). In the response Alice's user ID in Connecteam will be retrieved - The system sends a request to Connecteam to update Alice’s information.
Updated 3 months ago