--- title: "Create or update a batch of users by unique property values" method: POST path: "/crm/objects/2026-09/users/batch/upsert" tags: ["Batch"] --- # Create or update a batch of users by unique property values `POST /crm/objects/2026-09/users/batch/upsert` ## Request - Base URL: `https://api.hubapi.com` - URL: `https://api.hubapi.com/crm/objects/2026-09/users/batch/upsert` - 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` Create or update records identified by a unique property value as specified by the `idProperty` query param. `idProperty` query param refers to a property whose values are unique for the object. ## Request body - BatchInputSimplePublicObjectBatchInputUpsert: Represents a batch input operation for upserting simple public objects in HubSpot. This component is used to process multiple upsert operations in a single request, improving efficiency and performance. - `inputs` SimplePublicObjectBatchInputUpsert[], required: An array of SimplePublicObjectBatchInputUpsert objects, each containing the properties and identifiers necessary for creating or updating a CRM object. This array is required. - `id` string, required: A string representing the unique identifier of the CRM object. This is required for identifying the object to be created or updated. - `idProperty` string: The name of a property whose values are unique for this object - `objectWriteTraceId` string: A string used for tracing the write operation of the object. This is optional and can be used for tracking purposes. - `properties` object, required: An object containing key-value pairs where each key is a property name and each value is the property's value. These properties define the attributes of the CRM object. ## Response `200` successful operation - BatchResponseSimplePublicUpsertObject: Represents the result of a batch upsert operation, including the operation’s status, timestamps, and a list of successfully created or updated objects. - `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` SimplePublicUpsertObject[], required: An array of objects representing the results of the upsert operation. Each object contains details of an upserted CRM object. - `archived` boolean, required: Indicates whether the object is archived. A boolean value. - `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. - `new` boolean, required: Indicates whether the object is newly created. A boolean value. - `objectWriteTraceId` string: A trace ID for tracking the write operation of the object. - `properties` object, required: A map of property names to their current values for the object. - `propertiesWithHistory` object: A map of property names to their values, including a history of changes with timestamps. - `updatedAt` string, date-time, required: The date and time when this object was last updated, in ISO 8601 format. - `url` string: The URL link to access this object. - `warnings` PublicObjectWarning[]: A list of warnings associated with the object, each containing a category, message, and context. - `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/upsert/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)