--- title: "Read a batch of users by internal ID, or unique property values" method: POST path: "/crm/objects/2026-09/users/batch/read" tags: ["Batch"] --- # Read a batch of users by internal ID, or unique property values `POST /crm/objects/2026-09/users/batch/read` ## Request - Base URL: `https://api.hubapi.com` - URL: `https://api.hubapi.com/crm/objects/2026-09/users/batch/read` - Auth: one of: - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.subscriptions.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.services.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.sensitive.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.orders.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.listings.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tasks.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.appointments.sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.highly_sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.highly_sensitive.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.sensitive.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `media_bridge.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.highly_sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.highly_sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.commercepayments.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.invoices.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.calls.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.users.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.meetings.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.users.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.partner-services.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.orders.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.partner-services.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.appointments.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.highly_sensitive.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.carts.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.highly_sensitive.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.commercepayments.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.products.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.feedback_submissions.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.services.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.subscriptions.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.appointments.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.highly_sensitive.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.invoices.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `tickets.sensitive.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `e-commerce` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.appointments.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.custom.highly_sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.goals.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.sensitive.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.line_items.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.goals.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.line_items.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.partner-clients.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.projects.sensitive.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.quotes.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `tickets.highly_sensitive.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.leads.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.leads.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.carts.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.emails.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.quotes.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.courses.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.partner-clients.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.notes.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.courses.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.listings.read` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.sensitive.read.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.products.read` Retrieve records by record ID or include the `idProperty` parameter to retrieve records by a custom unique value property. ## Query parameters - `archived` boolean ## Request body - BatchReadInputSimplePublicObjectId: Specifies the input for reading a batch of CRM objects, including arrays of object IDs, requested property names (with optional history), and an optional unique identifying property. - `idProperty` string: When using a custom unique value property to retrieve records, the name of the property. Do not include this parameter if retrieving by record ID. - `inputs` SimplePublicObjectId[], required: An array of SimplePublicObjectId objects, each representing an object to be read. - `id` string, required: The unique identifier for the object. It is a string that serves as a reference to the specific object within HubSpot's CRM system. - `properties` string[], required: An array of strings specifying the properties to be returned in the response. If any specified properties are not present on the requested objects, they will be ignored. - `propertiesWithHistory` string[], required: An array of strings specifying the properties to be returned along with their history of previous values. If any specified properties are not present on the requested objects, they will be ignored. ## Response `200` successful operation - BatchResponseSimplePublicObject: A public object batch response object - `completedAt` string, date-time, required: The date and time when the batch operation was completed, in ISO 8601 format. - `links` object: A map of link names to associated URIs, providing additional information or actions related to the batch operation. - `requestedAt` string, date-time: The date and time when the batch operation was requested, in ISO 8601 format. - `results` SimplePublicObject[], required: An array of SimplePublicObject items, representing the results of the batch operation. - `archived` boolean, required: A boolean indicating whether this object is archived. - `archivedAt` string, date-time: The date and time when this object was archived, in ISO 8601 format. - `createdAt` string, date-time, required: The date and time when this object was created, in ISO 8601 format. - `id` string, required: The unique identifier for this object, represented as a string. - `objectWriteTraceId` string: A string representing the trace ID for the object write operation. - `properties` object, required: A map of property names to their values, where each value is a string. - `propertiesWithHistory` object: A map of property names to arrays of historical values, each containing a value and a timestamp. - `updatedAt` string, date-time, required: The date and time when this object was last updated, in ISO 8601 format. - `url` string: A string containing the URL of the object. - `warnings` PublicObjectWarning[]: An array of warnings associated with this object, each represented by a PublicObjectWarning. - `category` string, required: A string indicating the category of the warning. - `context` object, required: An object containing additional context about the warning, with string values for each context key. - `message` string, required: A string containing the warning message. - `startedAt` string, date-time, required: The date and time when the batch operation started, in ISO 8601 format. - `status` 'CANCELED' | 'COMPLETE' | 'PENDING' | 'PROCESSING', required: The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'. ## Other responses - `207`: multiple statuses - `default`: An error occurred. ## Changes - **2026-10-13** (2026-09) `7ffbe15ac78b`: 2 info - the security scope `crm.objects.deals.read` was added to the endpoint's security scheme `oauth2` - the security scope `crm.objects.products.read` was removed from the endpoint's security scheme `oauth2` - **2026-10-10** (2026-09) `127acea72a62`: 2 info - the security scope `crm.objects.deals.read` was added to the endpoint's security scheme `oauth2` - the security scope `crm.objects.products.read` was removed from the endpoint's security scheme `oauth2` - **2026-09-22** (2026-09) `127acea72a62`: 2 info - the security scope `crm.objects.deals.read` was added to the endpoint's security scheme `oauth2` - the security scope `oauth` was removed from the endpoint's security scheme `oauth2` - **2026-09-10** (2026-09) `3d2166bd580c`: 2 info - the security scope `oauth-access` was added to the endpoint's security scheme `oauth2` - the security scope `oauth` was removed from the endpoint's security scheme `oauth2` - **2026-09-09** (2026-09) `ca8e3b980ddb`: 2 info - the security scope `oauth-access` was added to the endpoint's security scheme `oauth2` - the security scope `oauth` was removed from the endpoint's security scheme `oauth2` [Operation history](https://skmtc.dev/hubspot/apis/crm-users/changes/crm/objects/2026-09/users/batch/read/post.md) --- [API](https://skmtc.dev/hubspot/apis/crm-users.md) - [All operations](https://skmtc.dev/hubspot/apis/crm-users/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/crm-users/revisions/7ffbe15ac78b?raw)