bannerColor WARNING_YELLOW templateName stackForums

People Search API

The People Search API returns information about people. It lets you implement most of what shows up when you do a search for "People" in the top right box on LinkedIn.com.

People Search API is a part of our Vetted API Access Program. You must apply here and get LinkedIn's approval before using this API.

  • It may not be used for the purposes of database matching, candidate sourcing, or lead generation without an established business relationship with LinkedIn. For information on partnership opportunities, and how to apply, visit our Partner Programs page.
  • You can never store data returned from the People Search API.
  • Search results may not be stored or offered as aggregated search.
  • All API calls must be made within an active user session.
  • You cannot let multiple people search using the authentication credentials of one person. Each person must authenticate individually.
  • If you have questions, see our Platform Guidelines for more information.

Hacker Summary

Usage

Permissions
This API requires the following permissions (see Member Permissions)

Permissions Description
r_network Required to successfully complete a people search

Throttle Limits
Please reference the limits applied to this API

Overview

Use the People Search API to find people using keywords, company, name, or other criteria. It returns a list of matching member profiles. Each entry can contain much of the information available on the person's member profile page.

The API can also return facets. Facets provide you with data about the collection of people, such as where they work, are located, or what schools they attended. You can then use this data to make a new API call that further refines your original request. This is similar to clicking the buttons on the left-hand side of the LinkedIn Search results page.

Here are a few examples showing how to use the basics of the People Search API:

By default, we return a list of all people in the member's network:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<people-search>
<people total="100" count="10" start="0">
<person>
<id>tePXJ3SX1o</id>
<first-name>Clair</first-name>
<last-name>Standish</last-name>
</person>
<person>
<id>pcfBxmL_Vv</id>
<first-name>John</first-name>
<last-name>Bender</last-name>
</person>
...
</people>
<num-results>108</num-results>
</people-search>

Refine your search by providing query parameters, such as keywords, first-name, last-name, and school-name:

Be sure to URL encode the parameter values in the URL. That's why Shermer High School is Shermer%20High%20School and Tim O'Reilly is Tim%20O%5CReilly.

Combine multiple parameters to find people that match all values:

These values are case insensitive. Bill, bill, and BILL are considered the same. Multiple values within a parameter are ANDed, not ORed. The one exception is keywords, which uses an algorithm to return the best set of results based on the keywords passed. If you have a full name, such as Andrew Clark, and don't know how to best split it into first-name and last-name fields, pass it in as a keyword instead.

By default, we return a very minimal set of fields: the person's id, along with their first and last names. To receive additional information, use our Field Selector syntax of :(field1, field2, ..., fieldN)

This URL returns the identical set of information, but explictly enumerates the return values using Field Selectors:

Field Selectors can be nested. At the top-level, you ask for people and num-results. Inside people, you ask for id, first-name, and last-name.

Alternatively, to also return the URL of a profile photo, and headline, add those fields:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<people-search>
<people total="108" count="10" start="0">
<person>
<id>tePXJ3SX1o</id>
<first-name>Bill</first-name>
<last-name>Doe</last-name>
<headline>Marketing Professional and Matchmaker</headline>
<picture-url>
https://media.linkedin.com:/....</picture-url>
</person>
<person>
<id>pcfBxmL_Vv</id>
<first-name>Ed</first-name>
<last-name>Harris</last-name>
<headline>Chief Executive Officer</headline>
</person>
...
</people>
<num-results>108</num-results>
</people-search>

Notice that the second person, Ed Harris, doesn't have a <picture-url> element. That's because he didn't provide a photo. In general, you should not assume that all elements you ask for will be returned.

Full information about Field Selectors is covered in a separate document.

Sort results using the sort parameter:

Paginate results using the start and count parameters:

This lets you walk through the result set 5 entries at a time. The first entry is at start=0 and the final one is at the value of the total attribute of the people element - 1. In the above example, total is 100, so the results go from 0 to 99. The maximum number of results per response is 25. The total number of search results possible for any search will vary depending on the user's account level.

Information on using facet types and bucket values is below.

Finally, it is important to distinguish between the top-level num-results element and the total attribute of the people element. These values are often the same, but they are not duplicates. The num-results element is the full count of entries in the member's network that match the search query. This number can be quite large. The total attribute is the number of results the member is allowed to retrieve and view. This number can vary depending on the member's account status or other factors. So, you should not make any assumptions about the value. The total attribute will always be equal to or less than num-results.

The People Search API can also include links to view the profile on linkedin.com or get the profile in an API call. Use the URL we return to see profiles found in search rather than constructing a URL yourself. There is a visibility token embedded in the URL we return to ensure your user sees the maximum set of profile information. Without those, your user may not see the full profile details or, in some cases, may not be able to see the profile at all.

Input Values

Unless otherwise specified:

  • All input is case insensitive.
  • Multiple words should be joined using a space. Since you need to URL encode input, this translates to %20. For example, Andrew%20Clark.
  • When you pass in multiple words, we search for all words in the string without regard to the order in which they are passed in. In keywords this means the words can appear in any of the fields searched.
  • Wildcards and boolean logic isn't supported (e.g. *, ?, AND, and OR).
  • When you want to search for either of two terms, use facets. To find all people in the United States or France, you cannot do country-code=us,fr; instead, you need to do facet=location,us:0,fr:0.
  • To get search results outside the network (aka not either 1st or 2nd degree connections) of the authenticated user who is performing the search, you must provide a first and last name. Searches not providing first and last name have results limited to the member's immediate network only.
Parameter Required Definition
keywords N

Members who have all the keywords anywhere in their profile. Use this field when you don't know how to more accurately map the input to a more specific parameter. (Don't forget to URL encode this data.)

first-name N

Members with a matching first name. Matches must be exact. Multiple words should be separated by a space.

last-name N

Members with a matching last name. Matches must be exactly. Multiple words should be separated by a space.

company-name N

Members who have a matching company name on their profile. company-name can be combined with the current-company parameter to specifies whether the person is or is not still working at the company.

It's often valuable to not be too specific with the company name. LinkedIn has made great efforts at standardizing company names, but including suffixes such as "Inc" and "Company" may overly limit your search, missing people who did not include those suffixes on their company names. It's usually better to  search for the basic name of the company and all different versions will be returned. This does increase the possibility of a false positive match return, though, so consider the most specific terms you can use. For example, consider using "Acme" instead of "Acme, Inc" to find people from a company called Acme, Inc. But this runs the risk of finding people from different companies with Acme in the title, such as "Acme Vending" and "Acme Services".

current-company N

Valid values are true or false. A value of true matches members who currently work at the company specified in the company-name parameter. A value of false matches members who once worked at the company. Omitting the parameter matches members who currently or once worked the company.

title N

Matches members with that title on their profile. Works with the current-title parameter.

current-title N

Valid values are true or false. A value of true matches members whose title is currently the one specified in the title-name parameter. A value of false matches members who once had that title. Omitting the parameter matches members who currently or once had that title.

school-name N

Members who have a matching school name on their profile. school-name can be combined with the current-school parameter to specifies whether the person is or is not still at the school.

It's often valuable to not be too specific with the school name. The same explation provided with company name applies: "Yale" vs. "Yale University".

current-school N

Valid values are true or false. A value of true matches members who currently attend the school specified in the school-name parameter. A value of false matches members who once attended the school. Omitting the parameter matches members who currently or once attended the school.

country-code N Matches members with a location in a specific country. Values are defined in by ISO 3166 standard. Country codes must be in all lower case.
postal-code N

Matches members centered around a Postal Code. Must be combined with the country-code parameter. Not supported for all countries.

distance N

Matches members within a distance from a central point. This is measured in miles. This is best used in combination with both country-code and postal-code.

facet N

Facet values to search over. Full information is below.

facets N

Facet buckets to return. Full information is below.

start N

Start location within the result set for paginated returns. This is the zero-based ordinal number of the search return, not the number of the page. To see the second page of 10 results per page, specify 10, not 1. Ranges are specified with a starting index and a number of results (count) to return. The default value is 0.

count N The number of profiles to return. Values can range between 0 and 25. The default value is 10. The total results available to any user depends on their account level.
sort N

Controls the search result order. There are four options:

  • connections: Number of connections per person, from largest to smallest.
  • recommenders: Number of recommendations per person, from largest to smallest.
  • distance: Degree of separation within the member's network, from first degree, then second degree, and then all others mixed together, including third degree and out-of-network.
  • relevance: Relevance of results based on the query, from most to least relevant.

By default, results are ordered by the number of connections.

Facets

Facets provide you with data similar to what appears on left-hand side of the LinkedIn Search results page.

Use facets to discover for a member:

  • Who in their network works at a specific company, or group of companies.
  • How the people their network cluster together. What locations or industries are the most popular?
  • Where their connections graduated from school.

Two blog posts explains how faceted search works the LinkedIn website and why we introduced these changes. The first covers the features; the second covers the design process. They're worth a read if you're unfamiliar with the product.

There are many facet types. Use these values to both receive a bucketed histogram of information about a type and also to filter your search query based on that data.

To retrieve facet histograms, specify both the list of facets you want to retrieve and fields you want for each facet:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<people-search>
<facets total="1">
<facet>
<name>Location</name>
<code>location</code>
<buckets total="5">
<bucket>
<name>United States</name>
<code>us:0</code>
</bucket>
<bucket>
<name>San Francisco Bay Area</name>
<code>us:84</code>
</bucket>
<bucket>
<name>France</name>
<code>fr:0</code>
</bucket>
...
</buckets>
</facet>
</facets>
</people-search>

Here you see the location breakdown of the people in your search. The text inside the name elements is meant for humans to read. The text inside the code elements is meant for machines to process, and that is the data you should pass us when referring to specific facets and facet values.

Note: If you want to retrieve both people and facets, you must explicitly provide a list of people and facet field selectors. Just asking for facets will override the default set of field selectors of people id, first-name, last-name, and num-results. For example, https://api.linkedin.com/v1/people-search:(people, facets:(code,buckets:(code))).

Further refine results by passing a facet parameter with a value of the facet code and facet bucket code separated by a comma (,). For example, to filter results to only return people with a location of the San Francisco Bay Area:

Find people in multiple facet buckets by appending additional bucket codes to the end of the parameter. So, this query finds people in the San Francisco Bay Area or France:

Combining multiple facets together gives you all people who are in the intersection of all buckets.

For example, to identify all 1st degree connections living in the San Francisco Bay Area:

To recap: within a single facet, multiple buckets are ORed; across multiple facets, the results are ANDed.

Reminder: Don't forget to URL encode the parameter values. For example, location,us:84 is location%2Cus%3A84.

Here is a list of all facet types. When possible, we have provided a list of potential values. However, when the facet accepts a large set of values (and those values are contantly being updated), then you will only be able to get the data by programmatically inspecting the results of your calls to this API. We do not have a facet metadata APIs at this time.

Values not listed below are unlikely to change, so once you find a value, you should be able to cache it. But we make no promises at this time. Sorry.

Parameter Definition Values
location

A geographical region. This is not necessarily a country. It could be a city or regional area, such as San Francisco Bay Area

A geographical code, such as us:84 for San Francisco Bay Area or fr:0 for France.

industry

An industry field.

Industry values are listed on a separate page.
network

A specific relationship to the member's social network:

There are four values

  • F: First degree connections
  • S: Second degree connections
  • A: Inside one of your groups
  • O: Out-of-network connections

Note: To return results from Groups (A) or Out-of-network connections (O), you must provide both the first-name and last-name parameters.

language

A member locale set to a specific language:

There are seven values

  • en: English
  • es: Spanish
  • fr: French
  • de: German
  • it: Italian
  • pt: Portuguese
  • _o: Others
current-company

A member's current companies.

A company ID, such as 1006 for NASA or 1028 for Oracle.

past-company

Same as current-company.

Same as current-company.

school

A members current or previous school.

Similar behavior as current-company, but with different values.

This is the full set of Facet fields available via Field Selectors.

Field Parent Node Description Values
name facet A human readable name for the facet. For example, Location or Network. This could change based on locale. (In other words, we might translate this term.)
code facet The machine processable value for the facet. For example, location or network. This is contant across all locals.
buckets facet The facet bucket values for the facet. Container element for the next four items.
name buckets A human readable name for the facet bucket. For example, San Francisco Bay Area or 1st Connections
code buckets The machine processable value for the bucket. For example, us:84 or F.
count buckets The number of results inside the bucket. A non-negative integer. (In other words, a number between 0 and max-results.)
selected buckets If this bucket's results are included in your search query. Values are true and false.

Migrating from Search API v1

While the new API offers more features, it is not 100% backwards compatible with the original People API. Here is a handy migration guide:

Old New
The default return fields are different. Before, you could do: /people?query and get a bunch of data about a person.

Use Field Selectors to explicitly enumerate the exact fields you want. This ensures the call returns in the least amount of time.

As a starting point, the People API default looked like this: /people-search:(people:(id,first-name,last-name,headline,location:(name,country:(code),postal-code),industry,num-recommenders,connections,summary,specialties,interests,honors,positions,educations,member-url-resources,api-standard-profile-request,site-standard-profile-request,public-profile-url))?query

name=firstname%20lastname

If you can properly split the name, use first-name=firstname and last-name=lastname. Otherwise, use keywords=firstname%20lastname. (This assumes you are already URL encoding firstname and lastname.)

company=name company-name=name
industry-code=code1[&industry-code=code2&...&industry-code=codeN]

Use facet=industry-code,code1[,code2...,codeN].

network=[in|out]

For in, use facet=network,F,S,A. For out, use facet=network,O.

sort=ctx|endorsers|distance|relevance

Two values, ctx and endorsers, are now connections and recommenders.

search-location-type

Unnecessary. Automatically detected if you do a geographical search.

Restrictive filters only. Restrictive and hierarchal filters.

Sample Output XML

Here is a sample return document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<people-search>
<num-results></num-results>
<people total="">
<person>
<id></id>
<first-name></first-name>
<last-name></last-name>
<headline></headline>
<location>
<name></name>
<country>
<code></code>
</country>
</location>
<industry></industry>
<num-recommenders></num-recommenders>
<connections total="" />
<positions total="">
<position>
<id></id>
<start-date>
<year></year>
<month></month>
</start-date>
<is-current></is-current>
<company>
</company>
</position>
...
</positions>
<site-standard-profile-request>
<url></url>
</site-standard-profile-request>
</person>
...
</people>
<facets total="">
<facet>
<code></code>
<name></name>
<buckets total="">
<bucket>
<code></code>
<name></name>
<count></count>
<selected></selected>
</bucket>
...
</buckets>
</facet>
...
</facets>
</people-search>