Predictive Audiences API

Warning

Deprecation Notice: The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026. 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.

Permissions

Permission Description
rw_dmp_segments Access an authenticated member's DMP Segments with the ability to read and manage audience DMP segments.

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. Accepted value: AUTO_TARGETING (signifies that auto-targeting is active for campaigns).
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.

targetingCriteria provides a generic AND / OR construct to include and exclude different adTargetingFacets when defining the audience.

For more information, see:

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

Update Predictive Audience by ID

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