Follower 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 its next generation of APIs for the creation and management of Dynamic Follower Ads.

This ad format replaces the previous /adCreativesV2 ad format for follower ads.

Permissions

Permission Possible Values
rw_ads Manage and read an authenticated member's Ad Accounts. In addition, authenticated member must have READ access for a Company Page and 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 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
    		•

    Workflow

    Typical workflow to create dynamic follower ad format is as follows:

    1. Upload an image asset. At present, LinkedIn partners are using Assets API to upload images. The new Image API replaces the Assets API, with simplified and consistent schema. Refer to Images API for more information.
    2. Create a Dynamic Ads Campaign. See Dynamic Ad Campaigns.
    3. Design a Creative. The new Creatives API replaces the /adCreativesV2 API, and features dynamic follower ad format fields for easier creative design and development. For more details in schema section below.

    Schema

    Field Type Description Required
    description Either a preApproved string or a custom string The description is text at the top of the ad. It provides more information to people who see the ad. It can follow either of the following formats:
    1. {"preApproved": "{description}"} Pre-approved and localized follower description text not subject to review process. Standard values:
      • GET_LATEST_JOBS_NEWS_AND_MORE - Get the latest on jobs, news and more
      • RECEIVE_DAILY_OR_WEEKLY_ORGANIZATION_UPDATES - Receive daily or weekly organization updates
      • OPPORTUNITIES_ARE_KNOCKING_ON_YOUR_DOOR - Opportunities are knocking on your door
      • GET_LATEST_JOBS_AND_INDUSTRY_NEWS - Get the latest jobs and industry news
      • KEEP_UP_WITH_INTERESTING_RELEVANT_UPDATES - Keep up with interesting, relevant updates
      • VISIT_CAREERS - Visit the careers page for {organizationName}!
      • VISIT_ORGANIZATION - Visit the organization page for {organizationName}!
      • MEMBER_STAY_INFORMED_ON_INDUSTRY_NEWS_AND_TRENDS {memberName}, stay informed on industry news and trends
      • IMAGINE_YOUR_NEXT_CAREER - Imagine your next career move
      • READY_FOR_NEXT_OPPORTUNITY - Ready for your next opportunity?
      • YOU_GOT_SKILLS_WEVE_GOT_OPPORTUNITIES - You've got the skills, we've got the opportunities!
      • YOU_GOT_SKILLS_ORGANIZATION_HAS_OPPORTUNITIES - You've got the skills, {organizationName} has the opportunities!
      • STAY_INFORMED_ON_INDUSTRY_NEWS_AND_TRENDS - Stay informed on industry news and trends
      • VISIT_COMPANY - Visit the company page for {organizationName}
      • RECIEVE_DAILY_OR_WEEKLY_COMPANY_UPDATES - Receive daily or weekly company updates
    2. {"custom": "{description}"} Custom description text subject to review process.
    		 Yes
    showMemberProfilePhoto boolean Boolean value that helps decide whether to display profile photo of member in the follower ad or not. Default true. No
    headline Either a preApproved string or a custom string The headline is bold text displayed right beneath the image or logo. It is the main message seen by the target audience. It can follow either of the following formats:
    1. {"preApproved": "{headline}"} Pre-approved and localized follower headline text not subject to review process. Standard values:
      • MEMBER_EXPLORE_RELEVANT_OPPORTUNITIES - {memberName}, explore relevant opportunities with {organizationName}
      • MEMBER_GROW_BUSINESS_NEWS_INSIGHTS - {memberName}, grow your business with news and insights from {organizationName}
      • GROW_YOUR_BUSINESS_INSIGHTS - Grow your business with insights from {organizationName}
      • MEMBER_KEEP_UP_WITH_LATEST_INSIGHTS - {memberName}, keep up with the latest insights from {organizationName}
      • MEMBER_YOU_MIGHT_LIKE_TO_FOLLOW - {memberName}, you might like to follow {organizationName}
      • MEMBER_KEEP_UP_WITH_RELEVANT_OPPORTUNITIES - {memberName}, keep up with relevant opportunities at {organizationName}
      • MEMBER_GROW_YOUR_CAREER_BY_FOLLOWING - {memberName}, grow your career by following {organizationName}
      • MEMBER_GET_LATEST_NEWS_JOBS_AND_MORE - {memberName}, get the latest on {organizationName} news, jobs, and more!
      • MEMBER_CURRENTLY_RECRUITING_IN_YOUR_SECTOR - {memberName}, currently recruiting in your sector!
      • MEMBER_ORGANIZATION_IS_HIRING - {memberName}, {organizationName} is hiring!
      • MEMBER_READY_FOR_YOUR_DREAM_JOB - {memberName}, ready for your dream job?
      • GROW_YOUR_BUSINESS_WITH_NEWS_AND_INSIGHTS - Grow your business with news and insights from {organizationName}
      • MEMBER_GET_THE_LATEST_ON_ORGANIZATION_NEW_JOBS_AND_MORE - {memberName}, Get the latest on {organizationName} News, Jobs, and More!
    2. {"custom": "{headline}"} Custom headline text subject to review process.
    		 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
    callToAction string The call-to-action (CTA) is what you want your target audience to do after seeing your ad. Possible values:
    • VISIT_ORGANIZATION_COMPANY_PAGE - Directs the member to the organization overview page.
    • VISIT_ORGANIZATION_LIFE_PAGE - Directs the member to the organization life page.
    • VISIT_ORGANIZATION_JOBS_PAGE - Directs the member to the organization jobs page.
    • VISIT_ORGANIZATION_CAREERS_PAGE - Direct the member to the organization jobs page, but the text will read 'Visit Careers' instead of 'Visit Jobs'
    		 Yes

    Prerequisite Values

    Attribute Possible Values
    Campaign Type DYNAMIC
    Campaign Format FOLLOW_COMPANY
    Creative Type FOLLOW_COMPANY_V2
    Objective Type BRAND_AWARENESS, ENGAGEMENT

    Create a Dynamic Follower Ad Creative

    Sample Request

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

    {
    "content": {
     "follow": {
      "organizationName": "Test Company Name",
      "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
      "headline": {
          "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
      },
      "description": {
          "preApproved": "GET_LATEST_JOBS_AND_INDUSTRY_NEWS"
      },
      "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
      "showMemberProfilePhoto": true
     }
    },
    "campaign": "urn:li:sponsoredCampaign:190492324",
    "intendedStatus": "DRAFT"
}

    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 a Dynamic Follower Ad

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

    Sample Response

    {
    "createdAt": 1646177413000,
    "servingHoldReasons": [
        "STOPPED",
        "CAMPAIGN_STOPPED"
    ],
    "lastModifiedAt": 1646177413000,
    "isTest": false,
    "createdBy": "urn:li:person:B1U4S2MZ-C",
    "isServing": false,
    "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
    "campaign": "urn:li:sponsoredCampaign:190492324",
    "id": "urn:li:sponsoredCreative:164380864",
    "intendedStatus": "DRAFT",
    "account": "urn:li:sponsoredAccount:508915158",
    "content": {
        "follow": {
            "description": {
                "preApproved": "GET_LATEST_JOBS_AND_INDUSTRY_NEWS"
            },
            "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
            "showMemberProfilePhoto": true,
            "organizationName": "Test Company Name",
            "headline": {
                "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
            },
            "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE"
        }
    }
}

    A successful response returns a HTTP 200 status code.

    Update a Dynamic Follower Ad

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

    {
"patch": {
          "$set": {
            "content": {
              "follow": {
                  "organizationName": "Test Company Name",
                  "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
                  "headline": {
                      "preApproved": "MEMBER_KEEP_UP_WITH_LATEST_INSIGHTS"
                  },
                  "description": {
                      "custom": "custom_description"
                  },
                  "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
                  "showMemberProfilePhoto": true
                 }
              }
            }
         }
      }

    A successful response returns a 204 No Content HTTP status code.

    Delete a Dynamic Follower Ad

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

    A successful response returns a 204 No Content.

    Batch Create Dynamic Follower Ads

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

    {
  "elements": [
    {
    "content": {
     "follow": {
      "organizationName": "Test Company Name",
      "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
      "headline": {
          "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
      },
      "description": {
          "preApproved": "GET_LATEST_JOBS_AND_INDUSTRY_NEWS"
      },
      "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
      "showMemberProfilePhoto": true
     }
    },
    "campaign": "urn:li:sponsoredCampaign:190492324",
    "intendedStatus": "DRAFT"
    },
    {
    "content": {
     "follow": {
      "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
      "headline": {
          "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
      },
      "description": {
          "custom": "custom description"
      },
      "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
      "showMemberProfilePhoto": true
     }
    },
    "campaign": "urn:li:sponsoredCampaign:190492324",
    "intendedStatus": "DRAFT"
}
]
}

    Sample Response

    {
    "elements": [
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A164385234",
            "status": 201,
            "id": "urn:li:sponsoredCreative:164385234"
        },
        {
            "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A164385244",
            "status": 201,
            "id": "urn:li:sponsoredCreative:164385244"
        }
    ]
}

    Batch Get Dynamic Follower Ads

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

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:164385244": {
            "createdAt": 1646181778000,
            "servingHoldReasons": [
                "STOPPED",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1646181778000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "isServing": false,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "campaign": "urn:li:sponsoredCampaign:190492324",
            "id": "urn:li:sponsoredCreative:164385244",
            "intendedStatus": "DRAFT",
            "account": "urn:li:sponsoredAccount:508915158",
            "content": {
                "follow": {
                    "description": {
                        "custom": "custom description"
                    },
                    "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
                    "showMemberProfilePhoto": true,
                    "organizationName": "Italian Devtestco..",
                    "headline": {
                        "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
                    },
                    "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE"
                }
            }
        },
        "urn:li:sponsoredCreative:164385234": {
            "createdAt": 1646181778000,
            "servingHoldReasons": [
                "STOPPED",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1646181778000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "isServing": false,
            "lastModifiedBy": "urn:li:person:B1U4S2MZ-C",
            "campaign": "urn:li:sponsoredCampaign:190492324",
            "id": "urn:li:sponsoredCreative:164385234",
            "intendedStatus": "DRAFT",
            "account": "urn:li:sponsoredAccount:508915158",
            "content": {
                "follow": {
                    "description": {
                        "preApproved": "GET_LATEST_JOBS_AND_INDUSTRY_NEWS"
                    },
                    "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
                    "showMemberProfilePhoto": true,
                    "organizationName": "Test Company Name",
                    "headline": {
                        "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
                    },
                    "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE"
                }
            }
        }
    },
    "statuses": {
        "urn:li:sponsoredCreative:164385244": 200,
        "urn:li:sponsoredCreative:164385234": 200
    },
    "errors": {}
}

    Batch Update Dynamic Follower Ads

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

    {
  "entities": {
    "urn:li:sponsoredCreative:{sponsoredCreative-urn1}": {
      "patch": {
        "$set": {
          "content": {
            "follow": {
      "organizationName": "Test Company Name",
      "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
      "headline": {
          "custom": "custom_headline1"
      },
      "description": {
          "preApproved": "GET_LATEST_JOBS_AND_INDUSTRY_NEWS"
      },
      "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
      "showMemberProfilePhoto": true
     }
          }
        }
      }
    },
    "urn:li:sponsoredCreative:{sponsoredCreative-urn2}": {
      "patch": {
        "$set": {
          "content": {
            "follow": {
      "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
      "headline": {
          "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
      },
      "description": {
          "custom": "custom description2"
      },
      "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE",
      "showMemberProfilePhoto": true
     }
          }
        }
      }
    }
  }
}

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:164385244": {
            "status": 204
        },
        "urn:li:sponsoredCreative:164385234": {
            "status": 204
        }
    },
    "errors": {}
}

    Batch Delete Dynamic Follower Ads

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

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:164385244": {
            "status": 204
        },
        "urn:li:sponsoredCreative:164385234": {
            "status": 204
        }
    },
    "errors": {}
}

    Finders for Dynamic Follower Ads

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

    Sample Response

    {
    "paging": {
        "start": 0,
        "count": 10,
        "links": [],
        "total": 1
    },
    "elements": [
        {
            "servingHoldReasons": [
                "UNDER_REVIEW",
                "CAMPAIGN_STOPPED"
            ],
            "lastModifiedAt": 1646180655000,
            "lastModifiedBy": "urn:li:system:0",
            "content": {
                "follow": {
                    "description": {
                        "custom": "custom description2"
                    },
                    "logo": "urn:li:image:C5522AQEomekaeMS6eQ",
                    "showMemberProfilePhoto": true,
                    "organizationName": "Italian Devtestco..",
                    "headline": {
                        "preApproved": "GROW_YOUR_BUSINESS_INSIGHTS"
                    },
                    "callToAction": "VISIT_ORGANIZATION_COMPANY_PAGE"
                }
            },
            "createdAt": 1646179904000,
            "isTest": false,
            "createdBy": "urn:li:person:B1U4S2MZ-C",
            "review": {
                "status": "NEEDS_REVIEW"
            },
            "isServing": false,
            "campaign": "urn:li:sponsoredCampaign:190492324",
            "id": "urn:li:sponsoredCreative:164382034",
            "intendedStatus": "ACTIVE",
            "account": "urn:li:sponsoredAccount:508915158"
        }
    ]
}

    Error Messages

    General creative errors are included here - Creatives error.