Spotlight Ads API

Article
10/15/2024

Warning

Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will 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

Note

Starting 202410, a new name field is introduced in Creative schema. Going forward, this new name field is the preferred approach to set and get the creative's name, consistently across all ad formats.

Upload an image asset. The new Image API replaces the Assets API, with simplified and consistent schema. See the Images API for more information.
Create a Dynamic Ads Campaign. See Dynamic Ads Campaign.
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

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"
}

curl --location --request POST 'https://api.linkedin.com/rest/creatives' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'Content-Type: application/json' \
-H 'X-Restli-Protocol-Version: 2.0.0' 
--data '{
    "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

http
curl

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

curl --location --request GET 'https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

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
                }
            }
        }
    }
}

curl --location --request POST 'https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}' \
-H 'X-RestLi-Method: PARTIAL_UPDATE' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json'
--data '{
    "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
                }
            }
        }
    }
}'

A successful response returns a 204 No Content.

Delete a Dynamic Spotlight Ad Creative

http
curl

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

curl --location --request DELETE 'https://api.linkedin.com/rest/creatives/{sponsoredCreative-urn}' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'X-RestLi-Method: DELETE' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

A successful response returns a 204 No Content.

Batch Create Dynamic Spotlight Ad Creatives

http
curl

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"
        }
    ]
}

curl --location --request POST 'https://api.linkedin.com/rest/creatives' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'X-RestLi-Method: BATCH_CREATE' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json'
--data '{
    "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

http
curl

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

curl --location --request GET 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'X-RestLi-Method: BATCH_GET' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

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
                        }
                    }
                }
            }
        }
    }
}

curl --location --request POST 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})' \
-H 'X-RestLi-Method: BATCH_PARTIAL_UPDATE' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json'
--data '{
     "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

http
curl

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

curl --location --request DELETE 'https://api.linkedin.com/rest/creatives?ids=List({sponsoredCreative-urn1},{sponsoredCreative-urn2})' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'X-RestLi-Method: BATCH_DELETE' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

Sample Response

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

Finders for Dynamic Spotlight Ad Creatives

http
curl

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

curl --location --request GET 'https://api.linkedin.com/rest/creatives?campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123)&intendedStatuses=List(ACTIVE)&q=criteria&sortOrder=ASCENDING' \
-H 'X-RestLi-Protocol-Version: 2.0.0' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'X-RestLi-Method: FINDER' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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.

Share via

Spotlight Ads API

Improvements over existing API

Permissions

Workflow

Prerequisite Values

Create a Dynamic Spotlight Ad Creative

Get a Dynamic Spotlight Ad Creative

Sample Response

Update a Dynamic Spotlight Ad Creative

Delete a Dynamic Spotlight Ad Creative

Batch Create Dynamic Spotlight Ad Creatives

Sample Response

Batch Get Dynamic Spotlight Ad Creatives

Sample Response

Batch Update Dynamic Spotlight Ad Creatives

Sample Response

Batch Delete Dynamic Spotlight Ad Creatives

Sample Response

Finders for Dynamic Spotlight Ad Creatives

Sample Response

Error Messages

Feedback

Additional resources