Live Events APIs

Article
05/08/2023

Overview

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

Register the Live Event.
Ingest RTMP(s) content.
Create a Post to share your Live Event with your LinkedIn network.
End the Live Event.
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

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

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

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.

Live Events APIs

Overview

Getting Started

Authenticating Members

Member Live Events

Company Page Live Events

Tiering

Development Tier

Standard Tier

Register

API Request

Sample Request Body

Sample Response Body

Live Ingest Requirements

Ingest and Create a User Generated Content (UGC) Post

Check Recipe Status

API Request

Sample API Response

API Request

Request Body Schema

Request Headers

Sample Request Body

End the Live Event

API Request

Sample Request Body

Feedback

Feedback

Additional resources

Live Events APIs

Overview

Getting Started

Authenticating Members

Member Live Events

Company Page Live Events

Tiering

Development Tier

Standard Tier

Register

API Request

Sample Request Body

Sample Response Body

Live Ingest Requirements

Ingest and Create a User Generated Content (UGC) Post

Check Recipe Status

API Request

Sample API Response

API Request

Request Body Schema

Share Content

Share Media

Request Headers

Sample Request Body

End the Live Event

API Request

Sample Request Body

Feedback

Feedback

Additional resources