About Video Ads (Legacy)

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to be sunset soon. 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.

Video ads are the next generation of LinkedIn's Sponsored Content products that enable you to engage business decision-makers on LinkedIn's mobile and desktop news feed.

You can create video ads in two ways:

  • Post videos to your Company Page and sponsor the post to reach more than just followers. Using Company Page Video, you can share a first-hand look into your company culture, products, news, and events in order to drive engagement and start conversations.
  • Create video ads that bypass Company Page followers and go directly to a member's news feed.

Video ads must meet the specifications described in Advertising Specifications for Video Ads.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's ad accounts. To sponsor a video, the authenticated member must meet both of the following conditions:
  • Be an ADMINISTRATOR of a Company Page or a DIRECT_SPONSORED_CONTENT_POSTER with access to Campaign Manager.
  • Have one of the following ad account roles:
  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
    		•
    r_ads Read an authenticated member's ad accounts. 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
    		•

    Use the organizationalEntityCreateShareAuthorizations endpoint to determine whether the authenticated member has the required roles to create a video ad.

    Schema

    Field Type Description
    account SponsoredAccountUrn Create-only field for adAccount association
    contentReference Urn Create-only field which supports the UserGeneratedContentPostUrn endpoint value (e.g., urn:li:ugcPost:6366778577446281216)
    name Optional string Name of the adDirectSponsoredContents
    owner OrganizationUrn Create-only field to express owner of the organization (e.g., urn:li:organization:<organization-id>)
    type AdDirectSponsoredContentType Create-only field used to describe the content type (e.g., VIDEO).

    Required Steps

    To create a video ad, you must do all of the following:

    Create an AdDirectSponsoredContent

    To create adDirectSponsoredContents, the LinkedIn member (to whom the access token belongs) must have access to:

    • The organization set in the owner field
    • An ad account value set in the account field

    Verify your access before you send the request.

    Make sure to set the Content-Type header to application/json.

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

    {
    "account": "urn:li:sponsoredAccount:517803082",
    "contentReference": "urn:li:ugcPost:6369250108747325440",
    "name": "Test dsc",
    "owner": "urn:li:organization:0000",
    "type": "VIDEO"
}

    A successful response returns a 201 Created HTTP status code and the ID in the x-linkedin-id response header.

    A failed response returns a 400 Bad Request Error.

    To avoid failures, verify the following:

    1. The Ad Account entity set in the account field may be linked to an organization through the Ad Account's reference field. See Ad Account Schema. The linked organization must be the same organization provided in the owner field. For example, if the Ad Account's linked organization is urn:li:organization:0000, the owner field set in the above creation call must also be urn:li:organization:0000. 1 The ugcPost set in contentReference field must have visibility as SponsoredContentVisibility.DARK.
    2. The video asset should be created with registerUploadRequest.recipes as urn:li:digitalmediaRecipe:ads-video_v2.
    3. The type must match the ShareMediaCategory of the given ugcPost and should be equal to VIDEO.
    4. The owner of the ugcPost must match the owner in the adDirectSponsoredContents.
    5. The owner in the adDirectSponsoredContents should be an organizationUrn.
    6. The member (to whom this access token belongs) who is creating adDirectSponsoredContents must have access to the organization set in the owner field and AdAccount set in the account field.

    Fetch a Video Ad

    You can fetch adDirectSponsoredContents by the ugcPost URN. Organic videos posted to the Company Page and then sponsored in Campaign Manager do not have a corresponding adDirectSponsoredContents object.

    GET https://api.linkedin.com/v2/adDirectSponsoredContents/{ugcPost-urn}

    Sample Response

    {
    "account": "urn:li:sponsoredAccount:517803082",
    "changeAuditStamps": {
        "created": {
            "time": 1518547642000
        },
        "lastModified": {
            "time": 1519258592000
        }
    },
    "contentReference": "urn:li:ugcPost:6369250108747325440",
    "name": "test update dsc again",
    "owner": "urn:li:organization:5590506",
    "type": "VIDEO"
}

    A successful response returns a 200 OK HTTP status code.

    Fetching Multiple Video Ads

    You can fetch multiple videos in one API call by providing multiple IDs in the ids parameter.

    Sample Request

    This sample uses Restli 2.0 and requires the Restli 2.0 header.

    GET https://api.linkedin.com/v2/adDirectSponsoredContents?ids=List(urn%3Ali%3Ashare%3A6264971476567408640,urn%3Ali%3AugcPost%3A6321851285679153152)

    Sample Response

    { 
   "statuses":{ 
   },
   "results":{ 
      "urn:li:ugcPost:6321851285679153152":{ 
         "owner":"urn:li:organization:11050",
         "changeAuditStamps":{ 
            "created":{ 
               "time":1507246801000
            },
            "lastModified":{ 
               "time":1521580166000
            }
         },
         "contentReference":"urn:li:ugcPost:6321851285679153152",
         "name":"test",
         "type":"VIDEO",
         "account":"urn:li:sponsoredAccount:516797086",
         "status":"ACTIVE"
      },
      "urn:li:ugcPost:6264971476567408640":{ 
         "owner":"urn:li:organization:11050",
         "changeAuditStamps":{ 
            "created":{ 
               "time":1493685597000
            },
            "lastModified":{ 
               "time":1493685597000
            }
         },
         "contentReference":"urn:li:ugcPost:6264971476567408640",
         "name":"test",
         "type":"VIDEO",
         "account":"urn:li:sponsoredAccount:516797086",
         "status":"ACTIVE"
      }
   },
   "errors":{ 
   }
}

    Update a Video Ad

    When you perform a partial update, the header must include contentType=application/json and X-RestLi-Method must be set to PARTIAL_UPDATE.

    POST https://api.linkedin.com/v2/adDirectSponsoredContents/{ugcPost-urn}

    Sample Request

    The following example shows how to change the name field. You can only update name when you edit adDirectSponsoredContents.

    POST https://api.linkedin.com/v2/adDirectSponsoredContents/urn:li:ugcPost:6369250108747325440

    {
    "patch": {
        "$set": {
            "name": "test update dsc again"
        }
    }
}

    A successful response returns a 204 No Content status.

    Archive Direct Sponsored Content

    You may discover that you posted too many Direct Sponsored Content (DSC) instances, creating clutter on your site. LinkedIn enables you to remove existing DSC instances to manage your posted content effectively by updating your DSC instances using a POST request.

    POST https://api.linkedin.com/v2/adDirectSponsoredContents/urn:li:share:12345

    {
    "patch": {
        "$set": {
            "status": "ARCHIVED"
        }
    }
}

    A successful response returns a 204 No Content status.

    Finders

    There are two types of finders:

    Account Finder

    You can get all adDirectSponsoredContents under an adAccount. You can request paged results using start and count. The max count value is 100. You can filter the results to a certain type of record using the types query parameter.

    GET https://api.linkedin.com/v2/adDirectSponsoredContents?account={encoded-sponsoredAccount-urn}&owner={encoded-organization-urn}&q=account&types=List[VIDEO]&includeTotals=false

    Sample Request

    GET https://api.linkedin.com/v2/adDirectSponsoredContents?account=urn%3Ali%3AsponsoredAccount%3A517803082&owner=urn%3Ali%3Aorganization%3A5590506&q=account&types=List[VIDEO]&includeTotals=false

    Sample Response

    {
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:517803082",
            "changeAuditStamps": {
                "created": {
                    "time": 1518547642000
                },
                "lastModified": {
                    "time": 1519258592000
                }
            },
            "contentReference": "urn:li:ugcPost:6369250108747325440",
            "name": "test update dsc again",
            "owner": "urn:li:organization:5590506",
            "type": "VIDEO"
        }
    ],
    "paging": {
        "count": 24,
        "links": [],
        "start": 0,
        "total": 0
    }
}

    A successful response returns a 200 OK HTTP status code.

    Owner Finder

    You can get all adDirectSponsoredContents by an organization if you are an ADMINISTRATOR of the organization.

    GET https://api.linkedin.com/v2/adDirectSponsoredContents?owner={encoded-organization-urn}&q=owner

    Sample Request

    GET https://api.linkedin.com/v2/adDirectSponsoredContents?owner=urn%3Ali%3Aorganization%3A5590506&q=owner

    Sample Response

    {
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:517803082",
            "contentReference": "urn:li:ugcPost:6369250108747325440",
            "name": "test update dsc again",
            "owner": "urn:li:organization:5590506",
            "type": "VIDEO"
        }
    ],
    "paging": {
        "count": 2147483647,
        "links": [],
        "start": 0,
        "total": 1
    }
}

    A successful response returns a 200 OK HTTP status code.