Text Ads API

  • Article

Warning

Deprecation Notice
The Marketing version 202209 (Marketing September 2022) 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.

You can create and manage Text Ads with the external Creatives API. Text ads include a headline, brief text, and an image. You can place them on the right rail of various LinkedIn desktop pages.

Requirements

For creation of Text ads, the following requirements must be met. See Text Ads Specifications.

Permissions

Permission Description
rw_ads Manage and read an authenticated member's Ad Accounts. To sponsor a image, 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 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
    		•

    Schema

    Schema for entire creative is similar to Creatives, only the content field now supports a Text Ad content for the creation and management of Text Ads.

    Schema for Text Ad Content is as follows:

    Field Type Details Required
    description string The description that provides more information about the ad. Use up to 75 characters, including spaces. Yes
    headline string The main message seen by the target audience on the ad. Use up to 25 characters, including spaces Yes
    image ImageUrn Image uploaded by the advertiser, size is 100 x 100 pixels and <= 2MB, format is either a JPG or PNG file. If empty, there is none No
    landingPage URL The URL where the member should be redirected to, on clicking the text ad. yes

    Create a Text Ad

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

    {
    "content": {
      "textAd": {
        "landingPage": "https://lnkd.in/eabXpqi",
        "headline": "prod test headline",
        "description": "prod test description",
        "image": "urn:li:image:C4E22AQGX_uq7mQBfAA"
      }
    },
    "campaign": "urn:li:sponsoredCampaign:191989474",
    "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:164380864

    Get a Text Ad

    GET https://api.linkedin.com/rest/creatives/{sponsoredCreativeUrn}

    Sample Response

    {
   "servingHoldReasons": [
       "UNDER_REVIEW",
       "ACCOUNT_SERVING_HOLD"
   ],
   "lastModifiedAt": 1650828926000,
   "lastModifiedBy": "urn:li:system:0",
   "content": {
       "textAd": {
           "image": "urn:li:image:C4E22AQGX_uq7mQBfAA",
           "description": "prod test description",
           "headline": "prod test headline",
           "landingPage": "https://lnkd.in/eabXpqi"
       }
   },
   "createdAt": 1650828923000,
   "isTest": false,
   "createdBy": "urn:li:person:B1U4S2MZ-C",
   "review": {
       "status": "NEEDS_REVIEW"
   },
   "isServing": false,
   "campaign": "urn:li:sponsoredCampaign:191989474",
   "id": "urn:li:sponsoredCreative:170811644",
   "intendedStatus": "ACTIVE",
   "account": "urn:li:sponsoredAccount:508915158"
}

    Update a Text Ad

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

    {
"patch": {
       "$set": {
           "content": {
             "textAd": {
                 "landingPage": "https://lnkd.in/eabXpqi",
                 "headline": "new prod test headline",
                 "description": "new prod test description"
              }
         }
       }
   }
}

    A successful response returns a 204 No Content.

    Delete a Text Ad

    DELETE https://api.linkedin.com/rest/creatives/{sponsoredCreativeUrn}

    A successful response returns a 204 No Content.

    Batch Create Text Ads

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

    {
  "elements": [
   {
       "content": {
         "textAd": {
           "landingPage": "https://lnkd.in/eabXpqi",
           "headline": "HL1",
           "description": "DP1",
           "image": "urn:li:image:C4E22AQGX_uq7mQBfAA"
         }
       },
       "campaign": "urn:li:sponsoredCampaign:192479594",
       "intendedStatus": "DRAFT"
   },
   {
       "content": {
         "textAd": {
           "landingPage": "https://lnkd.in/eabXpqi",
           "headline": "HL2",
           "description": "DP2",
           "image": "urn:li:image:C4E22AQGX_uq7mQBfAA"
         }
       },
       "campaign": "urn:li:sponsoredCampaign:192479594",
       "intendedStatus": "DRAFT"
   }
 ]
}

    Sample Response

    {
   "elements": [
       {
           "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A170811974",
           "status": 201,
           "id": "urn:li:sponsoredCreative:170811974"
       },
       {
           "location": "/partnerApiCreatives/urn%3Ali%3AsponsoredCreative%3A170811984",
           "status": 201,
           "id": "urn:li:sponsoredCreative:170811984"
       }
   ]
}

    Batch Get Text Ads

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

    Sample Response

    {
   "results": {
       "urn:li:sponsoredCreative:170811974": {
           "servingHoldReasons": [
               "UNDER_REVIEW",
               "ACCOUNT_SERVING_HOLD"
           ],
           "lastModifiedAt": 1650830101000,
           "lastModifiedBy": "urn:li:system:0",
           "content": {
               "textAd": {
                   "image": "urn:li:image:C4E22AQGX_uq7mQBfAA",
                   "description": "DP1",
                   "headline": "HL1",
                   "landingPage": "https://lnkd.in/eabXpqi"
               }
           },
           "createdAt": 1650830099000,
           "isTest": false,
           "createdBy": "urn:li:person:B1U4S2MZ-C",
           "review": {
               "status": "NEEDS_REVIEW"
           },
           "isServing": false,
           "campaign": "urn:li:sponsoredCampaign:191989474",
           "id": "urn:li:sponsoredCreative:170811974",
           "intendedStatus": "ACTIVE",
           "account": "urn:li:sponsoredAccount:508915158"
       },
       "urn:li:sponsoredCreative:170811984": {
           "servingHoldReasons": [
               "UNDER_REVIEW",
               "ACCOUNT_SERVING_HOLD"
           ],
           "lastModifiedAt": 1650830101000,
           "lastModifiedBy": "urn:li:system:0",
           "content": {
               "textAd": {
                   "image": "urn:li:image:C4E22AQGX_uq7mQBfAA",
                   "description": "DP2",
                   "headline": "HL2",
                   "landingPage": "https://lnkd.in/eabXpqi"
               }
           },
           "createdAt": 1650830099000,
           "isTest": false,
           "createdBy": "urn:li:person:B1U4S2MZ-C",
           "review": {
               "status": "NEEDS_REVIEW"
           },
           "isServing": false,
           "campaign": "urn:li:sponsoredCampaign:191989474",
           "id": "urn:li:sponsoredCreative:170811984",
           "intendedStatus": "ACTIVE",
           "account": "urn:li:sponsoredAccount:508915158"
       }
   },
   "statuses": {
       "urn:li:sponsoredCreative:170811974": 200,
       "urn:li:sponsoredCreative:170811984": 200
   },
   "errors": {}
}

    Batch Update Text Ads

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

    {
    "entities": {
        "sponsoredCreative-urn1": {
            "patch": {
                "$set": {
                    "content": {
                        "textAd": {
                            "headline": "Updated RGW headline_1",
                            "landingPage": "https://lnkd.in/eabXpqi",
                            "description": "Updated RGW test description_1"
                        }
                    }
                }
            }
        },
        "sponsoredCreative-urn2": {
            "patch": {
                "$set": {
                    "content": {
                        "textAd": {
                            "headline": "Updated RGW headline_2",
                            "landingPage": "https://lnkd.in/eabXpqi",
                            "description": "Updated RGW test description_2"
                        }
                    }
                }
            }
        }
    }
}

    Sample Response

    {
   "results": {
       "urn:li:sponsoredCreative:170811974": {
           "status": 204
       },
       "urn:li:sponsoredCreative:170811984": {
           "status": 204
       }
   },
   "errors": {}
}

    Batch Delete Text Ads

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

    Sample Response

    {
    "results": {
        "urn:li:sponsoredCreative:170811974": {
            "status": 204
        },
        "urn:li:sponsoredCreative:170811984": {
            "status": 204
        }
    },
    "errors": {}
}

    Error Messages

    General creative errors are included here - Creatives error.