Saved Audience Templates

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

The Saved Audience Templates API lets you create a workflow for users to easily save and retrieve audience templates for targeting in sponsored ad campaigns. These audience templates can be composed of approved targeting criteria made up of LinkedIn Audience Attributes and/or existing Matched Audience AdSegments (contact/company lists), and can be activated through the campaign API or the Campaign Manager user interface.

Note

All API requests are represented in Rest.li Protocol 2.0.0 and require the header: X-Restli-Protocol-Version: 2.0.0. Read the Protocol Versions document to learn more about using Rest.li Protocol 2.0.0.

Glossary

Term Description
Ad Targeting Facets Facets are high-level categories of the types of targeting available. Use facets to narrow down your intended audience. To see the list of available facets and their URNs, refer to Targeting Criteria Facet URNs page.
Audience Audience is a general term used to describe the Targeting Criteria filter selected to view insights. For example, an audience can be "Financial Analysts in the US". Refer targetingCriteria Object to define the audience criteria.
Matched Audience LinkedIn Matched Audience is a set of targeting capabilities that gives you the power to reach your desired audience, including those you already have a relationship with, through website, contact, and company list targeting. Refer Ad Segments to fetch existing matched audience ad segment URNs that can be passed to urn:li:adTargetingFacet:audienceMatchingSegments.

Permissions

There are two conditions for successful Saved Audience Templates API requests:

  • Scope permission accessibility for:

    • rw_ads (read/write)
    • r_ads (read-only)

  • The authenticated Ad Account user that provides consent has one of the following roles on the Ad Account:

    • ACCOUNT_BILLING_ADMIN
    • ACCOUNT_MANAGER
    • CAMPAIGN_MANAGER
    • CREATIVE_MANAGER
    • VIEWER (read-only, even with rw_ads scope)

For more information on Ad Account roles and permissions:

Methods

Method Name Request Type Permission Description
get GET r_ads,rw_ads Get a single AdTargetTemplate given the unique key.
create POST rw_ads Create a single Ad target template and persist the data. The input should not include an ID, as that is a synthetic key which will be supplied by the service.
partial_update POST rw_ads Update one or more fields of this Ad target template via the Patch operation. Other than the read-only fields that cannot be updated there are no other restrictions to this operation.
delete DELETE rw_ads Delete the identified Ad target template.
batch_delete DELETE rw_ads Batch delete Ad target templates using a set of Ad target template IDs.
findByAccount GET r_ads,rw_ads This finder returns a collection of AdTargetTemplates an Ad account can access that match the search parameters.

Create Saved Audience Template

Create a single Saved Audience Template and persist the data. The input should not include an ID, as that is a synthetic key which will be supplied by the service.

Schema

Field Name Type Description Required
account SponsoredAccountUrn URN identifying the sponsored Ad account associated with the saved targeting template; immutable. Refer to Find Ad Accounts by Authenticated User endpoint to fetch and select Ad accounts of the connected user. Yes
targetingCriteria targetingCriteria Object TargetingCriteria is the object that represents an Audience. It provides a generic AND / OR construct to include and exclude different targeting facets when defining an audience. TargetingCriteria defines the audience, for example, members who are skilled in Java and work for ABC company. Yes
name string Name of template generated by the member who created or updated it. The maximum length of the name is 100. Yes
description string Description of the template generated by the member who created or updated it. The maximum length of the description is 500. Optional
approximateMemberCount long Approximate number of members that the Ad targeting template could target. This field is optional for backward compatibility. Note that the member count could be slightly different than actual count. ReadOnly
created AuditStamp An AuditStamp corresponding to the creation of this resource. ReadOnly
lastModified AuditStamp An AuditStamp corresponding to the last modification of this resource/association/sub-resource. If no modification has occurred since creation, lastModified should be the same as created. ReadOnly
id string The auto-generated numeric identifier for the template. ReadOnly

Sample Request

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

{
  "name": "AI Audience Template",
  "description": "Audience interested in AI in tech in NA",
  "account": "urn:li:sponsoredAccount:<account_id>",
  "targetingCriteria": {
    "include": {
      "and": [
        {
          "or": {
            "urn:li:adTargetingFacet:interests": [
              "urn:li:interest:308"
            ]
          }
        },
        {
          "or": {
            "urn:li:adTargetingFacet:industries": [
              "urn:li:industry:6",
              "urn:li:industry:8"
            ]
          }
        },
        {
          "or": {
            "urn:li:adTargetingFacet:interfaceLocales": [
              "urn:li:locale:en_US"
            ]
          }
        },
        {
          "or": {
            "urn:li:adTargetingFacet:locations": [
              "urn:li:country:us",
              "urn:li:country:ca"
            ]
          }
        }
      ]
    },
    "exclude": {
      "or": {
        "urn:li:adTargetingFacet:seniorities": [
          "urn:li:seniority:1",
          "urn:li:seniority:2"
        ]
      }
    }
  }
}

Sample Response

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

Get Saved Audience Template

Get a single Saved Audience Template given the unique template id.

Sample Request

GET https://api.linkedin.com/rest/adTargetTemplates/<template_id>

Sample Response

{
  "approximateMemberCount": 1000,
  "created": {
    "actor": "urn:li:unknown:0",
    "time": 1676657537000
  },
  "name": "AI Audience Template",
  "targetingCriteria": {
    "include": {
      "and": [
        {
          "or": {
            "urn:li:adTargetingFacet:interests": [
              "urn:li:interest:308"
            ]
          }
        },     
        {
          "or": {
            "urn:li:adTargetingFacet:industries": [
              "urn:li:industry:6",
              "urn:li:industry:8"
            ]
          }
        },
        {
          "or": {
            "urn:li:adTargetingFacet:interfaceLocales": [
              "urn:li:locale:en_US"
            ]
          }
        },
        {
          "or": {
            "urn:li:adTargetingFacet:locations": [
              "urn:li:country:us",
              "urn:li:country:ca"
            ]
          }
        }
      ]
    },
    "exclude": {
      "or": {
        "urn:li:adTargetingFacet:seniorities": [
          "urn:li:seniority:1",
          "urn:li:seniority:2"
        ]
      }
    }
  },
  "description": "Saved Audience Template",
  "id": 12345,
  "lastModified": {
    "actor": "urn:li:unknown:0",
    "time": 1676657835000
  },
  "account": "urn:li:sponsoredAccount:12345"
}

Update Saved Audience Template

Update a single Saved Audience Template given the unique key.

Supported schema fields that can be updated

Field Name Type Description
targetingCriteria targetingCriteria Object TargetingCriteria which defines the audience, for example, members who are skilled in Java and work for ABC company.
description string Description of template generated by the member who created or updated it. The maximum length of the description is 500.
name string Name of template generated by member who created or updated it. The maximum length of the name is 100.

Sample Request

POST https://api.linkedin.com/rest/adTargetTemplates/<template_id>
'X-Restli-Method': 'PARTIAL_UPDATE’

{
    "patch": {
        "$set": 
            "name": "New Template Name"
        }
    }
}

Sample Response

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

HTTP/2 204
etag: W/"45"
x-restli-protocol-version: 2.0.0

Delete Saved Audience Template

Delete a single Saved Audience Template given the unique key.

Sample Request

DELETE https://api.linkedin.com/rest/adTargetTemplates/<template_id>

Sample Response

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

HTTP/2 204
etag: W/"45"
x-restli-protocol-version: 2.0.0

Batch Delete Saved Audience Templates

Batch delete multiple Saved Audience Templates given a set of template IDs.

Sample Request

DELETE https://api.linkedin.com/rest/adTargetTemplates?ids=List(<template_id1>, <template_id2>, …, <template_idn>)

Sample Response

{
    "results": {
        "10000001": {
            "status": 204
        },
        "10000002": {
            "status": 204
        }
    },
    "errors": {}
}

Find Saved Audience Templates by Account

This finder returns a collection of Saved Audience Templates an ad account can access that match the search parameters. Only account parameter and sortField parameter are required in the request.

SortField Schema (Enum)

Symbol Description
ID Id of ad targeting template
NAME Name of ad targeting template. Alphabetical sort with no localization.

SortOrder Schema (Enum)

Symbol Description
ASCENDING Sort by ascending order. This is by default
DESCENDING Sort by descending order.

Sample Request

GET https://api.linkedin.com/rest/adTargetTemplates?q=account&account=urn:li:sponsoredAccount:<account_id>&sortField=ID&sortOrder=ASCENDING

Sample Response

{
  "elements": [
    {
      "approximateMemberCount": 0,
      "created": {
        "actor": "urn:li:unknown:0",
        "time": 1676657537000
      },
      "name": "template_name1",
      "targetingCriteria": {
        "include": {
          "and": [
            {
              "or": {
                "urn:li:adTargetingFacet:locations": [
                  "urn:li:country:de"
                ]
              }
            },
            {
              "or": {
                "urn:li:adTargetingFacet:industries": [
                  "urn:li:industry:43"
                ]
              }
            },
            {
              "or": {
                "urn:li:adTargetingFacet:interfaceLocales": [
                  "urn:li:locale:en_US"
                ]
              }
            }
          ]
        },
        "exclude": {
          "or": {
            "urn:li:adTargetingFacet:industries": [
              "urn:li:industry:20"
            ]
          }
        }
      },
      "description": "Saved Audience Template",
      "id": 12345,
      "lastModified": {
        "actor": "urn:li:unknown:0",
        "time": 1676657835000
      },
      "account": "urn:li:sponsoredAccount:12345"
    },
    {
      "approximateMemberCount": 0,
      "created": {
        "actor": "urn:li:unknown:0",
        "time": 1676657537000
      },
      "name": "template_name2",
      "targetingCriteria": {
        "include": {
          "and": [
            {
              "or": {
                "urn:li:adTargetingFacet:locations": [
                  "urn:li:country:de",
                  "urn:li:country:lu",
                  "urn:li:country:ca"
                ]
              }
            },
            {
              "or": {
                "urn:li:adTargetingFacet:industries": [
                  "urn:li:industry:43",
                  "urn:li:industry:46"
                ]
              }
            },
            {
              "or": {
                "urn:li:adTargetingFacet:interfaceLocales": [
                  "urn:li:locale:en_US"
                ]
              }
            }
          ]
        },
        "exclude": {
          "or": {
            "urn:li:adTargetingFacet:industries": [
              "urn:li:industry:30"
            ]
          }
        }
      },   
      "description": "Saved Audience Template",
      "id": 12346,
      "lastModified": {
        "actor": "urn:li:unknown:0",
        "time": 1676657835000
      },
      "account": "urn:li:sponsoredAccount:12346"
    }
  ]
}

API Error Details

HTTP CODE ERROR MESSAGE DESCRIPTION
400 Parameter 'account' is required Missing required field in the request
400 Parameter 'sortField' is required Missing required field in the request
404 Cannot find entity to update Template to update does not exist
404 Key not found: 000 Template to delete does not exist
422 account::CreateOnly field present in a partial_update request CreateOnly field could not be updated, account field should not be used in update request