Invitation API

The Invitation API allows your users to invite people they find in your application to their LinkedIn network. To send an invitation, you POST the invitation XML. You have control over the message subject and text and can invite people by email or member id.

The Invitations API is similar to what you find on LinkedIn.com but has one major difference. The API only supports inviting as a friend. We will add the other methods as soon as possible.

You can only invite one person per API call. To invite more than one person, issue multiple calls.

This call requires that you identify only the person being invited. The inviter will always come from the access token you use when you make the call. There are two methods of identifying the user being invited:

  • Member ID + auth token: If the invitee was found using a search API call, then the search result will have included the member ID and auth token to make the API call. Use both of those to identify the member to invite.
  • Email: For all other cases, you can use email address to identify the member to invite.

Once an invitation is posted, it cannot be removed or deleted.

Usage

  • You must use an access token to make an authenticated call on behalf of a user
  • You can only send invitations for the user who grants you access. The inviter is always the person represented in the access token.

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

Permission Description
w_messages Required to send messages and invitations as authenticated user

Throttle Limits
Please reference the limits applied to this API

Requirements

You must adhere to the following requirements when posting n invitation to LinkedIn:

  • The user must be given a choice about whether to send the invitation. The user must opt into the messages being sent rather than opt out.
  • The user must be given the opportunity to edit the invitation message text.
  • The message must come at or around the time the user invites.
  • You must only suggest sending invitations for the purpose of connecting users. Using invitations as a replacement for messaging is inappropriate use of the API. You should use the Messaging API for messages or provide a link back to LinkedIn.com.

URL

Fields for the XML Body

Node Parent Node Required? Value Notes
mailbox-item Yes Child nodes of mailbox-item Parent node for all message/invitation content
recipients mailbox-item Yes One recipient child node For the invitation API, only one recipient child node is allowed.
recipient mailbox-item/recipients Yes, 1 required A single person node, with a path attribute specified indicating the person to invite.
person recipient Yes, 1 required Must contain a path attribute describing the person being invited When inviting by email, should also contain child nodes containing the first and last name of the invitee. See the section on "person paths" below.
first-name recipient/person no A first name for the recipient must be specified when inviting by email.
last-name recipient/person no A last name for the recipient must be specified when inviting by email.
subject mailbox-item yes The string subject of the message that will be sent to the recipient. "Invitation to connect" is the standard text that LinkedIn uses. You are encouraged to use some similar text. No HTML allowed. Only UTF-8 characters permitted.
body mailbox-item yes A string text of the message. 200 character limit. No HTML allowed. Only UTF-8 characters permitted.
item-content mailbox-item yes Containing node for additional content in the invitation.
invitation-request mailbox-item/item-content yes Containing node for additional content specific to this invitation.
connection-type item-content/invitation-request yes Always "friend". Only connecting as a friend is supported presently. We will add more options soon.
authorization item-content/invitation-request Only when requesting by member id. Containing element for authorization headers found from Search results and Profile requests A valid authorization header must be supplied when inviting by member id.
name invitation-request/authorization Only required when requesting by member id. The name of the authorization header being supplied. From search results, this will likely be "NAME_SEARCH." Each profile returned will have an auth name and value.
value invitation-request/authorization Only required when requesting by member id. The value of the authorization header being supplied. Each profile returned will have an auth name and value.

Person Paths

The person element you embed within the recipient node should have a path attribute attached to it. "Person paths" are very similar to the resource paths you use to access member resources on LinkedIn. Imagine taking away everything in a simple API URL such that only the resource identifiers are left. If you were identifying a member by the email address user@domain.com, you refer to that as a resource with /people/email=user@domain.com.

For identifying members by id, you use the format /people/id=ABCD.

As a result, most of your "person paths" will look like this:

<person path="/people/id=ABCD" />
<person path="/people/email=user@domain.com">
  <first-name>Richard</first-name>
  <last-name>Brautigan</last-name>
</person>

Invite By Email Example XML Body

<?xml version='1.0' encoding='UTF-8'?>
<mailbox-item>
  <recipients>
    <recipient>
      <person path="/people/email=a_user@domain.com">
        <first-name>Richard</first-name>
        <last-name>Brautigan</last-name>
      </person>
    </recipient>
  </recipients>
  <subject>Invitation to Connect</subject>
  <body>Please join my professional network on LinkedIn.</body>
  <item-content>
    <invitation-request>
      <connect-type>friend</connect-type>
    </invitation-request>
  </item-content>
</mailbox-item>

Authorization Headers

When inviting by member id, you must include a name and value node under invitation-request/authorization. You can get these authorization codes from standard profile and search results.

If I had the following XML element attached to a person result from a Search API request:

<api-standard-profile-request>
  <url>https://api.linkedin.com/v1/people/T4sKMZ8qEN</url>
  <headers total="1">
    <http-header>
      <name>x-li-auth-token</name>
      <value>NAME_SEARCH:1Mlb</value>
    </http-header>
  </headers>
</api-standard-profile-request>

I would pluck out the api-standard-profile-request/headers/http-header/value node, then split the string on the colon (":") character. The value to the left of the column would be my authorization/name and the value on the right would be my authorization/value. I would then compile this into the following XML structure:

  <authorization>
    <name>NAME_SEARCH</name>
    <value>1Mlb</value>
  </authorization>

The XML example below shows how this fits within the overall structure of an invitation by member id.

Invite By Member Id Example XML Body

<?xml version='1.0' encoding='UTF-8'?>
<mailbox-item>
  <recipients>
    <recipient>
      <person path="/people/id=T4sKMZ8qEN" />
    </recipient>
  </recipients>
  <subject>Invitation to Connect</subject>
  <body>Please join my professional network on LinkedIn.</body>
  <item-content>
    <invitation-request>
      <connect-type>friend</connect-type>
      <authorization>
        <name>NAME_SEARCH</name>
        <value>1Mlb</value>
      </authorization>
    </invitation-request>
  </item-content>
</mailbox-item>

Example Messaging JSON POST Body

In this example, we are inviting someone using their ID and an authorization token.

{
  "recipients": {
    "values": [
    {
      "person": {
        "_path": "/people/12345",
       }
    }]
  },
  "subject": "Invitation to connect.",
  "body": "Say yes!",
  "item-content":{
       "invitation-request":{
           "connect-type":"friend",
           "authorization":{
              "name":"NAME_SEARCH",
              "value":"pXCC"}
           }
       }
    }

In this example, we are inviting someone using an email address.

{
  "recipients": {
    "values": [
    {
      "person": {
        "_path": "/people/email=a_user@domain.com"",
        "first-name":"Andrew",
        "last-name":"User"
       }
    }]
  },
  "subject": "Invitation to connect.",
  "body": "Say yes!",
  "item-content":{
       "invitation-request":{
           "connect-type":"friend"
       }
    }