Retrieve InMail Stub Profiles

Article
09/20/2023

The InMail Stub Profile API allows you to retrieve basic profile data of LinkedIn members that have replied to InMails sent from Recruiter seat holders. When InMails are sent from Recruiter seatholders to members, the initial reply to that InMail asks the member if they would be willing to share their contact information with the Recruiter. On reply, if they elect to share, a subset of that member’s profile data (mailStub) will be retrievable with this API. The stub profile data can then be stored in your application database. If a member does not share their contact info, a mailStub will not be stored for the member.

All API requests require authorization . Additionally, API requests return paged results; details on paging through results can be found here.

Retrieve stub profiles for a contract:

GET https://api.linkedin.com/v2/mailStubs?q=contract

Query parameters

Field	Description	Format	Required	Notes
contract	The contract identifier	ContractUrn in format `urn:li:contract:{id}`	Yes	Find stub profiles associated with a specific Recruiter contract.
owners	The seat identifier	SeatUrn in format `urn:li:seat:{id}`	No	Find stub profiles associated with specific seat holders. Multiple allowed.
createdDateStart	Inclusive lower date boundary	Epoch in milliseconds (UTC)	No	Find stub profiles that were created on or after a specific date.
createdDateEnd	Non-inclusive upper date boundary	Epoch in milliseconds (UTC)	No	Find stub profiles that were created before or on a specific date.

Important

Even though 'owners' is not a required field, it should always be provided to avoid costly search operations at the LinkedIn backend.
Please make use of as much filtering criteria as possible.
For createdDateStart and createdDateEnd, if not specified we will search from all timespan.
The limit for hosted query search is 20000, if the query is trying to access the result more than 20000, api response will return an error with status code 500.

Sample Request

https://api.linkedin.com/v2/mailStubs?q=contract&contract=urn:li:contract:123456789&owners=urn:li:seat:123456789&createdDateStart=1486428734000&start=0&count=5

Response Body fields

Field	Description	Type	Required
firstName	First name of the member.	string	Yes
lastName	Last name of the member.	string	Yes
member	Unique id of the member within LinkedIn system.	PersonUrn in format `urn:li:person:{id}`	Yes
email	Prospect's email address at the time of sharing	string	No
phone	Prospect's phone number at the time of sharing	string	No
location	Location of the member (e.g. San Francisco Bay Area or Sunnyvale, California).	string	No
position	Prospect's position including title and company at the time of sharing.	string	No
seat	Seat to which the mail stub was shared.	SeatUrn in format `urn:li:seat:{id}`	Yes
createdAt	Created timestamp	Epoch in Milliseconds (UTC)	Yes
headline	Headline of the member.	string	No
profileUrl	URL of the member's public LinkedIn profile.	string	No

Sample Response

{
    "elements": [
    {
        "seat": "urn:li:seat:123456789",
        "createdAt": 1486428734000,
        "firstName": "firstName0",
        "lastName": "lastName0",
        "phone": {
            "number": "123-456-7890"
        },
        "member": "urn:li:person:a1b2c3d4e5",
        "location": "United States",
        "position": {
            "company": "LinkedIn",
            "title": "Software Engineer at LinkedIn"
        },
        "email": "test@linkedin.com"
    },
    {
        "seat": "urn:li:seat:123456789",
        "createdAt": 1526935559000,
        "firstName": "firstName1",
        "lastName": "lastName1",
        "member": "urn:li:person:a2b3c4d5"
    },
    {
        "seat": "urn:li:seat:123456789",
        "createdAt": 1526935559000,
        "firstName": "firstName2",
        "lastName": "lastName2",
        "member": "urn:li:person:a3b4c5d6"
    },
    {
        "seat": "urn:li:seat:123456789",
        "createdAt": 1526935559000,
        "firstName": "firstName3",
        "lastName": "lastName3",
        "member": "urn:li:person:a4b5c6d7"
    },
    {
        "seat": "urn:li:seat:123456789",
        "createdAt": 1526935559000,
        "firstName": "firstName4",
        "lastName": "lastName4",
        "member": "urn:li:person:a5b6c7d8"
    },
      ],
    "paging": {
        "count": 5,
        "start": 0
        "links": [
            {
                "rel": "next",
                "href": "/v2/mailStubs?contract=urn%3Ali%3Acontract%3A123456789&count=5&urn%3Ali%3Aseat%3A123456789q=contract&start=5",
                "type": "application/json"
            }
        ]
    }
}

Share via