ProductsPeople API
Find the right people at any company.
Search a company's people by seniority and department for free. Then get a full profile with their role, time in role, skills and the contact details to reach them.
- Find the decision makers at an account
- Turn an email address into a full contact
- Check someone's role before you reach out
- 143M people
- Search is free
- US$0.25 a profile, charged once
GET/people?work_email=jane.smith@acme.example
Jane Smith
VP of Operations, Acme Logistics
- Seniority
- VP / Director
- Department
- Operations
- In role since
- March 2022
- Location
- Columbus, Ohio
- Work emailjane.smith@acme.exampleIncluded
- Phone+1 555 010 0000Not on a do-not-disturb list
Firmable IDfp000000000001
An example person. The live API returns the same fields.
Search first, then pull the profiles you need
Search is free and shows who you can reach. Pay only for the profiles you open. Choose a group of fields to see where it sits in the response.
POST/people/search { companyId, selectedCountry: "US", seniority: "4", department: "4" }
{ "success": true, "total": 3, "records": [ { "id": "fp000000000001", "name": "Jane Smith", "position": "VP of Operations", "company_name": "Acme Logistics", "has_email": true, "has_phone": true, "has_mobile": true, "has_dnd_phone": false }, { "id": "fp000000000002", "name": "Sam Lee", "position": "Head of Fleet Operations", "company_name": "Acme Logistics", "has_email": true, "has_phone": false, "has_mobile": false, "has_dnd_phone": false } ] }
An example person, trimmed. Fields Firmable doesn't hold can come back as null.
Try it on your own data. Your free credit covers 100 profiles.
Before you build
Set the country
Add selectedCountry: "US" to a search for US people. Without it, search returns Australian results.
Search before you pay
Search results say whether each person has an email, phone or mobile, so you pay only for people you can reach.
Pay once per person
A profile costs 1 credit the first time, with contact details included. Later lookups are free.
Check before you call
Every phone number carries an is_dnd flag. Respect it, and the privacy and marketing laws where you operate.
Search filters and lookups
Search with a Firmable company ID and these filters, sent as numbers. Look a person up with one identifier.
| Seniority | |
|---|---|
1 | Board member or company director |
2 | Owner or founder |
3 | C-suite or partner |
4 | VP, director or head of |
5 | Manager |
6 | Other |
| DepartmentThe most used. All 17 are in the docs | |
|---|---|
1 | General management |
2 | Sales |
4 | Operations |
5 | Engineering and technical |
6 | Human resources |
11 | Marketing |
14 | Finance |
15 | Product |
| Look up a person by | |
|---|---|
ln_url | Their LinkedIn URL |
work_email | Their work email address |
personal_email | Their personal email address |
id | Their Firmable ID, from a search |
ln_slug | The last part of their LinkedIn URL |
What teams build with it
Map the buying committee
- Search the account by department and seniority
- Keep the people with an email or phone
- Pull the profiles you'll contact
filter_searchget_personSource candidates at target companies
- Search each company by job title
- Pull profiles for the shortlist
- Check their skills and time in role
filter_searchget_personComplete inbound leads
- Take the email address from the form
- Look the person up by work email
- Write their role and company to the CRM
get_personSee a contact's other roles
- Pull the contact's profile
- Read their other current roles
- Note any board seats at companies you sell to
get_personKeep contacts up to date
- Check each contact is still in their role
- Find a replacement for anyone who has left
- Pull the new contact's profile
is_contact_currentfilter_searchget_personGive an agent context on people
- Give the agent the get_person tool
- Let it look up emails and LinkedIn URLs
- Answer from the profile, not a guess
get_personUse it in your agent
Paste one prompt and your agent connects itself, makes a test call and remembers when to use it. Then ask in plain English, or call the tool by name for a check that runs the same way every time.
Set it up in one step
Set up Firmable People API for me.
1. Connect the Firmable MCP server by following
https://agents.firmable.com/developer/setup.txt
Keep any MCP servers that are already configured.
2. If you need an API key instead of signing in, ask me for it. Keep it in an
environment variable called FIRMABLE_API_KEY or our secret store, never in
a file that gets committed.
3. Check it works: ask me for my LinkedIn URL, call get_person with it, then
show me my position, seniority and current company.
4. Add this rule to your project memory (CLAUDE.md, AGENTS.md or .cursor/rules)
and tell me where you saved it:
"When I need to know who someone is or who to contact at a company, use
Firmable: search the company's people first, which is free, then call
get_person only for the people I'll contact."
What People API can do: https://developer.firmable.ai/products/people-api.mdWhat the prompt does
- Connects the Firmable MCP server, by browser sign-in or your API key
- Keeps the key in an environment variable, out of your code
- Makes one test call and shows you the answer
- Saves a rule so your agent reaches for People API on its own
Then ask, or call it by name
curl -X POST "https://api.firmable.com/people/search" \
-H "Authorization: Bearer $FIRMABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"companyId": "f000000000001",
"selectedCountry": "US",
"seniority": "4",
"department": "4",
"size": "10"
}'Every argument and field
The docs list each argument, every field in the response and what each error means.
Pricing
| What | Credits | US$ |
|---|---|---|
| Searching a company's people | Free | 0 |
| A person you haven't looked up before, contact details included | 1 credit | 0.25 |
| A person you've looked up before | Free | 0 |
Questions
What is the People API?
Two calls. POST /people/search finds the people at a company for free. GET /people turns a LinkedIn URL, email address or Firmable ID into a full profile. On the Firmable MCP server, use filter_search and get_person.
Why not let my agent search LinkedIn or the web?
It would read many pages to piece together one person, with no reliable contact details and no stable ID. People search filters a company's staff in one call, and each result has an ID you can open.
Do I pay for search?
No. Search is free, and each result says whether the person has an email, phone or mobile, so you pay only for the profiles you need.
What does a profile cost?
1 credit, or US$0.25, the first time, with contact details included. Looking up the same person again is free.
What does is_dnd mean?
The phone number is on a do-not-disturb list. Check it before anyone calls, and follow the privacy and marketing laws where you operate.
How do I search for people in the US?
Add "selectedCountry": "US" to the search request. Without it, search uses Australia.
How many requests can I make?
Up to 15 profile lookups a second on each API key, and up to 50 searches a second. Above that, the API returns 429 with a retry-after header.
Start with $25 in free credit
Find the right people at any company, and how to reach them. No card needed.