Event Ads API
Warning
Deprecation Notice
The Marketing Version 202401 (Marketing January 2024) has been sunset. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
LinkedIn Event Ads are a type of Sponsored Content that allows advertisers to promote events directly in the LinkedIn feed. This ad type enables advertisers to seamlessly promote a LinkedIn event to a defined audience before, during, and after the event. By using Event Ads, advertisers can increase event visibility, drive registrations, and engage with attendees throughout the event lifecycle.
For Live Events, this format provides an immersive ad experience for event attendees and registrants. Before the event, members can seamlessly register and view event details. During the event, members can watch the live stream directly in their feed. After the event, members can watch a replay of the event.
Authentication
This API follows our standard OAuth Authorization Code flow.
The user authenticates with LinkedIn (see OAuth guidance in the Appendix for introducing a new permission into your OAuth flow scopes).
Ensure all the necessary scopes (permissions) are requested:
rw_ads(for campaign and ad/creative management)w_organization_social,r_organization_social(to manage company page posts)r_events(get events)
Permissions
| Permission | Description | Product |
|---|---|---|
w_organization_social |
Post, comment, and like posts on behalf of an organization. Restricted to the company admin, DSC poster, or content admin. | Advertising API |
r_organization_social |
Retrieve Posts on the company page. | Advertising API |
rw_ads |
Create ads and creatives for a sponsored account. | Advertising API |
r_ads |
Read an authenticated member's Ad Account. Restricted to Ad Accounts in which the authenticated member has one of the following Ad Account roles: ACCOUNT_BILLING_ADMIN, ACCOUNT_MANAGER, CAMPAIGN_MANAGER, CREATIVE_MANAGER, VIEWER |
Advertising API |
r_events |
Retrieve organization’s events. Restricted to organizations in which the authenticated member has one of the following company page roles: ADMINISTRATOR, CONTENT_ADMINISTRATOR |
Event Management API |
Schema
Note
Starting 202410, the name field is introduced in Creative schema. Going forward, this name field is the preferred approach to set and get the creative's name, consistently across all ad formats.
Familiarize yourself with the following APIs required to create an Event Ad:
- Campaigns - create campaigns
- Campaign Groups - create campaign groups
- Posts- create posts (User Generated Content) on behalf of an organization
- Creatives - design creative content for an Ad Campaign
- Events- retrieve Events
Schema for entire creative is similar to Creatives, only the content field now supports an Event Ad content for the creation and management of Event Ads.
Schema for Event Ad Content is as follows:
| Field | Type | Details | Required |
|---|---|---|---|
| post | UserGeneratedContentPostUrn | URN identifying the sponsored user generated content post. This field is read only. | Yes |
| directSponsoredContent | boolean | Indicates whether the creative is direct sponsored content or not. This field is read only. | No |
| event | EventUrn | The LinkedIn event URN associated with this creative. This field is derived from the UGC post URN and is read only. | Yes |
| preEventRegistrationImage | DigitalmediaAssetUrn | Image shown to users who haven't registered for the event yet. | No |
| hidePreviewVideo | boolean | This flag indicates whether the preview should be hidden or not. | No |
| contentAuthor | URN | Author of the content. Optional for backwards compatibility reasons. | No |
Restrictions
Only the following campaign objective types are supported for the Event Ads ad format:
- Brand awareness
- Website visits
- Engagement
Restrictions/validations surrounding Accelerated Delivery are detailed here.
Event Ads are not available for delivery on the LinkedIn Audience Network.
Audio Events are not supported for Event Ads API.
Create an Event Ad with a New Post
To create an event creative, the following steps must be followed:
- Create a Campaign for Event Ad.
- Create the Post for the Event (This should be a dark post).
- Create an Event Creative with the Event dark post.
Create a Campaign for the Event Ad
POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns
{
"account": "urn:li:sponsoredAccount:53333333341",
"campaignGroup": "urn:li:sponsoredCampaignGroup:635137195",
"audienceExpansionEnabled": false,
"costType": "CPV",
"connectedTelevisionOnly": false,
"objectiveType": "ENGAGEMENT", //ENGAGEMENT,BRAND_AWARENESS,WEBSITE_VISITS
"creativeSelection": "OPTIMIZED",
"locale": {"language": "en","country": "US"},
"name": "Testing Live Event Ads",
"format": "SPONSORED_UPDATE_EVENT",
"pacingStrategy: "ACCELERATED" (or "LIFETIME"), //ACCELERATED is now available in the October release version 202410. Note that this is still an optional field so not setting it upon create is still valid.
"offsiteDeliveryEnabled": false,
"runSchedule": {
"start": 1520890990333,
"end": 1521754990333
},
"targetingCriteria": {
"include": {
"and": [
{
"or": {
"urn:li:adTargetingFacet:interfaceLocales": [
"urn:li:locale:en_US"
]
}
},
{
"or": {
"urn:li:adTargetingFacet:locations": [
"urn:li:geo:103644278"
]
}
}
]
}
},
"type": "SPONSORED_UPDATES",
"dailyBudget": {
"currencyCode": "USD",
"amount": "18"
},
"unitCost": {
"amount": "15",
"currencyCode": "USD"
},
"status": "ACTIVE"
}
A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header. For example, urn:li:sponsoredCreative:164380864
Get an Event by ID
Note
Replace the eventID parameter with the specific Event ID, which will look like 7189069406168117248.
Sample Response
{
"vanityName": "testlive7189069406168117248",
"settings": {
"entryCriteria": "PUBLIC",
"attendanceMode": "VIRTUAL",
"discoveryMode": "LISTED",
"invitationSettings": {
"invitationPrivilegePolicies": [
{
"com.linkedin.adsexternalapi.events.v1.SimpleEventInvitationPrivilegePolicyV1": "ALL_ATTENDEES"
}
]
},
"mapsToSingleUgcPost": true
},
"timeRangeV2": {
"startsAt": 1735704000000
},
"localizedName": "Test Live",
"created": {
"actor": "urn:li:person:kb6e46S_kG",
"time": 1714007712961
},
"organizer": "urn:li:organization:1234657", //this should be the same as the organization tied to the ad account
"name": {
"localized": {
"en_US": "Test Live"
},
"preferredLocale": {
"country": "US",
"language": "en"
}
},
"id": 7189069406168117248,
"lastModified": {
"actor": "urn:li:person:kb6e46S_kG",
"time": 1714007712961
},
"localizedDescription": {
"rawText": ""
},
ugcPost: "urn:li:ugcPost:7246667386014023680"
}
A successful response returns a 200 OK HTTP status code.
Note
Using the URN from the ugcPost field, get the post by calling the GET Posts endpoint to get either the liveVideo URN (for a Live event) or an event URN (for a non-Live event). The ugcPost URN or the event URN is used in the next step to create a dark events ads post.
Get a Post by URN
Replace the UGCPostUrn parameter with the specific URN, which will look like urn%3Ali%3AugcPost%3A7246667386014023680.
Sample Response
{
"isReshareDisabledByAuthor": false,
"createdAt": 1727740141581,
"lifecycleState": "PUBLISHED",
"lastModifiedAt": 1727740156240,
"visibility": "PUBLIC",
"publishedAt": 1727740141581,
"author": "urn:li:organization:1234657",
"id": "urn:li:ugcPost:7246667386014023680",
"distribution": {
"feedDistribution": "MAIN_FEED",
"thirdPartyDistributionChannels": []
},
"content": {
"reference": {
"id": "urn:li:liveVideo:7240449542943305728"
}
},
"commentary": "cbrehm testing live event september 2024 POST",
"lifecycleStateInfo": {
"isEditedByAuthor": false
}
}
A successful response returns a 200 OK HTTP status code. Using the live video URN from the response in this step, create the dark post in this step.
Create a Dark Post for a Live Event
POST https://api.linkedin.com/rest/posts
{
"adContext": {
"dscAdAccount": "urn:li:sponsoredAccount:53333333341",
"dscStatus": "ACTIVE"
},
"author": "urn:li:organization:1234567",
"commentary": "Sample Live Event Post",
"visibility": "PUBLIC",
"distribution": {
"feedDistribution": "NONE",
"targetEntities": [],
"thirdPartyDistributionChannels": []
},
"content":{
"reference":{
//Live video urn associated with your event (or event urn if not a live event)
"id": "urn:li:liveVideo:7240449542943305728"
}
},
"lifecycleState": "PUBLISHED",
"isReshareDisabledByAuthor": true
}
A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header.
Create an Event Ad Creative
This creative ties the campaign and the dark post together.
POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/creatives
{
"content": {
//Post urn - response from the dark post creation API (Step #5.g)
"reference": "urn:li:ugcPost:7240552321461111111"
},
//Campaign urn - response from the campaign API (Step #4.a)
"campaign": "urn:li:sponsoredCampaign:330682563",
"intendedStatus": "ACTIVE"
}
A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header. For example, urn:li:sponsoredCreative:120491345.
Appendix
OAuth Guidance
Since you will be adding new permissions to the OAuth scopes, your customers will need to reauthenticate to allow you to make API calls to the new endpoints on their behalf. To do this seamlessly and with minimal disruption to your customers, we recommend the following: (Please note that the guidance below assumes you are using the same Client ID and Secret.)
Update your OAuth flow scope with the new permissions required to access the APIs for the new feature.
New customers (have never been a customer on your platform before) will by default trigger the updated OAuth flow (thus moving forward they will be able to access the new features from an access token perspective once you’ve ungated the feature in the UI for them).
Existing customers who are not ramped to this new feature in your UI and thus not using the new permissions will continue as is, for now.
When you exchange their refresh token for a new access token every 60 days, the access token returned will only have the scopes initially granted for the initial refresh token (this will not reflect the updated OAuth scope).
If an existing user’s access tokens become invalidated/revoked or the refresh token expires, you will force them to reauthenticate and go through the updated OAuth flow with the new scope and permissions (thus moving forward they will be able to access the new features from an access token perspective once you’ve ungated the feature in the UI for them).
Existing customers who are ramped to use the new feature in your UI and the new permissions
When they signal they want to use the new feature you will force them to reauthenticate and go through the updated OAuth flow with the updated scope and permissions
Note: Once users reauthenticate, all tokens previously generated for each user by your client ID and secret will be invalidated so only the newly generated access and refresh token should be stored and used moving forward. A user can have multiple active/valid tokens generated by your client id and client secret so long as they were all granted with the same scopes.
Frequently Asked Questions
Q1: What if I want to use the same client ID and secret but want separate OAuth flows for each feature (matched audiences, Lead Syncing, conversions, etc)? In other words, the user authenticates for each feature with a unique set of scopes
Answer: This is not recommended because a user may use multiple features within your platform which would lead to token conflicts and the user inadvertently invalidating their tokens. If you want to achieve separate OAuth flows with unique scopes for each feature then you will need a LinkedIn Developer App for each feature and use the unique Client ID and Secret for each OAuth flow.
Error Messages
General creative errors are included here - Creatives error.