# People API

> 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.

- Web page: https://developer.firmable.ai/products/people-api
- Get a free API key: https://platform.firmable.com/sign-up
- Docs: https://docs.firmable.com/api-reference/overview/api-reference/endpoint/people-get
- Full API reference: https://docs.firmable.com/api-reference/overview

## What you can do

- Find the decision makers at an account
- Turn an email address into a full contact
- Check someone's role before you reach out

Key facts: 143M people, Search is free, US$0.25 a profile, charged once.

## How it works

1. **Search a company for free.** Filter by job title, seniority and department, and see who has an email or phone.
2. **Get the profiles you need.** By LinkedIn URL, work or personal email, or Firmable ID.
3. **Reach them.** Emails and phone numbers come with the profile, and each phone is flagged if it's on a do-not-disturb list.

Fields in every response:

- `position, seniority, department`: Job title, seniority and department.
- `current_company`: Their company, with its Firmable ID, size and website.
- `time_in_current_role`: When they started, with month_joined and year_joined.
- `emails, phones`: Work emails, and phones with an is_dnd flag.
- `skills, education`: The skills they list and where they studied.
- `secondary_position`: Other current roles, such as board seats.

## 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

### Department (the 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

### Sales teams: map the buying committee

1. Search the account by department and seniority.
2. Keep the people with an email or phone.
3. Pull the profiles you'll contact.

Tools: `filter_search`, `get_person`.

### Recruiters: source candidates at target companies

1. Search each company by job title.
2. Pull profiles for the shortlist.
3. Check their skills and time in role.

Tools: `filter_search`, `get_person`.

### Revenue operations teams: complete inbound leads

1. Take the email address from the form.
2. Look the person up by work email.
3. Write their role and company to the CRM.

Tools: `get_person`.

### Account managers: see a contact's other roles

1. Pull the contact's profile.
2. Read their other current roles.
3. Note any board seats at companies you sell to.

Tools: `get_person`.

### Customer success teams: keep contacts up to date

1. Check each contact is still in their role.
2. Find a replacement for anyone who has left.
3. Pull the new contact's profile.

Tools: `is_contact_current`, `filter_search`, `get_person`.

### Agent builders: give an agent context on people

1. Give the agent the get_person tool.
2. Let it look up emails and LinkedIn URLs.
3. Answer from the profile, not a guess.

Tools: `get_person`.

## Use it in your agent

Paste this into your agent to connect Firmable, make a test call and save a rule for when to use it:

```text
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.md
```

### Search, free

```text
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"
  }'
```

Seniority 4 is VP, director or head of. Department 4 is operations.

### Profile

```text
curl "https://api.firmable.com/people?work_email=jane.smith@acme.example" \
  -H "Authorization: Bearer $FIRMABLE_API_KEY"
```

Or send ln_url, ln_slug, personal_email or id.

### Ask your agent

```text
Use Firmable to find the heads of operations and finance at acme.example.
Show who has an email, then get the profiles of the two most senior.
```

Works in any client with the Firmable MCP server.

## 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 |

One credit costs US$0.25.

## 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.
