Spotlight Ads API

  • 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.

Linkedin is introducing creation and management of Dynamic Spotlight Ads with external Creatives apis.

Improvements over existing API

The new API has a simpler structure compared to the previous /adCreativesV2 API with Spotlight Ads content.

Permissions

Permission Description
rw_ads Manage and 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
    		•
    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
    		•

    Workflow

    1. Upload an image asset. The new Image API replaces the Assets API, with simplified and consistent schema. See the Images API for more information.
    2. Create a Dynamic Ads Campaign. See Dynamic Ads Campaign.
    3. Design a Creative. The adCreativesV2 API has historically been used to design creatives for a campaign. The new externalized Creatives API features dynamic spotlight ad format fields for easier creative design and development. For more details, see the schema section below.
    Field Type Description Required
    backgroundImage ImageUrn Custom background image uploaded by the advertiser. The default is set to clear background. If you include a background image, there will be no ad description, and the member’s profile photo will not be pulled into the ad. No
    headline string The headline of the ad. It is the main message seen by your target audience. Not used for mobile spotlight ads. Yes
    description string Any additional message or description that provides more information about the ad. If not present, only the headline is shown on the ad. If you include a description, there will be no backgroundImage set. No
    callToAction string The call-to-action (CTA) is what you want your target audience to do after seeing your ad. It is used for the button text. Yes
    landingPage URL The URL where the member should be re-directed to, on clicking the spotlight ad. Yes
    logo ImageUrn Company logo. This may differ from the logo on the official company page. If not present on create, the logo from company page is used. This is optional on creates, but will always be present on reads. Setting it to null on update would default to the logo from company page. No
    organizationName string Company name to use in the ad. This may differ from the name on the official company page. If not present on create, the company name from company page is used. This is optional on creates, but will always be present on reads. Setting it to null on update would default to the name from company page. No
    showMemberProfilePhoto boolean Boolean value that helps decide whether to display profile photo of member in the spotlight ad or not. Defaults to true. No

    Prerequisite Values

    Attribute Possible Values
    Campaign Type DYNAMIC
    Campaign Format SPOTLIGHT
    Creative Type SPOTLIGHT_V2
    Objective Type BRAND_AWARENESS, WEBSITE_CONVERSION, WEBSITE_VISIT, JOB_APPLICANT, TALENT_LEAD

    Create a Dynamic Spotlight Ad Creative

    POST https://api.linkedin.com/rest/creatives

    {
    "content": {
        "spotlight": {
            "callToAction": "Join Us Now",
            "description": "Check out this demo",
            "headline": "Spotlight Ad Demo",
            "landingPage": "http://www.linkedin.com",
            "logo": "urn:li:image:abc",
            "organizationName": "LinkedIn Demo",
            "showMemberProfilePhoto": true
        }
    },
    "campaign": "urn:li:sponsoredCampaign:123",
    "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:123456789

    Get a Dynamic Spotlight Ad Creative

    GET https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    Sample Response

    {
    "servingHoldReasons": [
        "UNDER_REVIEW",
        "CAMPAIGN_STOPPED"
    ],
    "lastModifiedAt": 1648512200000,
    "lastModifiedBy": "urn:li:member:123",
    "content": {
        "spotlight": {
            "organizationName": "LinkedIn Demo",
            "showMemberProfilePhoto": true,
            "landingPage": "http://linkedin.com",
            "description": "Check out this demo",
            "logo": "urn:li:image:abc",
            "headline": "Spotlight Ad Demo",
            "callToAction": "Join Us Now"
        }
    },
    "createdAt": 1648512200000,
    "createdBy": "urn:li:member:123",
    "isTest": false,
    "review": {
        "status": "PENDING"
    },
    "isServing": false,
    "campaign": "urn:li:sponsoredCampaign:123",
    "id": "urn:li:sponsoredCreative:123456789",
    "intendedStatus": "ACTIVE",
    "account": "urn:li:sponsoredAccount:123"
}

    Update a Dynamic Spotlight Ad Creative

    POST https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    {
    "patch": {
        "$set": {
            "content": {
                "spotlight": {
                    "callToAction": "New Action",
                    "description": "New Description",
                    "headline": "New Headline",
                    "landingPage": "http://example.com",                       
                    "organizationName": "New Organization Name",
                    "logo": "urn:li:image:def",
                    "showMemberProfilePhoto": false
                }
            }
        }
    }
}

    A successful response returns a 204 No Content.

    Delete a Dynamic Spotlight Ad Creative

    DELETE https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}

    A successful response returns a 204 No Content.

    Batch Create Dynamic Spotlight Ad Creatives

    POST https://api.linkedin.com/rest/creatives

    {
    "elements": [
        {
            "content": {
                "spotlight": {
                    "callToAction": "Join Us Now",
                    "description": "Check out this demo",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://www.linkedin.com",
                    "logo": "urn:li:image:abc",
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "campaign": "urn:li:sponsoredCampaign:123",
            "intendedStatus": "ACTIVE"
        },
        {
            "content": {
                "spotlight": {
                    "backgroundImage": "urn:li:image:abc"
                    "callToAction": "Join Us Now",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://www.linkedin.com",
                    "logo": "urn:li:image:abc",
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "campaign": "urn:li:sponsoredCampaign:123",
            "intendedStatus": "ACTIVE"
        }
    ]
}

    Sample Response

    {
    "elements": [
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A123456789",
            "status": 201,
            "id": "urn:li:sponsoredCreative:123456789"
        },
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A123456799",
            "status": 201,
            "id": "urn:li:sponsoredCreative:123456799"
        }
    ]
}

    Batch Get Dynamic Spotlight Ad Creatives

    GET 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    Sample Response

    {
    "results": {
        "{sponsoredCreative-urn1}": {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800364000,
            "lastModifiedBy": "urn:li:member:123",
            "content": {
                "spotlight": {
                    "callToAction": "Join Us Now",
                    "description": "Check out this demo",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://www.linkedin.com",
                    "logo": "urn:li:image:abc",
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "createdAt": 1643800364000,
            "isTest": false,
            "createdBy": "urn:li:member:123",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:123",
            "id": "{sponsoredCreative-urn1}",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:123"
        },
        "{sponsoredCreative-urn2}": {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800364000,
            "lastModifiedBy": "urn:li:member:123",
            "content": {
                "spotlight": {
                    "backgroundImage": "urn:li:image:abc",
                    "callToAction": "Join Us Now",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://www.linkedin.com",
                    "logo": "urn:li:image:abc",
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "createdAt": 1643800364000,
            "isTest": false,
            "createdBy": "urn:li:member:123",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:123",
            "id": "{sponsoredCreative-urn2}",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:123"
        }
    },
    "statuses": {
        "{sponsoredCreative-urn1}": 200,
        "{sponsoredCreative-urn2}": 200
    },
    "errors": {}
}

    Batch Update Dynamic Spotlight Ad Creatives

    POST 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    {
    "entities": {
        "{sponsoredCreative-urn1}": {
            "patch": {
                "$set": {
                    "content": {
                        "spotlight": {
                            "callToAction": "New Action",
                            "description": "New Description",
                            "headline": "New Headline",
                            "landingPage": "http://example.com",
                            "logo": "urn:li:image:def",                     
                            "organizationName": "New Organization Name",
                            "showMemberProfilePhoto": false
                        }
                    }
                }
            }
        },
        "{sponsoredCreative-urn2}": {
            "patch": {
                "$set": {
                    "content": {
                        "spotlight": {
                            "backgroundImage": "urn:li:image:def",
                            "callToAction": "New Action",
                            "description": "New Description",
                            "headline": "New Headline",
                            "landingPage": "http://example.com",
                            "logo": "urn:li:image:ghi",                 
                            "organizationName": "New Organization Name",
                            "showMemberProfilePhoto": false
                        }
                    }
                }
            }
        }
    }
}

    Sample Response

    {
    "results": {
        "{sponsoredCreative-urn1}": {
            "status": 204
        },
        "{sponsoredCreative-urn2}": {
            "status": 204
        }
    },
    "errors": {}
}

    Batch Delete Dynamic Spotlight Ad Creatives

    DELETE 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})'

    Sample Response

    {
    "results": {
        "{sponsoredCreative-urn1}": {
            "status": 204
        },
        "{sponsoredCreative-urn2}": {
            "status": 204
        }
    },
    "errors": {}
}

    Finders for Dynamic Spotlight Ad Creatives

    GET 'https://api.linkedin.com/rest/creatives?campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123)&intendedStatuses=List(ACTIVE)&q=criteria&sortOrder=ASCENDING'

    Sample Response

    {
    "paging": {
        "start": 0,
        "count": 2,
        "links": [],
        "total": 2
    },
    "elements": [
        {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643800073000,
            "lastModifiedBy": "urn:li:member:123",
            "content": {
                "spotlight": {
                    "callToAction": "Join Us Now",
                    "description": "Check out this demo",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://www.linkedin.com",
                    "logo": "urn:li:image:abc",  
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "createdAt": 1643767858000,
            "isTest": false,
            "createdBy": "urn:li:member:123",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:123",
            "id": "urn:li:sponsoredCreative:123456789",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:123"
        },
        {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1643791704000,
            "lastModifiedBy": "urn:li:member:123",
            "content": {
                "spotlight": {
                    "backgroundImage": "urn:li:image:abc",
                    "callToAction": "Join Us Now",
                    "headline": "Spotlight Ad Demo",
                    "landingPage": "http://example.com",
                    "logo": "urn:li:image:abc",  
                    "organizationName": "LinkedIn Demo",
                    "showMemberProfilePhoto": true
                }
            },
            "createdAt": 1643791171000,
            "isTest": false,
            "createdBy": "urn:li:member:123",
            "review": {
                "status": "PENDING"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:123",
            "id": "urn:li:sponsoredCreative:123456799",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:123"
        }
    ]
}

    Error Messages

    General creative errors are included in Creatives error.