Predictive Audiences API

Warning

Deprecation Notice: The Marketing Version 202507 (Marketing July 2025) has been sunset. We recommend that you migrate to the latest versioned APIs to avoid disruptions. For information on all the supported versions, refer to the migrations documentation. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Try in Postman

Predictive Audiences allow customers to combine their first-party or third-party data with LinkedIn's predictive AI modeling to build a high-intent audience tailored just for their business. LinkedIn's AI combines millions of engagement signals with the customer's data to identify members who are most likely to convert based on the customer's business objectives. Customers can select from company list or contact list as the data source and predictive audiences predicts the likelihood of our members to convert for a given customer, using the customer's own data as the input (think behavioral + lookalike). The most relevant members are then made available as an audience segment customers can target.

Note

Predictive Audience API is available as part of the Matched Audiences private API program. To request access, please complete the interest form here. LinkedIn will contact you up to 60 days after the form submission only if we identify meeting access criteria and a strong partnership fit. Make sure you have access to Advertising API first, before submitting the form as it's an obligatory pre-requisite. You can learn more about Advertising API application here.

Permissions

Permission Description
rw_dmp_segments Access an authenticated member's DMP Segments with the ability to read and manage audience DMP segments. This permission is a part of the Audiences program and is not automatically granted under the LinkedIn Marketing API Program.
Managing audiences is restricted to ad accounts where the authenticated member has a role other than VIEWER.

Schemas

Predictive Audience

Schema for predictive audience, which is a type of matched audience created using predictive modeling based on business objectives defined by the advertiser.

Property Type Read-only Required Description
id long Yes No The unique identifier (Predictive Audience ID) of the predictive audience. This field is set by the system and is ignored on create and partial update requests. Returned by the retrieve and list operations when LinkedIn-Version is 202607 or later.
created long Yes No The epoch timestamp in milliseconds at which one created the predictive audience.
lastModified long Yes No The epoch timestamp in milliseconds at which one most recently updated the predictive audience.
deleted long Yes No The epoch timestamp in milliseconds at which one deleted the predictive audience.
dmpSegmentId long Yes Yes The ID of the predictive audience's parent data management platform (DMP) segment.
seeds array[Urn] No Yes The seeds from which the predictive audience sprouts. Acceptable types of seeds include conversions (e.g. urn:lla:llaPartnerConversion:1), matched audience contact or company upload segments (e.g. urn:li:dmpSegment:123), and ad leadgen forms (e.g. urn:li:adForm:1231).
desiredAudienceCount long No No The number of members the advertiser aims for in the targetable matched audience segment. The advertiser could specify this value in creating the predictive audience, or after the recommended audience size is calculated by the system. If the advertiser doesn't specify a desired audience count, the system will use the size from the recommendedAudienceCount field.
recommendedAudienceCount long Yes No The recommended number of members in the targetable matched audience segment which finds a good balance between audience reach and campaign performance. This field is set by the system and cannot be set or changed by the client. This field will be null if there is no recommended audience count available. This can occur if the system is still processing an audience count to recommend or if the system can't generate a recommendation due to poor input data.
targetingFilter TargetingCriteria No Yes The targeting filter advertiser selects to build the predictive audience segment.
audienceAutomation AudienceAutomation Yes No The audience automation from which this audience is created (e.g. predictive audiences created from an Optima campaign). It is undefined for audiences not created from audience automation.
companyExpansionMultiplier int No No The company expansion multiplier for the company seeds, representing their expansion factor. For example, if the company expansion multiplier is 2, with the seeds consisting of 10 companies, the expansion output will have 20 companies. This field is only applicable to company seeds and will be validated with a valid range supported.

TargetingCriteria

Schema for targeting criteria for an advertising campaign, using a boolean expression identifying which members are included, and optionally excluded.

Note: A geo filter must be present in the targeting criteria for predictive audiences to build correctly. Currently, the targeting criteria only supports geo filtering.

Property Type Required/Optional Description
include TargetingAnd Required Specifies targeting criteria that the member must match, using a boolean expression in the form of a conjunction of disjunctions.
exclude TargetingOr Optional Specifies targeting criteria that the member must not match, using a boolean expression in the form of a disjunction.

TargetingAnd

This schema represents a conjunction of disjunctions.

Property Type Required/Optional Description
and array[TargetingOr] Required The disjunctions to conjunct.

TargetingOr

This schema represents a disjunction of conditions on members.

Property Type Required/Optional Description
or map[string, array[string]] Required Each element, a mapping from facet URN to targeting values, represents one of the disjuncts. For example "urn:li:adTargetingFacet:skills": ["urn:li:skill:200"] is a predicate that is true if a member possesses the skill with ID 200.

AudienceAutomation

This is an enumeration of values described below.

Value Description
AUTO_TARGETING Signifies that auto-targeting is active for campaigns.

Create Predictive Audience

Creates a new predictive audience. Returns the ID of the created predictive audience.

Sample Request

In this request, 12345 is the ID of the parent DMP segment. Please refer to DMP Segment API for more information on creating and managing DMP segments.

POST https://api.linkedin.com/rest/dmpSegments/12345/businessObjectiveBasedAudiences

{
  "targetingFilter": {
    "include": {
      "and": [
        {
          "or": {
            "urn:li:adTargetingFacet:locations": [
              "urn:li:countryGroup:AS"
            ]
          }
        }
      ]
    },
    "exclude": {
      "or": {
        "urn:li:adTargetingFacet:skills": [
          "urn:li:skill:200"
        ]
      }
    }
  },
  "desiredAudienceCount": 100,
  "seeds": [ "urn:li:dmpSegment:12345" ]
}

Sample Response

In this response, 67890 is the ID of the created Predictive Audience.

HTTP/2 201
content-length: 0
x-restli-protocol-version: 2.0.0
x-linkedin-id: 67890
location: /dmpSegments/12345/businessObjectiveBasedAudiences/67890

Retrieve Predictive Audience by ID

Retrieves a predictive audience by its unique ID.

Sample Request

In this request, 12345 is the ID of the parent DMP segment, and 67890 is the ID of the Predictive Audience to fetch.

GET https://api.linkedin.com/rest/dmpSegments/12345/businessObjectiveBasedAudiences/67890

Sample Response

Note

The id field (Predictive Audience ID) is returned when LinkedIn-Version is 202607 or later.

HTTP/2 200
content-length: 340
x-restli-protocol-version: 2.0.0
content-type: application/json

{
    "id": 67890,
    "targetingFilter": {
        "include": {
            "and": [
                {
                    "or": {
                        "urn:li:adTargetingFacet:locations": [
                            "urn:li:countryGroup:AS"
                        ]
                    }
                }
            ]
        }
    },
    "created": 1740775557000,
    "dmpSegmentId": 12345,
    "seeds": [
        "urn:li:dmpSegment:84735"
    ],
    "versionTag": "1",
    "lastModified": 1740775557000,
    "desiredAudienceCount": 100
}

List All Predictive Audiences

Retrieves all predictive audiences under a given parent DMP segment as a paginated collection.

Sample Request

In this request, 12345 is the ID of the parent DMP segment. Use the count and start query parameters to paginate through results.

GET https://api.linkedin.com/rest/dmpSegments/12345/businessObjectiveBasedAudiences?count=10&start=0

Sample Response

Note

The id field (Predictive Audience ID) is returned for each element when LinkedIn-Version is 202607 or later.

HTTP/2 200
content-type: application/json
x-restli-protocol-version: 2.0.0

{
    "paging": {
        "count": 10,
        "start": 0,
        "total": 2,
        "links": []
    },
    "elements": [
        {
            "id": 67890,
            "dmpSegmentId": 12345,
            "created": 1740775557000,
            "lastModified": 1740775557000,
            "seeds": [
                "urn:lla:llaPartnerConversion:336212"
            ],
            "desiredAudienceCount": 50000,
            "recommendedAudienceCount": 48000,
            "targetingFilter": {
                "include": {
                    "and": [
                        {
                            "or": {
                                "urn:li:adTargetingFacet:locations": [
                                    "urn:li:countryGroup:US"
                                ]
                            }
                        }
                    ]
                }
            }
        },
        {
            "id": 67891,
            "dmpSegmentId": 12345,
            "created": 1740862000000,
            "lastModified": 1740862000000,
            "seeds": [
                "urn:li:dmpSegment:789"
            ],
            "desiredAudienceCount": 100000,
            "recommendedAudienceCount": 95000,
            "targetingFilter": {
                "include": {
                    "and": [
                        {
                            "or": {
                                "urn:li:adTargetingFacet:locations": [
                                    "urn:li:countryGroup:EU"
                                ]
                            }
                        }
                    ]
                }
            }
        }
    ]
}

PARTIAL_UPDATE

Applies the given patch to the predictive audience to which the given ID maps. Note that this patch must be devoid of any properties marked as read-only in the predictive audience schema above.

Sample Request

In this request, 12345 is the ID of the parent DMP segment, and 67890 is the ID of the predictive audience to update. This patch sets the predictive audience's company expansion multiplier to 3.

POST https://api.linkedin.com/rest/dmpSegments/12345/businessObjectiveBasedAudiences/67890

{
  "patch": {
    "$set": {
      "companyExpansionMultiplier": 3
    }
  }
}

Sample Response

HTTP/2 204
x-restli-protocol-version: 2.0.0

Delete Predictive Audience

Deletes the predictive audience to which the given ID maps.

Sample Request

In this request, 12345 is the ID of the parent DMP segment, and 67890 is the ID of the predictive audience to delete.

DELETE https://api.linkedin.com/rest/dmpSegments/12345/businessObjectiveBasedAudiences/67890

Sample Response

HTTP/2 204
x-restli-protocol-version: 2.0.0

Error Details

The table below lists commonly encountered errors when using the Predictive Audiences API.

Code Message Description
400 sourcePlatform cannot be set to XYZ A Predictive Audience can only be created in a DMP Segment where the sourcePlatform is set to LINKEDIN_BUSINESS_OBJECTIVE_BASED_AUDIENCES.
403 No WRITE access to {sponsored account URN}. Viewer is not present or user is not authorized to perform dmp segment write operations within the ad account.
403 No READ access to {sponsored account URN}. Viewer is not present or user is not authorized to perform dmp segment read operations within the ad account.
404 Entity with key {predictive audience ID} is not found. Predictive audience of the provided ID in the path doesn't exist.
404 Entity with key {dmpSegmentId} is not found. The parent DMP segment specified in the path does not exist.
  • Last updated on