canonical: https://jentic.com/apis/hubspot.com/hubspot-crm-users

# HubSpot Users

The HubSpot CRM Users API exposes the User CRM object, which represents end users tracked alongside contacts, companies, and deals (distinct from the HubSpot account owners managed by the Users Provisioning API). Each User record supports custom properties, associations to other CRM objects, and the standard CRM object operations. The API includes single-record CRUD, batch read, batch create, batch update, batch upsert by unique property, batch archive, and a search endpoint with filters and sorting on /crm/v3/objects/users.

## For AI agents

Create, read, update, search, and archive User CRM records - the end-user object on /crm/v3/objects/users - including efficient batch operations and external-key upsert.

## Scope

Does not handle HubSpot account seat provisioning, login authentication, or permissions - use for managing end-user CRM records on /crm/v3/objects/users only.

## Capabilities

- Create a User record via POST /crm/v3/objects/users
- Read a User record by ID with GET /crm/v3/objects/users/{userId}
- Update User properties with PATCH /crm/v3/objects/users/{userId}
- Search User records by property values via POST /crm/v3/objects/users/search
- Bulk-create User records using POST /crm/v3/objects/users/batch/create
- Upsert User records keyed by an external user ID with POST /crm/v3/objects/users/batch/upsert
- Archive a User record with DELETE /crm/v3/objects/users/{userId}

## Use cases

### Syncing Application Users Into HubSpot

SaaS companies want to track each application end-user as a CRM record so support, success, and product teams can see usage context inside HubSpot. POST /crm/v3/objects/users/batch/upsert keyed by an external user ID property runs nightly to create new users and update existing ones with the latest profile fields. Existing records are matched by the external ID, avoiding duplicates that would otherwise creep in from email-based matching.

Example prompt: Call POST /crm/v3/objects/users/batch/upsert with idProperty='external_user_id' and inputs containing email, role, signup_date, and external_user_id for each application user.

### Per-User Engagement and Health Tracking

Customer success teams use the User CRM object to store per-user health metrics (last login, feature usage, NPS) so risk dashboards reflect individual seat-level activity, not just account-level. POST /crm/v3/objects/users/search returns User records filtered by health score or activity windows, enabling targeted outreach. Updates land via PATCH on individual records or batch update during scheduled jobs.

Example prompt: Call POST /crm/v3/objects/users/search with filters on last_login_at older than 30 days and health_score below threshold, then export the result for outreach.

### Identity Provider Driven User Lifecycle

When the company uses an identity provider as the source of truth, a webhook from the IdP triggers a HubSpot User update - provisioning, attribute changes, and de-provisioning. POST /crm/v3/objects/users on creation, PATCH on update, and DELETE on de-provision keep the HubSpot record aligned with the IdP. Using batch endpoints during full reconciliations keeps the load manageable.

Example prompt: On IdP webhook, call POST /crm/v3/objects/users (create) or PATCH /crm/v3/objects/users/{userId} (update) or DELETE (deprovision) with the relevant payload.

### AI Agent Customer Lookup

An AI support agent answers questions like 'show me Jane Doe's profile' by searching HubSpot User records by email or external ID. Through Jentic the agent searches for the User search and read operations, executes them, and returns the typed result. Jentic stores OAuth credentials in its vault so the agent only handles scoped execution tokens.

Example prompt: Search Jentic for 'find hubspot user by email', load POST /crm/v3/objects/users/search, and execute it with a filter on email equal to the requested address.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /crm/v3/objects/users | Create a User record |
| GET | /crm/v3/objects/users/{userId} | Read a User record |
| PATCH | /crm/v3/objects/users/{userId} | Update a User record |
| DELETE | /crm/v3/objects/users/{userId} | Archive a User record |
| POST | /crm/v3/objects/users/search | Search User records |
| POST | /crm/v3/objects/users/batch/upsert | Upsert User records by external key |
| POST | /crm/v3/objects/users/batch/create | Batch create User records |

## Key resources

- **Basic** — Single-User-record CRUD on /crm/v3/objects/users including read, list, create, update, and archive.
- **Batch** — Batch read, create, update, upsert, and archive operations for processing many User records per request.
- **Search** — Filter User records by property values and associations via POST /crm/v3/objects/users/search.

## Why Jentic

- **Setup:** Wiring HubSpot CRM Users by hand means learning its OAuth2 access token or private app token auth, targeting the api.hubapi.com host, and handling batch and search calls yourself. Through Jentic you install once, import HubSpot CRM Users from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Users API puts the user id in the URL path (/crm/v3/objects/users/{userId}), so a rule can pin your agent to one user record for read and update. You choose the operations it may call, so destructive ones like deleting a user record or batch upsert are not included unless you add them.
- **Credential handling:** Your HubSpot access token or private app token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a HubSpot user by email' or 'update a user record', and Jentic returns the matching Users operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Salesforce REST API** — Salesforce Person Account or custom User-equivalent objects offer comparable end-user record management.
- **HubSpot Contacts** — Contacts are typically the broader marketing/sales record while User records track product end users - both often coexist.
- **HubSpot Companies** — User records typically associate to a Company so account-level reporting reflects user-level activity.

## FAQ

### What authentication does the HubSpot CRM Users API use?

It supports OAuth 2.0 (recommended for public apps) and HubSpot private app access tokens passed as a Bearer token in the Authorization header. Through Jentic the token is stored encrypted in the vault and injected at execution time so the agent never holds the raw secret.

### Is the User CRM object the same as a HubSpot account user (seat)?

No. This API manages the User CRM object - an end-user record that lives alongside contacts and companies. HubSpot account seats (people who log into HubSpot) are managed via a separate Users Provisioning API and are not the subject of /crm/v3/objects/users.

### What are the rate limits for the HubSpot CRM Users API?

HubSpot enforces 100 requests per 10 seconds for OAuth apps and 190 per 10 seconds for private apps on Enterprise tiers, plus daily quotas. Use POST /crm/v3/objects/users/batch/upsert and batch/update (up to 100 records each) for high-volume sync jobs.

### How do I upsert User records by an external ID through Jentic?

Search Jentic for 'upsert hubspot user record', load POST /crm/v3/objects/users/batch/upsert, and execute it with idProperty set to your external_user_id property and inputs containing each user's fields. Jentic returns typed responses for each record.

### Can I associate a User CRM record with a Company?

Yes. User records support standard CRM associations - pass association inputs when creating the user, or use the Associations API to link an existing User record to a Company, Contact, or Deal.

### Does archiving a User record with DELETE /crm/v3/objects/users/{userId} delete it permanently?

No. Archive is a soft delete - the record is removed from default lists and search results but can be restored within HubSpot's retention window. To permanently remove records you must use HubSpot's GDPR delete process.

### Can I limit what my agent is allowed to do with the HubSpot CRM Users API?

Yes. Because you run Jentic One yourself, your own rules decide which HubSpot CRM Users operations and credentials the agent may use. Since the API puts the user id in the URL path (/crm/v3/objects/users/{userId}), a rule can pin the agent to reading and updating a single user record, and you choose which operations it can call at all. Destructive calls like archiving a record with DELETE /crm/v3/objects/users/{userId} or bulk-writing with POST /crm/v3/objects/users/batch/upsert stay off unless you explicitly allow them.