Primary Contact API

Note

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

The Primary Contact API returns an authenticated member's primary handles. A handle represents the contact information that the authenticated member provided to LinkedIn and can be an email or a phone number"

Usage

You must use an access token to make an authenticated call on behalf of a user.

Permissions

This API requires one of the following permissions:

Permission	Description
r_emailaddress	Retrieve primary email address on the authenticated user's behalf.
r_primarycontact	Retrieve primary authenticated member handles (email or phone number) on the authenticated user's behalf.

Note

These two permissions are mutually exclusive, you should only include one permission in the "scope" field while requesting access token. If your app only requires email address, you should specify r_emailaddress. And if your app requires email address or phone number, you should replace r_emailaddress with r_primarycontact.

Retrieve Primary Contact

To query for an authenticated member's primary contact information, you can use the sample request below. Make sure your request has the appropriate authentication.

GET https://api.linkedin.com/v2/clientAwareMemberHandles?q=members&projection=(elements*(primary,type,handle~))

Note

The query parameter "q=members" is always required, called Finder members in v2 APIs and represents querying by members to find their associated handles. The "projection" parameter customizes the response you are expecting the API to return. Please check 'Request Methods' and 'Projections' sections at out v2 API Concepts page for more details.

Retrieve Email Address

To query an authenticated member's primary email address:

GET https://api.linkedin.com/v2/clientAwareMemberHandles?q=members&projection=(elements*(primary,type,handle~))

Note

The API call would return empty response body if the authenticated user was registered via phone number, and never added any primary email address into their LinkedIn account previously. The value of type is case sensitive, and can only be EMAIL in this case.

Response Body

The response will be in JSON and always include the field elements that contains an array of handles belonging to the authenticated member. A handle can be either an email or a phone number, differentiated by type . An authenticated member is only required to have one primary handle of either type. Therefore, the response can return either one email address, one phone number or both. If an authenticated member has no primary handle, then the response code will still be 200 and the elements array will be empty.

Response Field	Type	Description
primary	Boolean	Indicates if the handle is primary or not.
type	String	Represents the type of handle. It can be either: EMAIL PHONE
handle	URN	Represents either a emailAddress or phoneNumber URN. When decorated with ~, it will return with one of the formats: {"emailAddress" : "ding_wei_stub@example.com"} {"phoneNumber" : { "number": "158****1473" }} The phone number will be partially obfuscated.

sample response

{
    "elements": [
        {
            "handle": "urn:li:emailAddress:3775708763",
            "handle~": {
                "emailAddress": "ding_wei_stub@example.com"
            },
            "primary": true,
            "type": "EMAIL"
        },
        {
            "handle": "urn:li:phoneNumber:6146249836070047744",
            "handle~": {
                "phoneNumber": {
                    "number": "158****1473"
                }
            },
            "primary": true,
            "type": "PHONE"
        }
    ]
}

Note

If a decoration succeeds, it will contain ~ in the field (ie. handle~ . fails. If it fails, it will contain ! (ie. handle! ). See below for example.

sample decoration error

"handle!": {
  "message": "URN Resolution failed for unknown reasons.",
  "status": 500
}