The same lookup, from your own code
Yes. On Pro and above you can look a person up from your own code with a workspace API key. The rules are the ones the extension follows: one credit per person, nothing for a miss, and no overage — when the balance is empty the call is declined rather than billed. Ask for the balance first, free.
- Available on
- Pro and Scale
- Charge
- One credit per person
- Out of credits
- Declined, nothing charged
- Auth
- Bearer key, per workspace
50 addresses free every month · no card
One person in, one person out
A shape rather than a signature. The docs carry the real field names, and they are the ones to build against.
You send what you know about somebody — a name, and a company or a domain if you have one. You get back the person, whether an address was found, what kind of evidence stands behind it, and the two things a script has to know: whether that call charged, and what is left.
POST /api/v1/lookup
Authorization: Bearer <your workspace key>
{
"name": "Dana Whitfield",
"company": "Bramble Co"
}
200 OK
{
"person": {
"email": "dana@brambleco.com",
"status": "verified",
"confidence": 96
},
"charged": true,
"credits": 4831
}Illustrative. Field names, the base URL and the error codes are not fixed by this page — they live in the API reference, which is what a client should be written against. If something there disagrees with what the API did, write to support@cuvy.io and the reference is what gets fixed.
There is a second call worth knowing about and it is the boring one: asking for the balance. It costs nothing, it is the same number the app and the extension show, and calling it before a batch is how a job knows whether to start.
A script does not get its own billing
Everything true of a lookup in the browser is true of a lookup from your server. That is the whole design.
- One person, one credit, whichever surface found them
- A person is charged for once, ever, on the workspace that paid. Asking for them again from a different machine, a different seat or a different script returns what is stored and costs nothing.
- One balance, and you can read it for free
- The API does not have its own wallet, its own currency or its own price. It draws on the workspace balance, and the call that reports that balance is free — so the cost of a run is knowable before the run.
- The refusal, rather than the overage
- Reach the end of the balance and the call is declined with a message saying nothing was charged. No card is touched, no partial credit is taken, and the job stops where you can see it stopped.
Three steps, and one of them is revoking
- Owner or Admin
Make a key in the workspace settings
An Owner or an Admin creates it. The secret is shown once, at that moment, and is not retrievable afterwards — if it is lost, revoke it and make another.
- One header
Send it as a bearer token
One header on every request. Keys belong to the workspace rather than to the person who made them, so somebody leaving the team does not silently break a nightly job.
- Effective immediately
Revoke it the moment it leaks
Revoking takes effect on the next call. A key cannot create another key — that is a signed-in action — so a leaked one cannot grow itself a replacement before you get to it.
No second price list
The three numbers a procurement conversation usually needs.
- $49
- a month, the plan the API starts on
- 0
- separate API rate cards
- 3
- active keys per workspace
Scale at $99 includes it too. Free, Starter and Growth do not — the API comes with the plan rather than as an add-on with its own contract.
A lookup from code costs the same as a lookup in the side panel. No per-call fee, no minimum spend, no commitment to buy a block of calls.
Enough for production, staging and the script somebody wrote once. Revoke one and the slot comes back.
What people ask before writing a client
Which plans include API access?
Pro at $49 a month and Scale at $99. Free, Starter and Growth do not include it. Moving up a plan turns it on the same day, and there is no separate API subscription on top of the plan — the same credits pay for calls from your code and lookups in the browser.
How does a script work out what a batch will cost before it starts?
It asks for the balance — that call is free and returns the same number every other Cuvy surface shows — and compares it with the number of people it is about to send. After that, each lookup reports in its own response whether it charged and what is left, so a loop can keep a running total and stop on your terms rather than ours.
What happens when the balance runs out halfway through a script?
The call is declined and says so, with the message that nothing was charged and the balance it stopped at. There is no overage, nothing is billed to the card, and no partial credit is taken for the person it was working on. Everything found before that point is already yours.
Do API lookups and extension lookups share a balance?
Yes, and they share the people too. One workspace, one pool of credits, one record of who has been found. A person revealed in the side panel this morning comes back from the API this afternoon for nothing, because the credit for that person was already spent.
Is there a rate limit?
Sixty requests a minute per key, on every v1 endpoint. Past that a call is answered 429 with a Retry-After header, and nothing is looked up or charged — a client that waits the stated seconds and tries again loses nothing. If you are planning a batch in the tens of thousands, that is the pace to write the loop for.
Where is the actual reference — endpoints, fields, error codes?
On the API reference page in the docs. The example on this page is a shape rather than a signature: it exists to show that a call is one person in and one person out. The reference carries the base URL, every field name, the error list and the webhook signature, and it is the page a client should be written against.
50 addresses free every month · no card