Official vendor OpenAPI document · agent-readyCRMContact 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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-crm-users" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-crm-users" | 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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
U
Users
- Foundational (D-)41/100
74
Foundational Compliance63
Developer Experience & Jentic Compatibility17
AI-Readiness & Agent Experience94
Agent Usability70
Security53
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
74
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: BSignals: 4
8%
Example Density
How richly the API is illustrated with examples.
95%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
17
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
17%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
53%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
70
Security
Trust, risk posture, and security compliance.
Grade: A-Signals: 1
70%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
53
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: CSignals: 1
53%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
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.
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.
GET STARTED