HubSpot
Recognise the caller before they say their name
The useful half of a HubSpot connection is not logging the call afterwards. It is the lookup in the first second, so the agent opens with the right context instead of asking who is calling and why.
Lookup cost
1 search call
Search ceiling
5 / second, per account
Write path
After the call
What gets asked for
Four jobs, in the order people want them
Recognise the caller from the number
One search on the incoming number, before the agent speaks. Everything else on this page exists to make that single call reliable.
Read the open deal or ticket
So the opening line can refer to the reason they are probably calling, instead of asking them to explain it.
Log the outcome on the timeline
Written after the caller has hung up. Nobody has ever stayed on the line to hear a CRM confirm a write.
Create or update a deal
Only when the conversation actually produced one, and only with fields the agent could not have invented.
The constraint that bites
Search is the ceiling, not your call volume
A HubSpot private app on Professional or Enterprise gets 190 requests per ten seconds, which sounds like more than any phone line could use. Caller lookup does not spend that budget. Finding a contact by phone number is a search call, and search endpoints are limited to five requests per second per account, separately and far more strictly. That cap is shared across every integration on the account, so the number to plan against is not your call volume. It is your call volume plus whatever else already searches HubSpot.
So the lookup is cached, and the cache is keyed on the number rather than on the contact.
Numbers
- Burst limit
- 190 requests / 10s per private app
- Search endpoints
- 5 requests / second per account
- Daily limit
- 625,000 (Pro) or 1,000,000 (Enterprise), shared across apps
- Our tool call
- 30s, attempted once
In practice
A recognised call, end to end
inbound +31612345678 t+0.00s
[norm] normalised → 612345678 t+0.00s
[cache] miss t+0.01s
[hs] POST /crm/v3/objects/contacts/search
filter: phone CONTAINS 612345678
[hs] 200 · 1 result · 340ms t+0.35s
[cache] stored · ttl 4h t+0.35s
[agent] "Good afternoon, Mr de Vries." t+0.41s
search budget used 1 of 5 per second
the caller heard nothing before the greetingWhat gets built
One endpoint, two paths
The read path answers the tool call: it normalises the number, checks the cache, searches HubSpot only on a miss, and returns a short answer the model can speak. The write path never blocks the conversation. Call outcomes are queued and pushed after the caller has hung up, because nobody has ever hung on to hear a CRM confirm a write.
{
"found": true,
"say": "Mr de Vries, from De Vries Installatie",
"open_deal": "heat pump quote, sent 6 August",
"last_contact": "eight days ago"
}
// Four fields, all of them speakable. Not the contact object:
// a model handed forty fields will read one of them out loud.What we need from you
Four things, and the first call is easier with all four
A private app token
With read on contacts and deals, and write on engagements if we log the call. A private app, not somebody's personal key, so it survives that person leaving.
Which property holds the phone number
Most portals have several, and the one people actually fill in is rarely the one called phone. We check this before writing any code.
Who else searches this portal
The five per second is shared across the account. If a warehouse sync already uses four of it, we design around one.
Where the call should land
On the contact, on the deal, or on both. It sounds like a detail and it decides what your sales team sees on Monday.
Questions we get first
Is there a native HubSpot integration?
No. There is a tool contract. Your agent calls a tool, we post to an endpoint you own, and that endpoint talks to HubSpot with your private-app token. We will build that endpoint with you, or you build it against our API.
Where does my HubSpot token live?
In your environment. VoiceDock posts to a URL you own and never stores a HubSpot credential.
What happens when the caller is not in HubSpot?
The agent is told the lookup returned nothing and greets them as a new caller. It does not guess, and it does not read out a near match, because a wrong name in the first sentence costs more than no name at all.
Can the agent write a deal during the call?
It can, and usually it should not. Writes during the call add latency the caller hears for a result they cannot see. The exception is a write the caller needs confirmed out loud, such as a booked appointment.
Going deeper
The two articles underneath this page
Thirty seconds, one attempt
Why a tool call gets a single try, which lookups may hold up a conversation, and what the agent says while it waits.
Thirty seconds, one attemptKnowing who is calling before they say so
The number arrives in E.164 and your CRM holds six other formats. Normalisation, caching, and shared numbers.
Knowing who is calling before they say soBring us the awkward one
Send the system, its API documentation and one call you want to automate. On the intake call we will tell you whether the hard part is the code or the configuration, and which of the two sets the date.