ContactOut People Search API

openapi: 3.2.0
info:
  title: ContactOut People Search API
  version: v1
  summary: 'B2B contact data: people and company enrichment, search, contact checks, email verification, campaigns and usage stats.'
  description: Welcome to ContactOut's API. Find anyone's email & phone number 10x faster with the most powerful sales and recruitment intelligence software available. (Generated from the published API reference at https://api.contactout.com; every operation carries x-source pointing at the section it was read from.)
  contact:
    name: ContactOut
    url: https://contactout.com/meeting?utm_source=api_docs
  termsOfService: https://contactout.com/terms
  x-generated-from: documentation
  x-generated-on: '2026-10-07'
  x-generator: 'api-evangelist enrichment pass: deterministic parse of the Slate API reference HTML (headings, parameter tables, example blocks); the pipeline generator generate-contract-from-docs.py was run first and its path-collapse heuristic merged the literal resources linkedin/email/domain into a {v1id} template, so its output was replaced by this parse'
servers:
- url: https://api.contactout.com
security:
- apiToken: []
tags:
- name: People Search API
paths:
  /v1/people/search:
    post:
      summary: People Search API
      tags:
      - People Search API
      operationId: peopleSearch
      description: 'POST https://api.contactout.com/v1/people/search


        Boolean Equations: Few input parameters mentioned in the table above can accept boolean equations as input. Check the "Accepts Boolean" column to know which input fields can accept boolean equations. You can use boolean equations to filter based on a specific criteria. e.g. If you are looking for profiles who have the skills ReactJS and Python, but not Java, you can format the skills parameter as: { "skills": ["(ReactJS AND Python) NOT Java"] }. Always add brackets to ensure the boolean logic is applied correctly. The same logic will apply for the rest of the mentioned paramters. The supported boolean operators are: Boolean operators must be capitalized. Lowercase and, or, and not are treated as part of the search phrase, not as operators. For example, Financial Planning and Analysis is searched as a single phrase. For the industry parameter, prefix a value with NOT to exclude that industry (e.g. { "industry": ["NOT Computer Software", "Banking"] } returns profiles in Banking but not Computer Software). AND and OR are not supported for industry filters.'
      x-source: https://api.contactout.com#search-profiles-http-request
      x-section: People Search API
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeopleSearchResponse'
              example:
                status_code: 200
                metadata:
                  page: 1
                  page_size: 25
                  total_results: 0
                profiles:
                  https://linkedin.com/in/at-JqjtXv:
                    li_vanity: at-JqjtXv
                    title: Research Assistant
                    contact_availability:
                      personal_email: true
                      work_email: true
                      phone: true
                    contact_info:
                      emails: []
                      personal_emails: []
                      work_emails: []
                      work_email_status: []
                      phones: []
        '400':
          $ref: '#/components/responses/BadCredentials'
        '401':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleSearchRequest'
      x-cost:
      - Consumes 1 search credit for each profile returned.
      - Consumes 1 email/phone credit for every profile where email/phone info is found, if reveal_info=true is specified.
components:
  responses:
    Forbidden:
      description: 'You''re out of credits, please email your sales manager or book a meeting; or: No access to endpoint'
    RateLimited:
      description: 'Rate limit reached. Check header retry-after: <time_in_seconds> for when rate limit will reset'
      headers:
        retry-after:
          schema:
            type: integer
          description: Seconds until the rate limit resets
    BadCredentials:
      description: Bad credentials or invalid headers
    BadRequest:
      description: Bad request or invalid input
  schemas:
    PeopleSearchResponse:
      type: object
      properties:
        status_code:
          type: integer
        metadata:
          type: object
          properties:
            page:
              type: integer
            page_size:
              type: integer
            total_results:
              type: integer
        profiles:
          type: object
          properties:
            https://linkedin.com/in/at-JqjtXv:
              type: object
              properties:
                li_vanity:
                  type: string
                title:
                  type: string
                contact_availability:
                  type: object
                  properties:
                    personal_email:
                      type: boolean
                    work_email:
                      type: boolean
                    phone:
                      type: boolean
                contact_info:
                  type: object
                  properties:
                    emails:
                      type: array
                      items: {}
                    personal_emails:
                      type: array
                      items: {}
                    work_emails:
                      type: array
                      items: {}
                    work_email_status:
                      type: array
                      items: {}
                    phones:
                      type: array
                      items: {}
        contact_info:
          type: array
          items: {}
          description: Returns an array containing contact information including email and phone numbers (array)
        contact_availability:
          type: array
          items: {}
          description: Returns an array determining whether the profile contains the contact information (array)
    PeopleSearchRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the profile (text)
        job_title:
          type: array
          items: {}
          description: Accepts an array of job titles. (array, max:50)
        past_job_title:
          type: array
          items: {}
          description: 'Returns profiles that held these job titles in past (non-current) roles. Cannot be combined with current_titles_only: false. Cannot be combined with match_experience when both job_title and company are set. (array, max:50)'
        job_function:
          type: array
          items: {}
          description: Accepts an array of job functions to filter profiles by their functional area (e.g., Engineering, Marketing, Sales, Finance). Accepted values list (array, max:50)
        seniority:
          type: array
          items: {}
          description: Accepts an array of seniority levels to filter profiles by their career level. Accepted values list (array, max:50)
        current_titles_only:
          type: boolean
          default: 'true'
          description: 'Returns profiles matching the current job title. If specified false, the response will return profiles matching the current or past job title. (boolean, default: true)'
        include_related_job_titles:
          type: boolean
          default: 'false'
          description: 'Returns profiles with related job titles (boolean, default: false)'
        match_experience:
          type: string
          default: current
          description: 'Ensures job_title and company match in the same experience. current – Returns profiles that match the current experience.past – Returns profiles that match any past experience.both – Returns profiles matching either current or past experience.If set, current_titles_only and company_filter should not be used; otherwise, an error is returned. (string, default: current)'
        skills:
          type: array
          items: {}
          description: Accepts an array of skills (array, max:50)
        languages:
          type: array
          items: {}
          description: Accepts an array of language objects. Each object must have a language field (required string) and optionally a proficiency field (array of strings). If proficiency is not provided, any proficiency level is accepted. Accepted values list for proficiency. (array, max:50)
        education:
          type: array
          items: {}
          description: Accepts an array of schools/degrees (array, max:50)
        educations:
          type: array
          items: {}
          description: 'Accepts an array of education objects. Each object can have optional fields: school_name (string), field_of_study (string), and location (string). At least one field must be provided. (array, max:50)'
        location:
          type: array
          items: {}
          description: Accepts an array of locations (array, max:50)
        location_radius:
          type: integer
          description: Search radius in miles (1-500). Only works when location is provided and the location is a city / area. Filters profiles within the specified radius of the location. (integer)
        current_work_location:
          type: array
          items: {}
          description: Accepts an array of location strings (cities or countries). Filters profiles who currently work in any of the specified locations. (array, max:50)
        past_work_location:
          type: array
          items: {}
          description: Accepts an array of location strings (cities or countries). Filters profiles who previously worked in any of the specified locations. (array, max:50)
        company:
          type: array
          items: {}
          description: Accepts an array of company names (array, max:50)
        past_company:
          type: array
          items: {}
          description: Returns profiles that worked at these companies in past (non-current) roles. Cannot be combined with company_filter set to past, past_only, or both. Cannot be combined with match_experience when both job_title and company are set. (array, max:50)
        company_filter:
          type: string
          default: current
          description: 'current – Returns profiles matching the current company name    past – Returns profiles matching any past company name  past_only – Returns profiles where the company appears in past experience and is not their current employer.  both – Returns profiles matching either current or past experience (string, default: current)'
        current_company_only:
          type: boolean
          default: 'true'
          description: 'Returns profiles matching the current company name (boolean, default: true)'
        domain:
          type: array
          items: {}
          description: Accepts an array of domains (array, max:50)
        industry:
          type: array
          items: {}
          description: Accepts an array of industries. Prefix an industry with NOT to exclude it (e.g. "NOT Computer Software"). Accepted values list (array, max:50)
        keyword:
          type: string
          description: Returns profiles that contain the mentioned keyword anywhere in their profile (text)
        company_size:
          type: array
          items: {}
          description: Accepts an array of company size ranges. Accepted values list (array)
        years_of_experience:
          type: array
          items: {}
          description: Accepts an array of ranges in the format X_Y where X and Y are integers representing the minimum and maximum years of experience. e.g. ["2_5", "6_10"] means 2-5 years OR 6-10 years. (array)
        years_in_current_role:
          type: array
          items: {}
          description: Accepts an array of ranges in the format X_Y where X and Y are integers representing the minimum and maximum years in current role. e.g. ["1_3", "4_6"] means 1-3 years OR 4-6 years in current role. Cannot be used with recently_changed_jobs. (array)
        recently_changed_jobs:
          type: boolean
          default: 'false'
          description: 'If set to true, returns profiles whose current job started within the last 3 calendar months. Cannot be used with years_in_current_role. (boolean, default: false)'
        is_currently_working:
          type: boolean
          description: If true, returns only profiles with an active current role. If false, returns only profiles with no active current role. Omit to return both. (boolean)
        page:
          type: integer
          description: Provides results for the given page (integer)
        page_size:
          type: integer
          default: '25'
          description: 'Maximum number of profiles to return per page. Valid range is 1-25. When not provided, 25 profiles are returned. Search credits are charged only for the number of profiles returned. (integer, default: 25)'
        data_types:
          type: array
          items: {}
          description: Returns profiles containing atleast one of the specified data types. It accepts an array of one more values from this list [personal_email, work_email, phone] (array)
        reveal_info:
          type: boolean
          default: 'false'
          description: 'If set to true, contact_info will contain the emails and phone numbers of the profile and credits will be charged (boolean, default: false)'
        detailed_experience:
          type: boolean
          default: 'false'
          description: 'If set to true, the experience field returns detailed data like title, company_name, summary, start_date_year, start_date_month, end_date_year, end_date_month, is_current, linkedin_url, logo_url. If false, returns simple text strings. (boolean, default: false)'
        detailed_education:
          type: boolean
          default: 'false'
          description: 'If set to true, the education field returns detailed data like school_name, degree, field_of_study, description, start_date_year, end_date_year, url. If false, returns simple text strings. (boolean, default: false)'
        exclude_job_titles:
          type: array
          items: {}
          description: Accepts an array of job titles to exclude from results. (array)
        exclude_companies:
          type: array
          items: {}
          description: Accepts an array of company names to exclude from results. (array)
        exclude_companies_filter:
          type: string
          default: both
          description: 'Applies when exclude_companies is non-empty. current – Exclude if the company appears as the profile''s current employer only.past – Exclude if it appears in past roles only.both – Exclude if it appears in either current or past experience. (string, default: both)'
      required:
      - education
      - job_title
      - keyword
      - past_job_title
      - skills
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: token
      description: 'ContactOut uses API keys to allow access to the API. You can request an API key by booking a meeting. ContactOut expects the API key to be included in all API requests to the server in a header that looks like the following: token : <YOUR_API_TOKEN>'
externalDocs:
  url: https://api.contactout.com
  description: ContactOut API Reference
x-rate-limits:
- 'People Search API: 60 requests per minute'
- 'Contact Checker APIs: 150 requests per minute'
- 'Other APIs: 1000 requests per minute'