Share via

Handle Lookup API

  • Article

Note

The use of this API is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.

With the Handle Lookup API you can retrieve LinkedIn profile data via email handles.

Required HTTP Headers

For security reasons we require you to set the following HTTP headers when using the Handle Lookup API.

Header Sample Value Description
X-Forwarded-For 198.51.100.1 The client's IP address.  Will be different than the server IP address where a server makes calls on behalf of a client application.
Caller-Account-Age 2 An integer value between 0 and 5, representing account age "buckets". The bucket value is derived from: 0. "Younger than a day" : 0-86400 seconds, inclusive. 1. "Younger than a week" : 86401-604800 seconds, inclusive. 2. "Younger than a month" : 604801-2629800 seconds, inclusive. 3. "Younger than 6 months" : 2629801-15778800 seconds, inclusive. 4. "Younger than a year" : 15778801-31557600 seconds, inclusive. 5. "Older than a year" : Greater than 31557600 seconds.
Caller-Device-UUID   The client device's UUID.

Note

Per legal requirement, LinkedIn is not allowed to collect user's device UUID, but this API still requires to pass Caller-Device-UUID into the header to make the call succeed. Therefore you must not fill any real device UUID until LinkedIn remove Caller-Device-UUID completely.

For best usage of this API, we recommend caching the retrieved member's Person ID, and storing the association between LinkedIn Person ID and email address within your own service.  Once you've stored the member's ID, you can use the ID to retrieve that user's profile in a more efficient manner.

Get Person ID via Email Address

GET https://api.linkedin.com/v2/clientAwareMemberHandles?q=handleString&handleString={someone@email.com}

Sample Response

{
  "elements": [
    {
      "member": "urn:li:person:_zO6OFcZuz",
      "handle": "urn:li:emailAddress:3774955"
    }
  ],
  "paging": {
    "count": 10,
    "start": 0,
  }
}

Now that you have the corresponding LinkedIn member's unique identifier (their PersonURN), parse out the ID component of the full URN to get the Person ID.  The ID component is everything that appears after urn:li:person:.

In the example above, the Person ID is _zO6OFcZuz.

Once you have the Person ID, you can retrieve that member's profile using it as a primary key via the People API.

Note that you can also request handles for multiple email addresses at once via repeating the handleStrings parameter as such:

GET https://api.linkedin.com/v2/clientAwareMemberHandles?q=handleStrings&handleStrings={email1}&handleStrings={email2}

Combine Profile Data with Member Handles

The preferred pattern is to save the unique member identifier retrieved above and use it in all subsequent calls to retrieve LinkedIn profile data.

However, there may be times where you want to retrieve the profile data in the same call to Handle Lookup.  In this case, we offer a way to decorate the response above with the user's profile data via the projection query parameter.

Example:

GET https://api.linkedin.com/v2/clientAwareMemberHandles?q=handleString&handleString={someone@email.com}&projection=(elements*(member~))

Sample Response

{
  "elements":[
    {
      "member":"urn:li:person:5eeiv-3YgM",
      "member~":{
        "firstName":{
          "localized":{
            "en_US":"Arash"
          },
          "preferredLocale":{
            "country":"US",
            "language":"en"
          }
        },
        "headline":{
          "localized":{
            "en_US":"Partner Engineer, Consumer and Strategic Partnerships at LinkedIn"
          },
          "preferredLocale":{
            "country":"US",
            "language":"en"
          }
        },
        "localizedFirstName":"Arash"
      },
      ...
    }
  ]
}