Invitations API

  • Article

Note

Usage of this API is restricted to approved partners, subject to limitations via API agreement.

With the Invitations API, you can replicate the full LinkedIn experience around connecting LinkedIn members to each other.

Creating Invitations

Sending an Invitation

Send an invitation by issuing a POST that specifies the URN of the LinkedIn member that the invite will be sent to. You can only send invites on behalf of the authenticated user.

POST https://api.linkedin.com/v2/invitations

Request Body Fields

Field Description Format Required
invitee The URN of the person to send the invite to. Can be one of the following URN format:
  • Person - urn:li:person:{personID}
  • Email - urn:li:emailAddress:{emailID}
  • Phone - urn:li:phoneAccount:{phoneAccountID}
  • Raw email - urn:li:email:{raw email string}
 Urn Yes
message. com.linkedin.invitations.InvitationMessage. body The body of the invitation message. Omit to send the default message. String No

Sample request body

{
    "invitee": "urn:li:email:test@linkedin.com",
    "message": {
        "com.linkedin.invitations.InvitationMessage": {
            "body": "Let's connect!"
        }
    }
}

Sample Response Header

x-linkedin-id: urn:li:invitation:617608454596123456

Retrieving Invitations

Once an invitation has been created, you can retrieve that invitation to check on it's status. For example, the invitation may be accepted or rejected. You can also retrieve a list of invitations sent out by the authenticated user, as well as a list of invitations they have received.

Retrieving an Invitation by Invitation URN

Once you have an Invitation's unique identifier, you can retrieve information on its current state.

GET  https://api.linkedin.com/v2/invitations/{invitation Urn}

sample invitation response

{
    "created": 1484671788434,
    "id": "urn:li:invitation:6227164820370661376",
    "invitee": "urn:li:person:RYZMZJHEsz",
    "inviter": "urn:li:person:Ylpq-RobP9",
    "lastModified": 1484672192563,
    "message": {
        "com.linkedin.invitations.InvitationMessage": {
            "body": "Connect with me!"
        }
    },
    "sentAt": 1484671817742,
    "state": "ACCEPTED",
    "validationToken": "viUrSCUs"
}

For more information, refer to the Invitation schema.

Using parameters to search for multiple matching Invitations

You can retrieve a list of invitations that match certain search criteria. Common use cases would be:

  • Find invites sent within a certain time range
  • Find invites that are in a certain state (pending, accepted, rejected, etc.)
  • Whether the invite had a custom message vs. default message

Please see below for the available APIs and their parameters.

Retrieving Invitations the user received

You can retrieve a list of invitations the authenticated user has received from other LinkedIn members.

GET https://api.linkedin.com/v2/invitations?q=invitee&states=PENDING

Query Parameters

Field Description Format Required
timeFrame The time range to constrain the search to. Filters based on the invitation create time. see below No
timeFrame.start Represents the inclusive (greater than or equal to) value in which to start the range. Long No
timeFrame.end Represents the exclusive (strictly less than) value in which to end the range. Long No
state The list of states to constrain the search to. Valid states are:
  • UNSENT
  • ABORTED
  • PENDING
  • BOUNCED
  • ACCEPTED
  • IGNORED
  • REJECTED
  • WITHDRAWN
  • EXPIRED
  • BLOCKED
 String[] No
hasCustomizedMessage Whether the invite had a custom message or the default message. Boolean No
inviters Inviters for whom you want to retrieve the invitation data sent from. PersonURN[] No

Retrieving Invitations the user sent

You can retrieve a list of invitations the authenticated user has sent to other users.

GET https://api.linkedin.com/v2/invitations?q=inviter&states=ACCEPTED

Query Parameters

Field Description Format Required
timeFrame The time range to constrain the search to. Filters based on the invitation create time. see below No
timeFrame.start Represents the inclusive (greater than or equal to) value in which to start the range. Long No
timeFrame.end Represents the exclusive (strictly less than) value in which to end the range. Long No
state The list of states to constrain the search to. Valid states are:
  • UNSENT
  • ABORTED
  • PENDING
  • BOUNCED
  • ACCEPTED
  • IGNORED
  • REJECTED
  • WITHDRAWN
  • EXPIRED
  • BLOCKED
 String[] No
sources The filter to select the invitations from specified source types. Valid types are:
  • ABI - The invitation is contributed by Address-Book-Import workflow.
  • PYMK - The invitation is contributed by People-You-May-Know workflow.
  • PROFILE - The invitation comes from direct profile view.
  • OTHER - The invitation comes from all other sources except the specified ones.
 String[] No
invitees Invitees for whom you want to retrieve the invitation data sent to. PersonURN[] No
invitations The list of invitation URNs that are of interest. InvitationURN[] No

Sample finder response

{
  "elements": [
    {
      "validationToken": "gFulHMKt",
      "created": 1485388767467,
      "inviter": "urn:li:person:Ylpq-RobP9",
      "id": "urn:li:invitation:6230172048157614080",
      "state": "PENDING",
      "lastModified": 1485388791605,
      "sentAt": 1485388791605,
      "message": {
        "string": "invite_member_28"
      },
      "invitee": "urn:li:person:RT7VAAk2nr"
    },
    {
      "validationToken": "54aKoD6Q",
      "created": 1485379397914,
      "inviter": "urn:li:person:Ylpq-RobP9",
      "id": "urn:li:invitation:6230132749475291136",
      "state": "PENDING",
      "lastModified": 1485379412806,
      "sentAt": 1485379412806,
      "message": {
        "com.linkedin.invitations.InvitationMessage": {
          "body": "Connect with me!"
        }
      },
      "invitee": "urn:li:person:r5GpfvpA3t"
    },
    ...
  ],
  "paging": {
    "total": 5,
    "count": 10,
    "start": 0
  }
}

Taking Action Upon an Invitation

Once an Invitation has been created, you can then take action upon it. The most common use cases would be to accept or reject an invitation, rescind a sent invitation, etc. A full list of actions that can be taken are listed below.

Accepting an Invitation the user received

By setting the inviteeActionType field to one of the states above, you can take actions on an invitation the user has received. The available actionTypes are ACCEPT, IGNORE, REJECT, and REPORT_SPAM. The required request fields are invitationId, validationToken, and inviteeActionType.

POST https://api.linkedin.com/v2/invitations?action=inviteeClosingInvitation

request body

{
  "inviteActionData": [
    {
      "invitationId": "urn:li:invitation:6148971681877606400",
      "validationToken": "ABC123"
    }
  ],
  "inviteeActionType": "ACCEPT"
}

Withdrawing an Invitation the user has sent

By setting the inviterActionType field to one of the states above, you can take actions on an invitation the user has received. The available actionTypes are WITHDRAW, and ABORT. The required request fields are invitationId and inviterActionType.

POST https://api.linkedin.com/v2/invitations?action=inviterClosingInvitation

request body

{
  "inviteActionData": [
    {
      "invitationId": "urn:li:invitation:6148971681877606400"
    }
  ],
  "inviterActionType": "WITHDRAW"
}

Resolving Inviter and Invitee URNs

As you might have noticed, inviter and invitee both return URNs and can be the following types:

  • Person - urn:li:person:{person ID}
  • Email - urn:li:emailAddress:{email ID}
  • Phone - urn:li:phoneAccount:{phoneAccount ID}
  • Raw email - urn:li:email:{raw email string}

This URNs can be resolved by our projection concept. See below for examples of how these URNs are easily decorated to contain more information without making additional calls:

GET https://api.linkedin.com/v2/invitations//urn:li:invitation:123456789?projection=(created,inviter~person(firstName,lastName,headline)~emailAddress(emailAddress)~phoneAccount(phoneNumber),id,state,lastModified,sentAt,message,invitee~person(firstName,lastName,headline)~emailAddress(emailAddress)~phoneAccount(phoneNumber))

response body

{
    "created": 1487769180000,
    "id": "urn:li:invitation:6240156200003072",
    "invitee": "urn:li:emailAddress:6368071366",
    "invitee~": {
        "emailAddress": "bob-smith@linkedin.com"
    },
    "inviter": "urn:li:person:TejNUSGAB1",
    "inviter~": {
        "firstName": {
            "localized": {
                "en_US": "John"
            },
            "preferredLocale": {
                "country": "US",
                "language": "en"
            }
        },
        "headline": {
            "localized": {
                "en_US": "Software Engineer at LinkedIn"
            },
            "preferredLocale": {
                "country": "US",
                "language": "en"
            }
        },
        "lastName": {
            "localized": {
                "en_US": "Smith"
            },
            "preferredLocale": {
                "country": "US",
                "language": "en"
            }
        }
    },
    "lastModified": 1487769180000,
    "message": {
        "string": "invite_guest"
    },
    "sentAt": 1487769180760,
    "state": "SENT"
}

As you can see, the projection parameter not only provides ability to do field selection but also a way to retrieve more information on URNs. The syntax is done so by doing ~(field1,field2,field3). In addition, if it's a generic URN, the correct way is to identify what you want for each URN type, hence the ~person(firstName,lastName,headline) ~emailAddress(emailAddress)~phoneAccount(phoneNumber). If you wanted more fields from each URN, you just have to specify more. For example, ~person(firstName,positions).

Note

For now, phoneAccountUrn will not resolve. It is still under development.

Below is an example for the FINDER invitee :

GET https://api.linkedin.com/v2/invitations?q=inviter&count=100&projection=(elements*(created,inviter~person(firstName,lastName,headline)~emailAddress(emailAddress)~phoneAccount(phoneNumber),id,state,lastModified,sentAt,message,invitee~person(firstName,lastName,headline)~emailAddress(emailAddress)~phoneAccount(phoneNumber)))

response body

{
  "elements": [
    {
      "invitee~": {
        "emailAddress": "bob-smith@linkedin.com"
      },
      "created": 1487769180000,
      "inviter~": {
        "firstName": {
          "localized": {
            "en_US": "John"
          },
          "preferredLocale": {
            "country": "US",
            "language": "en"
          }
        },
        "lastName": {
          "localized": {
            "en_US": "Smith"
          },
          "preferredLocale": {
            "country": "US",
            "language": "en"
          }
        },
        "headline": {
          "localized": {
            "en_US": "Software Engineer at LinkedIn"
          },
          "preferredLocale": {
            "country": "US",
            "language": "en"
          }
        }
      },
      "inviter": "urn:li:person:TejNUSGAB1",
      "id": "urn:li:invitation:6240156200003072",
      "state": "SENT",
      "lastModified": 1487769180000,
      "sentAt": 1487769180760,
      "message": {
        "string": "invite_guest"
      },
      "invitee": "urn:li:emailAddress:6368071366"
    },
    ...
  ]
}

You will notice the only difference is the elements*. This is because all FINDERs will return a collection of results grouped in elements. The * syntax represents an array and will decorate all the objects in that array.