People Search API via Filters

The People Search API via Filters allows you to search for detailed professional profiles based on custom filters. This API provides real-time results, making it a powerful tool for gathering information about professionals matching specific criteria.

When to Use

Use this API when you need to retrieve professional profiles that match certain criteria, such as industry, job title, location, company size, and more. It's ideal for:

How to Make a Request

To use this API, send a POST request to the following endpoint:

POST /screener/person/search

Authentication

Include your Bearer token in the Authorization header.

Headers

• Content-Type: application/json
• Authorization: Bearer <your_token>

Body Parameters

• filters (array): An array of filter objects specifying your search criteria.
• page (integer): The page number for pagination.

Building Filters

Filters allow you to refine your search results by various criteria. Each filter object should include:

• filter_type: The type of filter you want to apply.
• type: The operation type (e.g., in, not in, between).
• value: The value or range of values for the filter.

Refer to How to Build Filters for a comprehensive guide on creating filters, including valid filter_type and value options.

Example Requests

Example 1: Find Senior Executives in Technology Companies

To find senior-level professionals in technology companies with more than 500 employees:

{
  "filters": [
    {
      "filter_type": "INDUSTRY",
      "type": "in",
      "value": ["Technology", "Information Technology and Services"]
    },
    {
      "filter_type": "COMPANY_HEADCOUNT",
      "type": "in",
      "value": ["501-1,000", "1,001-5,000", "5,001-10,000", "10,001+"]
    },
    {
      "filter_type": "SENIORITY_LEVEL",
      "type": "in",
      "value": ["CXO", "Vice President", "Director"]
    }
  ],
  "page": 1
}

Example 2: Locate Professionals with Specific Skills

To find professionals skilled in Machine Learning and Data Science:

{
  "filters": [
    {
      "filter_type": "KEYWORD",
      "type": "in",
      "value": ["Machine Learning"]
    },
    {
      "filter_type": "CURRENT_COMPANY",
      "type": "in",
      "value": ["Google", "Microsoft"]
    },
    {
      "filter_type": "CURRENT_TITLE",
      "type": "not in",
      "value": ["Software Engineer", "Data Scientist"]
    }
  ],
  "page": 1
}

Example 3: Search by Company and Title

To find people currently working at "Acme Corp" with the title "Marketing Manager":

{
  "filters": [
    {
      "filter_type": "CURRENT_COMPANY",
      "type": "in",
      "value": ["Acme Corp"]
    },
    {
      "filter_type": "CURRENT_TITLE",
      "type": "in",
      "value": ["Marketing Manager"]
    }
  ],
  "page": 1
}

Response

Successful Response (200 OK)

A successful response returns a JSON object containing:

• profiles: An array of professional profile objects matching your filters.
• total_display_count: The total number of results available for your query.

Example Response

{
  "profiles": [
    {
      "name": "Fiona Carney",
      "location": "Dublin, County Dublin, Ireland",
      "linkedin_profile_url": "https://www.linkedin.com/in/ACwAAAOVnpoBgQE7TIY1W_J1DNcnfDcM8loYbxU",
      "linkedin_profile_urn": "ACwAAAOVnpoBgQE7TIY1W_J1DNcnfDcM8loYbxU",
      "flagship_profile_url": "https://www.linkedin.com/in/fionacarney",
      "profile_picture_url": "https://media.licdn.com/dms/image/v2/D4E03AQELiK08u7SIGg/profile-displayphoto-shrink_400_400/0/1696959670867?e=1733961600&v=beta&t=2vWotWCukuZXTSCdh6xShxq6tBgvIM5qvGu7GPNWE-o",
      "headline": "COO at Microsoft EMEA | Diversity & Inclusion | Coach & Mentor | Board Member",
      "summary": "Currently I am COO for Microsoft EMEA...",
      "num_of_connections": 10369,
      "skills": [
        "Global Operations",
        "Team Management",
        "Stakeholder Management",
        // More skills...
      ],
      "employer": [
        {
          "title": "Chief Operating Officer, EMEA",
          "company_name": "Microsoft",
          "company_linkedin_id": "1035",
          "start_date": "2024-05-01T00:00:00",
          "end_date": null,
          "location": "EMEA, Ireland",
          "description": "Leading the regional team for Europe..."
        },
        // More employment history...
      ],
      "education_background": [
        {
          "degree_name": "Bachelor of Commerce (B.Comm)",
          "institute_name": "University College Dublin",
          "field_of_study": "Management",
          "start_date": "1993-01-01T00:00:00",
          "end_date": "1996-01-01T00:00:00"
        },
        // More education history...
      ],
      "current_title": "Chief Operating Officer, EMEA",
      "current_company": "Microsoft",
      "pronoun": "She/Her"
      // Additional profile fields...
    },
    // More professional profiles...
  ],
  "total_display_count": "78K+"
}

Error Response (400 Bad Request)

If your filters are invalid or there is an error processing your request, you will receive an error message:

{
  "error": "Failed to parse filters"
}

Key Things to Note

• Pagination: Each request returns up to 25 results. Use the page parameter to access additional results.
• Combining Filters: You can combine multiple filters to narrow down your search. Filters are combined using logical AND operations.
• Valid Values: Ensure you're using valid values for each filter_type. Refer to How to Build Filters for a comprehensive list of filter types and acceptable values.
• Filter Limitations: Some filters may not support certain operations (e.g., not in may not be supported for all filters). Check the filter documentation for details.
• Authentication: A valid Bearer token is required for all requests. Ensure your token has the necessary permissions.
• Data Privacy: Be mindful of data privacy regulations when handling personal data.

Additional Resources

• How to Build Filters: Detailed guide on creating filters for your queries.
• Data Dictionary: Comprehensive list of fields available in the ProfessionalProfile object, available here.