PeopleSearch.im Deliver API

openapi: 3.2.0
info:
  title: PeopleSearch.im Deliver 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: []
tags:
- name: Deliver
paths:
  /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. Send the same `filters` or `query` you searched with: the search runs exactly as /api/v1/search does, including the automatic broadening when there are no exact matches; any dropped filter fields are listed in `relaxed`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                filters:
                  $ref: '#/components/schemas/PeopleFilters'
                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.
      tags:
      - Deliver
components:
  schemas:
    PeopleFilters:
      type: object
      description: 'Exact filters, recommended for AI agents and programs: state each part of the request instead of a sentence. Values inside one list are alternatives (OR); different fields must all match (AND). Give a few variants where people word things differently (titles: ["M&A Associate", "Investment Banking Associate"]). When filters are given, `query` is only a label and is not parsed.'
      properties:
        first_name:
          type: array
          items:
            type: string
          description: 'To find one named person: their first name, with the variants they may use, e.g. ["Timothy", "Tim"]. Use with last_name, and add companies or company_domains when known ("Anqi Dai at Memorial Sloan Kettering" finds the one person).'
        last_name:
          type: array
          items:
            type: string
          description: 'To find one named person: their last name, e.g. ["Dai"]. If the name with the employer finds nobody, the search tries the last name at the employer, then the full name anywhere.'
        job_titles:
          type: array
          items:
            type: string
          description: 'Current job titles, matched as case-insensitive substrings ("Account Executive" also finds "Senior Account Executive"). Include the variants people use: ["VP Sales", "Vice President of Sales", "Head of Sales"].'
        exclude_job_titles:
          type: array
          items:
            type: string
          description: Titles to leave out, e.g. ["Intern", "Recruiter"].
        past_job_titles:
          type: array
          items:
            type: string
          description: Titles the person held before their current job.
        companies:
          type: array
          items:
            type: string
          description: Current employers by name, e.g. ["Stripe"].
        company_domains:
          type: array
          items:
            type: string
          description: Current employers by website domain, the most exact way to name a company, e.g. ["stripe.com"].
        past_companies:
          type: array
          items:
            type: string
          description: Former employers by name, e.g. ["McKinsey"] for ex-McKinsey people.
        locations:
          type: array
          items:
            type: string
          description: 'Where the person lives or works: cities, states, countries or regions, e.g. ["Frankfurt", "Munich"], ["Germany"], ["DACH"], ["Texas"]. Use "City, Country" to tell same-named places apart ("Paris, France"). Country names are safest; ISO codes are converted.'
        industries:
          type: array
          items:
            type: string
          description: Industry of the current employer, as LinkedIn names it, e.g. ["Investment Banking"], ["Software Development"], ["Hospitals and Health Care"], ["Venture Capital and Private Equity Principals"], ["Staffing and Recruiting"]. Common older names are mapped; a name that is not an industry is reported in `ignored` and not applied.
        schools:
          type: array
          items:
            type: string
          description: Schools the person attended, matched as substrings; add the local-language name too, e.g. ["University of Mannheim", "Universität Mannheim"].
        skills:
          type: array
          items:
            type: string
          description: Skills listed on the profile, e.g. ["Python", "Kubernetes"].
        languages:
          type: array
          items:
            type: string
          description: Languages the person speaks, e.g. ["German"] or ["DE"].
        keywords:
          type: array
          items:
            type: string
          description: Words to find anywhere on the profile (headline, descriptions, past roles), for what no other field covers.
        company_keywords:
          type: array
          items:
            type: string
          description: Words the current employer's own description should contain, for a KIND of employer no industry names exactly, e.g. ["hostel"], ["coffee"] (founders of coffee roasteries), ["SEO"] (with industries ["Marketing Services"] for SEO agencies), ["community college"].
        company_size_min:
          type: integer
          minimum: 1
          description: Minimum employees at the current employer.
        company_size_max:
          type: integer
          minimum: 1
          description: Maximum employees at the current employer.
        years_experience_min:
          type: integer
          minimum: 0
          description: Minimum total years of professional experience.
        years_experience_max:
          type: integer
          minimum: 0
          description: Maximum total years of professional experience.
      additionalProperties: false
  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.
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: find_work_email
    title: Find a person's work email
    credits: 2
  - 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