Groups API
The Groups API provides rich access to read and interact with LinkedIn’s groups functionality. The API enables members to view and interact with groups off of LinkedIn.com with the same business rules that apply on the LinkedIn site. Data available includes group profile information, discussion posts, comments on posts, and likes.
Overview
Use the Groups API to:
- Retrieve a group's profile details
- Manage, join and retrieve information about a member's groups
- Retrieve and filter group discussion posts
- Read, Create, Like, Comment, Flag and Follow discussion posts
- Read, Create and Flag comments
- Retrieve suggested groups for a LinkedIn member
- Known Issues
Authentication
All groups capabilities require authentication through LinkedIn's OAuth 1.a or OAuth 2. Before an application can make an API call, it needs to establish an OAuth access grant between the user and the application. Members should be requested to log in and authenticate with LinkedIn and your application using LinkedIn’s
authentication flow.
Data Storage
Caching of LinkedIn data is not allowed, so API calls should be made on behalf of the member viewing data for every view instance or page refresh.
Display Requirements
When displaying group content, it should be made clear that the content is coming from a LinkedIn group.
- Ensure correct profile attribution to the poster or commenter, including their profile picture, first-name, last-name and headline.
- Ensure correct attribution to the group itself, including group logo, and group name.
- When displaying group posts, enable user actions including like, comment, and flag as inappropriate either through the API or through a link back to the post on linkedin.com.
- When displaying a LinkedIn member, group or post, provide a link back to the linkedin site instance of the object.
See the full set of legal requirements in LinkedIn’s Terms of Use and Platform Guidelines.
Group Resources and Standard Behavior
The Groups API introduces the following new resources into the LinkedIn REST API domain model. Each new resource has a unique identifying key.
| Resource | Key | Description |
|---|---|---|
| Group | Numeric group ID | The unique identifier for a LinkedIn group |
| Post | Post ID | The unique identifier for a LinkedIn post |
| Comment | Comment ID | The unique identifier for a LinkedIn comment within a group |
| Group-membership | groupid=<>&memberid=<> | The relationship between a member and a group |
The
Groups Domain Modellists all the fields available for each of these resources.
Field Selectors
Your application should only request the fields it needs when requesting data about resources. Ensure that your application does not rely on the default fields available; instead always specify the fields it needs and expects to receive using inline field selectors. For example:
You can also nest field selectors. For example:
Collections
A collection is a list of resources, with each resource instance accessible by its unique key. You can use a bulk collection lookup to specify multiple keys to look up in a single request.
Single key lookup:
/groups/12345
Multiple key lookup:
/posts::(1234,5678,9012)
Paginating Through Collections
You can write your application to paginate through groups, posts, comments, and group-memberships collections by index, using the start and count parameters. Collections referenced in field selectors can also be paginated using matrix parameters.
Note:Root collections do not have pagination support.
| Parameter | Description | Default Value |
|---|---|---|
| count | Number of records to return | Integer. Default depends on the resource, but is usually 5. |
| start | Record index at which to start pagination | Integer. Default is 0. |
Paginating Examples
Return 5 Group Memberships Starting at 0
Return 5 Group Posts Starting at 5
Advanced: Return the First 3 Posts of my First 3 Group Memberships
Note:The previous advanced example uses matrix parameters embedded inside of inline field selectors to paginate within selected fields.
Retrieving a Group's Profile Details
You can access details about one or more groups such as the ID, name, settings, and posts from any groups resource path. Some examples include:
Group Resource Full Field List
Input Values
| Parameter | Required | Definition |
|---|---|---|
| group-id | Y | The unique identifier for a group |
Group Memberships for a User
Use the group memberships resource to find the groups a member belongs to, to join groups and/or has requested to join.
Input Values
| Parameter | Required | Definition |
|---|---|---|
| group-id | N | The unique identifier for a group |
| person-id | Y | The unique identifier for a user |
Collection Filters
| Parameter | Description | Default Value |
|---|---|---|
| membership-state | The state of the caller’s membership to the specified group. Use the value member to retrieve the groups to which a user belongs. | Enum. Values are: non-member, awaiting-confirmation, awaiting-parent-group-confirmation, member, moderator, manager, owner. |
Group Membership Full Field List
Get Groups I am a Member Of
Show My Group Settings
Change My Group Settings
<group-membership>
<show-group-logo-in-profile>true</show-group-logo-in-profile>
<email-digest-frequency>
<code>daily</code>
</email-digest-frequency>
<email-announcements-from-managers>true</email-announcements-from-managers>
<allow-messages-from-members>true</allow-messages-from-members>
<email-for-every-new-post>true</email-for-every-new-post>
</group-membership>
Join a Group
Using the Groups API, it is possible to request to join any LinkedIn group that is listed in the LinkedIn.com Groups Directory. This can be achieved in one of two ways.
First, you can PUT a simple membership request via:
<group-membership>
<membership-state>
<code>member</code>
</membership-state>
</group-membership>
The second method involves POSTing additional group settings information with the request, which allows for more control over how the user interacts with the Group on LinkedIn.com. Normally, these settings would need to be adjusted by the user manually in the 'Your Settings' area for each group.
<group-membership>
<group>
<id>{group-id}</id>
</group>
<show-group-logo-in-profile>true</show-group-logo-in-profile>
<email-digest-frequency>
<code>daily</code>
</email-digest-frequency>
<email-announcements-from-managers>true</email-announcements-from-managers>
<allow-messages-from-members>true</allow-messages-from-members>
<email-for-every-new-post>false</email-for-every-new-post>
<membership-state>
<code>member</code>
</membership-state>
</group-membership>
Note: You can only join groups that are listed in the public directory via the Groups API. In the settings for your group, ensure that 'Display this group in the Groups Directory' is checked.
Leave a Group
Retrieving a Group's Discussion Posts
When the group ID is known, you can access all the posts for the group with optional filters. For example:
Input Values
| Parameter | Required | Definition |
|---|---|---|
| group-id | Y | The unique identifier for a group |
Collection Filters
| Parameter | Description | Default Value |
|---|---|---|
| start | Record index to start pagination. Supported for posts and post/comments. | Positive integer |
| count | Number of records to return. Supported for posts and post/comments. | Positive integer |
| order | Sort order for posts. | Enum. Valid for: recency, popularity |
| role | Filter for posts related to the caller. Valid only for group-memberships/{id}/posts resource. | Enum. Valid for: creator, commenter, follower |
| category | Category of posts. | Enum. Valid for: discussion |
| modified-since | Timestamp filter for posts created after the specified value. |
Show Latest Discussions for a Group Since a Timestamp
Show Most Popular Discussions for a Group
Show Posts a User has Started for a Group
Show Posts a User has Participated in for a Group
Show Posts a user is Following for a Group
Interacting with a Discussion Post
When your application needs to drill down into one or more posts directly, you can access the posts resource. The following examples show how to retrieve details about a post, and how to interact with a post.
Input Values
| Parameter | Required | Definition |
|---|---|---|
| post-id | Y | The unique identifier for a post |
Post Resource Full Field List
Paginate through all Comments of a Post
Create a new Post
<post> <title>Post Title</title> <summary>Post Summary</summary> </post>
JSON example:
{"title":"Post Title","summary":"Post Summary"}
Like/Unlike a Post
<is-liked>true</is-liked>
JSON Example:
true
<is-liked>false</is-liked>
JSON Example:
false
Follow/Unfollow a Post
<is-following>true</is-following>
JSON Example:
true
<is-following>false</is-following>
JSON Example:
false
Flag a Post as a Promotion or Job
<code>promotion</code>
<code>job</code>
Delete a Post or Flag as Inappropriate
If the actor is the creator or moderator, this deletes the post. If the actor is a member, this flags the post as inappropriate.
Interacting with Comments
When your application needs to drill down into one or more comments directly, you can access the comments resource. The following examples show how to retrieve details about a comment, and how to interact with a comment.
Input Values
| Parameter | Required | Definition |
|---|---|---|
| comment-id | Y | The unique identifier for a comment |
Comment Resource Full Field List
Add a Comment to a Post
<comment> <text>Comment text</text> </comment>
Delete a Comment or Flag as Inappropriate
If the actor is the creator or moderator, this deletes the comment. If the actor is a member, this flags the comment as inappropriate.
Suggested Groups for a LinkedIn Member
Get Suggested Groups for a User
Remove a Group Suggestion for a User
Known Issues
The following issues exist for the initial release. Workarounds are available.
- Comments pagination is inconsistent for bulk fetches of comments for multiple posts.
Workaround:Comments pagination works as expected for direct access through the root post resource. - The post.site-group-post-url parameter uses the incorrect domain.
Workaround:Replace api.linkedin.com with www.linkedin.com.