> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: e4c58b66-38ea-46bc-b3b0-5105cd727e46 --- # Account | Users API > A user object stores information such as a user's working hours, timezone, additional phone number, and job title. The user endpoints allow you to manage this data and sync it between HubSpot and other systems.  export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; Use the Users API to read or update information about users in a HubSpot account. For example, view their calendar details or update properties such as working hours, timezone, additional phone numbers, and job title. This API can be useful to sync HubSpot user data with external workforce management tools. For example, use these endpoints keep a user's working hours in sync with an external scheduling system. Learn more about [managing users in HubSpot](https://knowledge.hubspot.com/user-management/manage-user-properties-and-preferences). ## Retrieve users * To retrieve all users, make a `GET` request to `/crm/objects/2026-03/users/`. * To retrieve a specific user, make a `GET` to `/crm/objects/2026-03/users/{userId}`. For example: `crm/objects/2026-03/users/207838823235`. * To retrieve a batch of users, make a `POST` request to `/crm/objects/2026-03/users/batch/read`. In the request body, include `id` values of the users to retrieve. You can retrieve by the [user ID or another unique identifier property](#retrieve-users-by-custom-unique-identifier-property). * To retrieve users that meet a specific set of criteria, make a `POST` request to `/crm/objects/2026-03/users/search` and include search filters in the request body. Learn more about [searching the CRM](/docs/api-reference/latest/crm/search-the-crm). **Please note:** in each user API endpoint response, the `id` and `hs_object_id` values are the same and represent a user only in the HubSpot account from which the data was requested. This is different than the `id` values in the [user provisioning API](/docs/api-reference/latest/account/settings/user-provisioning/guide) (`hs_internal_user_id`) which refers to a user across all accounts, and in the [owners API](/docs/api-reference/latest/crm/owners/guide) (`hubspot_owner_id`) which refers to a user as an owner of records. For example, the following response returns users, their unique identifiers within the selected HubSpot account, and information about when they were created or modified: ```json theme={null} { "results": [ { "id": "207838823235", "properties": { "hs_createdate": "2021-01-10T20:36:06.761Z", "hs_lastmodifieddate": "2023-08-29T18:17:55.697Z", "hs_object_id": "207838823235" }, "createdAt": "2021-01-10T20:36:06.761Z", "updatedAt": "2023-08-29T18:17:55.697Z", "archived": false }, { "id": "207840253600", "properties": { "hs_createdate": "2017-12-22T12:22:12.212Z", "hs_lastmodifieddate": "2023-08-29T18:17:55.697Z", "hs_object_id": "207840253600" }, "createdAt": "2017-12-22T12:22:12.212Z", "updatedAt": "2023-08-29T18:17:55.697Z", "archived": false } ] } ``` ### Return specific user properties To return specific properties, include a `properties` query parameter in the request URL along with comma-separated property names. The following are commonly used properties when retrieving users. Learn more about other [user properties](#user-properties) or use the [properties API](/docs/api-reference/latest/crm/properties/get-properties) to retrieve all user properties. | Field | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hs_working_hours` | The user's working hours, [formatted as stringified JSON](#working-hours). | | `hs_availability_status` | The user's availability status. Either `available` or `away`. | | `hs_standard_time_zone` | The user's timezone, shown as a standard [TZ identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (e.g.,`America/New_York` or `Europe/Dublin`). | | `hs_calendar_connection_status` | Whether the user's [calendar is connected to HubSpot](https://knowledge.hubspot.com/meetings-tool/use-meetings). Either `true` (connected), `false` (disconnected), or `null` (never connected). | | `hs_calendar_sync_enabled` | Whether the user has [calendar sync](https://knowledge.hubspot.com/meeting-tool/customize-connected-calendar-and-meeting-scheduling-page-settings) turned on to log meetings from their calendar to records in HubSpot. Either `true` (on), `false` (off), or `null` (never turned on). | | `hs_meetings_enabled` | Whether the user has [scheduling pages](https://knowledge.hubspot.com/meeting-tool/customize-connected-calendar-and-meeting-scheduling-page-settings) turned on to allow contacts to book meetings on their connected calendar. Either `true` (on), `false` (off), or `null` (never turned on). | For example, to retrieve users with their job titles. additional phone numbers, and calendar connection status, a `GET` request to `crm/objects/2026-03/users?properties=hs_job_title,hs_additional_phone,hs_calendar_connection_status`. Your response would look similar to: ```json theme={null} { "results": [ { "id": "207838823235", "properties": { "hs_additional_phone": "+1123456780", "hs_createdate": "2021-01-10T20:36:06.761Z", "hs_job_title": "CEO", "hs_calendar_connection_status": "false", "hs_lastmodifieddate": "2023-08-29T18:17:55.697Z", "hs_object_id": "207838823235" }, "createdAt": "2021-01-10T20:36:06.761Z", "updatedAt": "2023-08-29T18:17:55.697Z", "archived": false }, { "id": "207840253600", "properties": { "hs_additional_phone": "+1238675309", "hs_createdate": "2021-01-10T20:36:06.761Z", "hs_job_title": "Vice President", "hs_calendar_connection_status": "true", "hs_lastmodifieddate": "2023-08-29T18:17:55.697Z", "hs_object_id": "207838823235" }, "createdAt": "2017-12-22T12:22:12.212Z", "updatedAt": "2023-08-29T18:17:55.697Z", "archived": false } ] } ``` ### Retrieve users by custom unique identifier property For the batch read endpoint (`POST` `/crm/objects/2026-03/users/batch/read`), you can retrieve users by their ID or by another [unique identifier property](/docs/api-reference/latest/crm/properties/guide#create-unique-identifier-properties) by including the `idProperty` field. For example, to read a batch of users, your request could look like either of the following: ```json theme={null} { "properties": ["hs_job_title", "hs_additional_phone"], "inputs": [ { "id": "207838823235" }, { "id": "207840253600" } ] } ``` ```json theme={null} { "properties": ["hs_job_title", "hs_additional_phone"], "idProperty": "externalIdProperty", "inputs": [ { "id": "0001111" }, { "id": "0001112" } ] } ``` ## Update users You can update users by ID individually or in batches. * To update an individual user, make a `PATCH` request to `/crm/objects/2026-03/users/{userId}`. * To update a batch of users, make a `POST` request to `/crm/objects/2026-03/users/batch/update`, including the [user IDs or unique `idProperty` in the request body](#retrieve-users-by-custom-unique-identifier-property). For each endpoint, include a request body that contains the properties you want to update. For example, the request body below would update a user's timezone and working hours: ```json theme={null} { "properties": { "hs_standard_time_zone": "America/Detroit", "hs_working_hours": "[{\"days\":\"SATURDAY\",\"startMinute\":540,\"endMinute\":1020},{\"days\":\"WEDNESDAY\",\"startMinute\":540,\"endMinute\":1020}]" } } ``` Only some properties can be set through this API. See the properties section below for a list of the available properties. ## User properties To retrieve a list of all available user properties, you can use the properties API by making a `GET` request to `crm/properties/2026-03/user`. Learn more about using the [properties API](/docs/api-reference/latest/crm/properties/guide). Below are the user properties that can be set through this API. | Parameter | Type | Description | | ---------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `hs_additional_phone` | String | The user's additional phone number. Users can set this in their [user preferences](https://knowledge.hubspot.com/user-management/manage-user-properties-and-preferences#set-user-preferences). | | `hs_availability_status` | String | The user's availability status. The value must be either `available` or `away`. | | `hs_job_title` | String | The user's job title. Users can set this in their [user preferences](https://knowledge.hubspot.com/user-management/manage-user-properties-and-preferences#set-user-preferences). | | `hs_main_user_language_skill` | String | The user's main language skill. The value must match an existing language skill. Learn more about formatting language skills below. | | `hs_out_of_office_hours` | String | The user's out of office hours. Out of office hours must not overlap. Each out of office hours' start time must be later than the previous start time. | | `hs_secondary_user_language_skill` | String | The user's secondary language skill. The value must match an existing language skill. Learn more about formatting language skills below. | | `hs_standard_time_zone` | String | The user's timezone. Timezone values must use standard [TZ identifiers](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), such as `America/New_York` or `Europe/Dublin`. This property must be set before you can set the user's working hours. | | `hs_uncategorized_skills` | String | The user's custom uncategorized skill. This property value must match an existing custom uncategorized skill in the account. | | `hs_working_hours` | String | The user's working hours. This property value is formatted as stringified JSON. Learn more about formatting for working hours below. | ### Working hours `hs_working_hours` accepts a stringified JSON value. It consists of an array with an object for each set of working hours. ```json theme={null} "[{\"days\":\"VALUE\",\"startMinute\":number,\"endMinute\":number}]" ``` | Parameter | Type | Description | | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `days` | Stringified JSON | The days included in a set of working hours. Values include: | | `startMinute` | Number | Working hours start time in minutes. Must be within the range of `0` - `1440`, where `0` represents 12:00AM midnight. For example, a 9:00AM start time would be represented as `540`. | | `endMinute` | Number | Working hours end time in minutes. Follows the same rules as `startMinute`.For example, 5:00PM is represented as `1020`. | **Please note:** * The `hs_standard_time_zone` property must be set before you can set working hours. * Working hours cannot overlap. For example, if a user works Monday through Friday, 9:00AM to 5:00PM, you would format that as follows: ```json theme={null} "[{\"days\":\"MONDAY_TO_FRIDAY\",\"startMinute\":540,\"endMinute\":1020}]" ``` If a user works Monday 9:00AM to 5:00PM and Saturday 11:00AM to 2:00PM, the array would contain an object to represent each set of working hours: ```json theme={null} "[{\"days\":\"MONDAY\",\"startMinute\":540,\"endMinute\":1020},{\"days\":\"SATURDAY\",\"startMinute\":660,\"endMinute\":840}]" ``` ### Out of office hours If a user will be unavailable due to scheduled time off, you can set any periods during which they'll be out of office using the `hs_out_of_office_hours` property: * The property accepts an array of date ranges, each specified by a `startTimestamp` and `endTimestamp`. * The date ranges cannot overlap with one another, and the `startTimestamp` of each date range must be later than the previous `startTimestamp`. For example, if you wanted to specify out-of-office hours during October 31st 2024 9:00 AM to 5:00 PM and November 28 2024 9:00 AM to 5:00 PM, you'd specify the following value for the `hs_out_of_office_hours` property for a user: ```json theme={null} "[{\"startTimestamp\": 17303796000,\"endTimestamp\": 17304084000},{\"startTimestamp\": 17328024000,\"endTimestamp\": 17328312000}]" ``` ### Language skills `hs_main_user_language_skill` or `hs_secondary_user_language_skill` must match an existing language skill. The following JSON array lists all valid options for language skill categories: ```json theme={null} [ { "label": "Dansk", "value": "da" }, { "label": "Deutsch", "value": "de" }, { "label": "English", "value": "en" }, { "label": "Español", "value": "es" }, { "label": "Français", "value": "fr" }, { "label": "Italiano", "value": "it" }, { "label": "Nederlands", "value": "nl" }, { "label": "Norsk", "value": "no" }, { "label": "Polski", "value": "pl" }, { "label": "Português", "value": "ptbr" }, { "label": "Suomi", "value": "fi" }, { "label": "Svenska", "value": "sv" }, { "label": "中文 - 繁體", "value": "zhtw" }, { "label": "日本語", "value": "ja" } ] ```