--- title: "How to use a people search API: a developer's guide – Invenitor" description: "Call a people search API over REST: authenticate, send a plain-words query, read people as JSON, look up contacts, and handle empty results and limits." url: https://invenitor.com/guides/people-search-api-for-developers agents: https://invenitor.com/llms.txt mcp: https://api.invenitor.com/mcp --- [Home](https://invenitor.com/)/[Guides](https://invenitor.com/guides)/How to use a people search API: a developer's guide Credits, API and agents # How to use a people search API: a developer's guide To use Invenitor's people search API, send a POST request with your key and a plain-words query to /api/v1/people/search, then read people from the JSON response. By Invenitor team. Updated 2026-11-01. ## What do you need before your first call? You need an account and a key. Sign in, then copy your key from the [API key page](https://invenitor.com/dashboard/key). It starts with pf\_live\_, and it is shown once, so store it right away. Every account has REST and MCP access on the same key. New accounts get 25 free credits, which covers one search and five contacts. That is enough to test the whole flow. Treat the key like a password. Keep it on your server, not in browser code, not in a mobile app, and never in a URL. If a key leaks, regenerate it from the same page. ## How do you search for people? Send a sentence. There is no query language to learn. This costs 20 credits (₹40) for up to 100 people, and it is free if it finds nobody. ``` curl -X POST https://api.invenitor.com/api/v1/people/search \ -H "Authorization: Bearer pf_live_..." \ -H "Content-Type: application/json" \ -d '{"query":"Heads of procurement at auto component makers in Pune"}' { "search_id": "...", "result_count": 100, "results": [ { "id": "...", "display_name": "...", "headline": "...", "company": "...", "profile_urls": ["..."] } ], "credits_used": 20 } ``` Store the search\_id. You can list past searches with GET /api/v1/people/searches, which is free, so you do not need to pay for the same search again. The advice in [how to write a people search query](https://invenitor.com/guides/write-a-people-search-query) applies here exactly as it does in the app. Short and specific beats long and clever. ## How do you get a contact? Pass a LinkedIn or GitHub link from the profile\_urls field, or one you already have. A name helps. This costs 1 credit (₹2), and only when an email or phone comes back. ``` curl -X POST https://api.invenitor.com/api/v1/find \ -H "Authorization: Bearer pf_live_..." \ -H "Content-Type: application/json" \ -d '{"full_name":"Jordan Lee","linkedin_url":"https://linkedin.com/in/example"}' ``` Treat an empty result as a normal outcome, not as an error. Your code should expect that some people return an email only, some return a phone only, and some return nothing. Repeating a lookup for the same person is free, so you do not need a cache just to save credits, although one may still save time. ## What other endpoints are there? These all use the same header. Full details are in the [API docs](https://invenitor.com/docs). | Method and path | What it does | | --------------------------- | ----------------------------------------------- | | POST /api/v1/people/search | Find people | | GET /api/v1/people/searches | List your past searches | | POST /api/v1/find | Look up one contact | | GET /api/v1/usage | Your usage for the last 24 hours | | GET /api/v1/key/info | Details of this API key | | GET /api/v1/health | Health check | | GET /api/pricing | Live packs and credit costs, with no key needed | ## What should your code handle? A few things are worth building in from the start: - Rate limits. The live pricing list shows contact lookups at five a minute. Queue your lookups, and back off when you are told to slow down. - Errors. Read the code in the error response rather than matching its message text, since messages can change. - Timeouts. Timeouts do not spend credits, so it is safe to retry after a pause. - Running out. Credits expire after 30 days, and you can run out mid-batch. Check your usage first, and fail in a way that tells a person what happened. - Data care. Store only what you need, and delete it when you are done. A person can ask for their details to be removed, so give your own users a way to do that too. ## What are good and bad uses? Good uses include filling in details for a person a user has picked, adding a research step to an internal tool, and letting your users look for experts in your product. In each case, a person decides who to contact. Do not build a mass-mailing pipeline on this. Invenitor's [Terms](https://invenitor.com/terms) prohibit using its data for unconsented electronic marketing, telemarketing or automated outreach, and they make you responsible for what you send. If your product sends messages, have your own users confirm each one, and keep a do-not-contact list. Very large volume is a conversation, so write to [hello@invenitor.com](mailto:hello@invenitor.com) before you build around it. ## How does this compare with other APIs? Other APIs differ mostly in query format and billing. People Data Labs accepts SQL or Elasticsearch and says "We charge per record retrieved" ([PDL reference](https://docs.peopledatalabs.com/docs/reference-person-search-api)), so 100 records use 100 credits. Invenitor charges a flat amount per search and separately for contacts you pick. Which suits you depends on whether you want bulk records or a search you can run from a sentence. See [Invenitor vs People Data Labs](https://invenitor.com/compare/people-data-labs) and [Invenitor vs RocketReach](https://invenitor.com/compare/rocketreach). If an AI agent is calling your tool rather than your own code, read [the MCP guide](https://invenitor.com/guides/connect-people-search-to-an-ai-agent) instead of writing a wrapper. ## Common questions Is there a free tier for the API? New accounts get 25 free credits, with no card, and these work on the API. After that you buy packs. Can I call the API from the browser? Do not. Your key would be visible to anyone. Call it from your own server. Try one real search for free New accounts get 25 free credits, with no card. That covers one search and five contacts. [](https://invenitor.com/login?from=https%3A%2F%2Fpeople.invenitor.com%2Fsearch&x=w7&q=c5&z=s1)[](https://invenitor.com/pricing?x=w7&q=c5&z=s2) ## Keep reading - [How to connect people search to an AI agent with MCP](https://invenitor.com/guides/connect-people-search-to-an-ai-agent) - [How to write a people search query that works](https://invenitor.com/guides/write-a-people-search-query) - [How Invenitor credits work, with worked examples](https://invenitor.com/guides/how-invenitor-credits-work) - [How to find an email from a LinkedIn profile](https://invenitor.com/guides/find-an-email-from-a-linkedin-profile)