HubSpot Users
Browse all Hubspot APIs✓ Official Vendor SpecCRMContact Managementoauth2,apiKey11 EndpointsREST
For 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.
Use for: I need to create a User CRM record for a newly registered application user, Look up a User record by an external auth provider ID, Update properties on an existing User record, Search for User records that match a specific property value
Not supported: Does not handle HubSpot account seat provisioning, login authentication, or permissions — use for managing end-user CRM records on /crm/v3/objects/users only.
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.
Install Jentic One Beta
Connect the Users to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Users, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Users API.
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
Patterns agents use Users API for, with concrete tasks.
★ 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.
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.
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.
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.
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
11 endpoints — 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).
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth tokens and private app keys are stored encrypted in the Jentic vault. Agents receive scoped execution tokens — the raw secret never enters agent context or logs.
Intent-based discovery
Agents search Jentic with intents like 'find hubspot user by email' and Jentic returns the matching Users operations with typed input schemas, so the agent can call the right endpoint without browsing HubSpot's docs.
Time to first call
Direct HubSpot Users integration with OAuth and external ID matching: 1-2 days. Through Jentic: under 30 minutes — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Users API through Jentic.
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.
GET STARTED