Share via

Live Events APIs

  • Article

Overview

Use the Live Events API to stream and manage Live Events with your LinkedIn network. The Live Events API offers the following functionality:

  1. Register the Live Event.
  2. Ingest RTMP(s) content.
  3. Create a Post to share your Live Event with your LinkedIn network.
  4. End the Live Event.
  5. Check the Live Event status.

Getting Started

Authenticating Members

New members authenticating with your developer application for the first time will need to follow the Authenticating with OAuth 2.0 Guide. When requesting an authorization code in Step 2 of the OAuth 2.0 Guide, make sure to request the minimum set of permission scopes required for your use case.

Note

Before authenticating with OAuth 2.0, determine if your use case permits creating live events for the member, or a company page. Combining both member and company page permission scopes within a single authentication request is not permitted.

Note

LinkedIn Live is currently a beta feature. As a broadcaster, to apply for access see Applying for Live Events Broadcasting.

Member Live Events

Permission Name Description
r_member_live READ access to a member's live events. This permission scope allows you to check the status of your Live Event, as well as retrieve the Live Event playable streams.
w_member_live WRITE access to a member's live events. This permission scope allows you to upload and manage your Live Event.
r_liteprofile READ access to a member's lite profile. This permission scope permits access to retrieve the user's ID via the Profile API.

Company Page Live Events

Permission Name Description
r_organization_live READ access to your organization's live events. This permission scope allows you to check the status of your Live Event, as well as retrieve the Live Event playable streams.
w_organization_live WRITE access to your organization's live evends. This permission scope allows you to upload and manage your Live Events.
r_organization_admin READ access to a member's organization or company page. This permission scope permits access to retrieve the organization ID via the Organization Access Control API.

Tiering

The Live Events API Program is available in two tiers: Development and Standard Tiers. The intent of the Development Tier is to introduce Developers to Live Events APIs, giving you limited access to create and view Live Events on LinkedIn. A prerequisite to requesting access to the Standard Tier will require a demonstration from your platform, showcasing each of the Live Events certification test cases. Access to both the Development and Standard Tiers are available through managing your developer applications Products at developer.linkedin.com.

Development Tier

The Developement Tier contains access to all APIs and services of the full Standard Tier, with a restriction on the total number of API calls your developer application can request within a 24 hour period. Generally, each Live Events API is limited to 100 API requests per day -- giving you the freedom to test and develop against LinkedIn APIs for your developer application. The intent of the Development Tier is to give you a preview of the Live Events Program, and to demonstrate your proficiency in integrating with LinkedIn before being elevated to the Standard Tier.

Standard Tier

When you are ready to launch your LinkedIn Live Events integration to your broadcasters, you must request access to the Standard Tier. We will take this time to review your integration with LinkedIn, and require a demonstration video showcasing your fulfillment of our Certification Test Cases.

Register

Register your Live Event using the liveAssetActions API with the action query parameter to register.

Note

Newly registered Live Events will be discarded if ingestion has not started within 1 hour. After ingestion has started, a timeout will occur if the ingest URL has not received any data within 120 seconds.

Field Name Type Description
owner Person or Organization URN The unique identifier of the member or organization registering the asset. To identify your Person URN, use the Lite Profile API and append the ID returned to "urn:li:person:".
To identify your Organization URN, use the Organization Access Control API. You must be the Administrator of your Organization in order to post to your Organization Page.
recipes AssetRecipe Defines the asset media type. The live event asset media type is always urn:li:digitalmediaRecipe:feedshare-live-video.
region string The region specifies the closest region your asset should be registered to. Possible values include:
1. WEST_US (West US)
2. EAST_US_NORTH (Northeastern US)
3. EAST_US_SOUTH (Southeastern US)
4. CENTRAL_US (Central US)
5. SOUTH_CENTRAL_US (South Central US)
6. SOUTH_AMERICA (South America)
7. NORTH_EUROPE (North Europe)
8. WEST_EUROPE (West Europe)
autoCaptionLanguageTag string (optional) The BCP-47 language tag of the auto captions to generated for the live event. Use "en-US" for English. Remove this parameter if you do not want auto captions added.

Tip

Use decoration syntax to retrieve the Person ID within a single request. GET https://api.linkedin.com/v2/me?projection=(id)

Tip

Use decoration syntax to retrieve the Organization URN within a single request. https://api.linkedin.com/v2/organizationAcls?q=roleAssignee&projection=(elements*(organization~))

API Request

POST https://api.linkedin.com/v2/liveAssetActions?action=register

Sample Request Body

{
    "registerLiveEventRequest": {
        "owner": "urn:li:person:12345",
        "recipes": ["urn:li:digitalmediaRecipe:feedshare-live-video"],
        "region": "WEST_US"
    }
}

A successful response will include an array of ingestUrls where RTMPS is the preferred ingestion protocol. Secondary ingest URLs are available in the event the primary ingest URL is unavailable.

Ingestion needs to begin before creating your Post on LinkedIn.

The asset ID will be used in subsequent requests to create a Post, end the Live Event.

Sample Response Body

{
    "value": {
        "ingestUrls": [
            {
                "ingestProtocol": "RTMP",
                "url": "rtmp://12345.channel.media.azure.net:1935/live/12345"
            },
            {
                "ingestProtocol": "RTMP",
                "url": "rtmp://12345.channel.media.azure.net:1936/live/12345"
            },
            {
                "ingestProtocol": "RTMPS",
                "url": "rtmps://12345.channel.media.azure.net:2935/live/12345"
            },
            {
                "ingestProtocol": "RTMPS",
                "url": "rtmps://12345.channel.media.azure.net:2936/live/12345"
            }
        ],
        "previewUrls": [
            "https://12345-vectoreimedia2.preview-usw22.channel.media.azure.net/e57e889f-aaaa-bbbb-cccc-c337afacf31a/preview.ism/manifest"
        ],
        "mediaArtifact": "urn:li:digitalmediaMediaArtifact:(urn:li:digitalmediaAsset:12345,urn:li:digitalmediaMediaArtifactClass:feedshare-live-liveinput)",
        "asset": "urn:li:digitalmediaAsset:12345"
    }
}

Note

We recommend using RTMPS whenever available. If you would like to take advantage of a backup stream, a separate time-synced hardware encoder can be used to stream to the secondary RTMP(s) urls provided.

Live Ingest Requirements

Use the following specifications when encoding your Live Event:

Field Name Description
Duration max 4 hours. Live Events may not exceed 4 hour limit.
Aspect Ratio 16:9
Resolution max 1080p
Frame Rate max 30 fps
Key Frame every 2 seconds (60 frames)
Bitrate max 6 mbps video; max 128 kbps audio, 48 khz sample rate
Encoding H264 video, AAC audio
Protocol RTMP/RTMPS (preferred)

Note

When streaming via RTMP, check firewall and/or proxy settings to confirm that outbound TCP ports 1935 and 1936 are open. When streaming via RTMPS, check firewall and/or proxy settings to confirm that outbound TCP ports 2935 and 2936 are open. For a complete list of IP ranges required for allowlisting, please refer to Microsoft Azure IP Ranges.

Ingest and Create a User Generated Content (UGC) Post

Using the RTMP or RTMPS ingest URLs from the previous step, you may now begin ingestion of your Live Event.

Before creating the Post, first check if the Live ViEventdeo is ready to be shared on LinkedIn.

Check Recipe Status

To check the status of your Live Event, send a GET request to the assets API. After successful ingestion, the recipe status is AVAILABLE, and ready to be included with your UGCPost.

Note

If your asset recipe status has not updated after 15 seconds, there may be an issue with ingestion. End the current session by sending the action to endLiveEvent, and try again by registering a new Live Event.

Recipe Status Description
NEW A newly assigned recipe. This status is only used for new assignments. Transitions to PROCESSING as soon as processing requests are sent.
PROCESSING Some or all of the recipe's required artifacts are not available and processing is underway to generate the missing artifacts.
AVAILABLE All of the recipe's required artifacts are available.
INCOMPLETE The artifact is not available because it has been deleted or is in deleting process.

API Request

GET https://api.linkedin.com/v2/assets/:id

Sample API Response

{
    "owner": "urn:li:person:12345",
    "resourceRelationships": [],
    "serviceRelationships": [],
    "recipes": [
        {
            "recipe": "urn:li:digitalmediaRecipe:feedshare-live-video",
            "status": "AVAILABLE"
        }
    ],
    "mediaTypeFamily": "VIDEO",
    "created": 1539649231180,
    "executedActions": [
        {
            "recipe": "urn:li:digitalmediaRecipe:feedshare-live-video",
            "action": "PROCESSING",
            "createdAt": 1539649231234
        },
        {
            "recipe": "urn:li:digitalmediaRecipe:feedshare-live-video",
            "action": "PROCESSED",
            "createdAt": 1539649504293
        }
    ],
    "lastModified": 1539649504293,
    "id": "12345",
    "status": "ALLOWED"
}

Use the ugcPosts API to create a Post on LinkedIn, viewable by your LinkedIn network. Include the asset ID returned from registering the Live Event, as well as relevant Post metadata in the request body. Keep in mind that the UGC Post must be created as soon as you begin ingestion.

API Request

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

Note

All requests require the following header: X-Restli-Protocol-Version: 2.0.0

Request Body Schema

Field Name Description Format Required
author The author of a share contains either the Person or Organization URN. Person URN
Organization URN		 Yes
lifecycleState Defines the state of the share. For the purposes of creating a share, the lifecycleState will always be PUBLISHED. string Yes
specificContent Provides additional options while defining the content of the share. ShareContent Yes
visibility Defines any visibility restrictions for the share. Possible values include:
  • PUBLIC - The share will be viewable by anyone on LinkedIn.
 MemberNetworkVisibility Yes

Share Content

Field Name Description Format Required
shareCommentary Provides the primary content for the share. string Yes
shareMediaCategory Represents the media assets attached to the share. Possible values include:
  • LIVE_VIDEO - The share contains live event content.
 string Yes
media Use the Asset URN returned from registering the live event. ShareMedia[] No

Share Media

Field Name Description Format Required
status Must be configured to READY. string Yes
media ID of the uploaded image asset. If you are uploading an article, this field is not required. DigitalMediaAsset URN No

Request Headers

Header Value
X-RestLi-Method Create

Sample Request Body

{
    "author": "urn:li:person:abcde12345",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "media": [
                {
                    "media": "urn:li:digitalmediaAsset:12345",
                    "status": "READY"
                }
            ],
            "shareCommentary": {
                "attributes": [],
                "text": "Join us as we live stream!"
            },
            "shareMediaCategory": "LIVE_VIDEO"
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}

A 201 response confirms your UGC Post has been created successfully. To generate a user-friendly URL to your newly created UGC Post, identify the X-RestLi-Id within the response header. Append the header value to https://linkedin.com/feed/update/. The resulting URL should resemble:

https://www.linkedin.com/video/live/urn:li:ugcPost:1238957139875

End the Live Event

Once your Live Event has ended, send an action to end for your asset ID.

API Request

POST https://api.linkedin.com/v2/liveAssetActions?action=end

Sample Request Body

{
    "asset": "urn:li:digitalmediaAsset:C5624AQEUbk4_xZgHJQ"
}

Note

We recommend waiting 10 seconds after your Live Event has ended before submitting the action to endLiveEvent to ensure your broadcast is not interrupted.

A successful response is indicated by a 200 Response Code.