{"openapi":"3.1.0","info":{"title":"PeopleSearch.im API","version":"1.0.0","description":"The same people-search backend as PeopleSearch.im, over HTTP. Search a global professional database in plain English, reveal full profiles, and fetch verified professional emails. Pay-as-you-go: 1 credit per profile, credits refunded when a lookup finds nothing. The same tools are also available to AI agents as a Model Context Protocol (MCP) server at https://peoplesearch.im/api/mcp.","termsOfService":"https://peoplesearch.im/legal/terms"},"servers":[{"url":"https://peoplesearch.im"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"x-mcp":{"endpoint":"https://peoplesearch.im/api/mcp","transport":"streamable-http","description":"Remote MCP server exposing the same operations as agent tools. Authenticate with OAuth 2.1 (the MCP authorization spec; the server's 401 points at its protected resource metadata) or with the same API key as this REST API (Bearer token or X-API-Key header).","authorization":{"protectedResourceMetadata":"https://peoplesearch.im/.well-known/oauth-protected-resource/api/mcp","authorizationServerMetadata":"https://peoplesearch.im/.well-known/oauth-authorization-server"},"tools":[{"name":"people_search","title":"Search people","credits":0},{"name":"reveal_profile","title":"Reveal a person","credits":1},{"name":"find_people","title":"Find & unlock a batch of people","credits":1},{"name":"fetch_email","title":"Fetch a verified work email","credits":1},{"name":"verify_email","title":"Verify an email address","credits":1},{"name":"find_company_emails","title":"Find a company's emails","credits":2},{"name":"reverse_email_lookup","title":"Reverse email lookup","credits":13},{"name":"find_linkedin_profile","title":"Find a LinkedIn profile","credits":2},{"name":"lookup_linkedin_profile","title":"Look up a LinkedIn profile","credits":2},{"name":"lookup_company","title":"Look up a company","credits":1},{"name":"company_search","title":"Search companies","credits":0},{"name":"check_credits","title":"Check credit balance","credits":0}]},"paths":{"/api/v1/search":{"post":{"operationId":"searchPeople","summary":"Search people (free)","description":"Describe who you want in plain English and get masked previews plus the true total. Free; spends no credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","example":"Heads of Marketing at Series B SaaS in New York"},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"page":{"type":"string","description":"Next-page token from a prior response."},"drop":{"type":"array","items":{"type":"string"},"description":"Interpreted filter fields to remove and broaden the search."}}}}}},"responses":{"200":{"description":"Masked previews and the true total.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"total":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Opaque id for this person, stable across searches. Not their LinkedIn URL or name."},"token":{"type":"string","description":"Pass to /api/v1/reveal to unlock this person."},"maskedName":{"type":"string"},"title":{"type":"string"},"industry":{"type":"string","nullable":true},"companySize":{"type":"integer","nullable":true},"location":{"type":"string","nullable":true}}}},"token":{"type":"string","nullable":true,"description":"Next-page token."},"balance":{"type":"integer","nullable":true},"relaxed":{"type":"array","items":{"type":"string"},"description":"Filter fields dropped automatically because the query had no exact matches, least essential first. Empty when the query matched as written."}}}}}},"401":{"description":"Missing or invalid API key."}}}},"/api/v1/deliver":{"post":{"operationId":"deliverProfiles","summary":"Deliver full profiles (1 credit each)","description":"Re-run a search and unlock up to `count` full profiles in one atomic charge. 1 credit per newly unlocked profile; already-owned profiles are free. The search runs exactly as /api/v1/search does, including the automatic broadening when a query has no exact matches; any dropped filter fields are listed in `relaxed`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"count":{"type":"integer","minimum":1,"maximum":100,"default":100},"drop":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"The unlocked profiles, each with an id for the email step."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Out of credits."}}}},"/api/v1/reveal":{"post":{"operationId":"revealProfile","summary":"Reveal one profile (1 credit)","description":"Unlock a single profile from a search token. Set withEmail to also fetch the verified email (a second credit, refunded if none is found). Idempotent per person.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"A search result's token."},"withEmail":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"The full profile."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Out of credits."}}}},"/api/v1/email":{"post":{"operationId":"fetchEmail","summary":"Fetch a verified work email (1 credit)","description":"Look up the professional email for a profile id returned by deliver/reveal. Refunded if no email is found.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"The email and its status."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Out of credits."}}}},"/api/v1/tools":{"post":{"operationId":"runTool","summary":"Run a single lookup tool","description":"Dispatch any lookup tool: email-verifier, reverse-email-lookup, email-finder, linkedin-profile-finder, linkedin-profile-lookup, company-lookup, or company-search. Credits vary by tool and are refunded when nothing is found.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool","input"],"properties":{"tool":{"type":"string","enum":["email-verifier","reverse-email-lookup","email-finder","linkedin-profile-finder","linkedin-profile-lookup","company-lookup","company-search"]},"input":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"The tool result."},"401":{"description":"Missing or invalid API key."},"402":{"description":"Out of credits."}}}},"/api/v1/credits":{"get":{"operationId":"getCredits","summary":"Get credit balance","description":"Return the current credit balance for the API key.","responses":{"200":{"description":"The balance."},"401":{"description":"Missing or invalid API key."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk_sift_…","description":"A PeopleSearch.im API key, created at /developers."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The same PeopleSearch.im API key (sk_sift_…), sent as a header."}}}}