Audiences

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 offers a centralized Data Management Platform (DMP) platform that aggregates LinkedIn advertiser data. This enables B2B marketers to identify and reach their target audiences across different platforms and ad exchanges. This platform generates a mapping between user information from LinkedIn advertisers and LinkedIn member profiles. The platform uses this mapping to output a custom audience list in a format that can be used by an ad exchange (for example, LinkedIn) for targeted advertising. The set of APIs to programmatically manage segments, users, companies, and destinations are referred to as DMP Segment APIs.

The use of these APIs is restricted to those developers approved by LinkedIn and subject to applicable data restrictions in their agreements.

DMP Segments APIs

DMP Segments act as staging entities, which can take in user information from a third-party provider, map them to LinkedIn member profiles, and output Ad Segments, which can then be used with other LinkedIn ads APIs.

Use Cases

DMP Segments support two use cases:

• Upload Audience Lists as CSV Files
• Update Audience Lists Dynamically

Upload Audience Lists as CSV Files

Advertisers can upload their data as a CSV list of companies or email addresses to match with LinkedIn company pages or members to create new audience segments for targeting specific accounts within LinkedIn advertising campaigns.

Your application must have an access token with the rw_ads permission to use this API.

See Create and Manage List Uploads for more information.

Update Audience Lists Dynamically

The DMP segments APIs allow you to programmatically and dynamically add or remove users or companies from a DMP Segment using the streaming APIs dmpSegments/id/users and dmpSegments/id/companies. After the initial processing, which could take up to 48 hours, any subsequent addition or removal of users and companies happen in near real-time.

Your application must have an access token with the rw_dmp_segments permission to use DMP Segment APIs. DMP Segment APIs are part of the Audiences program that is separate from the LinkedIn Marketing API Program. Access to the LinkedIn Marketing API Program does not automatically grant access to DMP Segment APIs. Developers must apply separately to be considered for access.

Apply for the Audience Management APIs to be considered for access to these APIs. Note that Campaign Manager does not have this option.

A typical workflow consists of the following steps:

1. Request LinkedIn to provide a sourcePlatform ENUM that your organization can use.
2. Create an empty DMP Segment with some metadata such as account, type and sourcePlatform. When you create the segment, you must define whether you are adding companies or users.
3. Optional: Add Destinations to the segment. If you don't provide a destination, the default is LinkedIn.
4. Add or remove companies or users to the segment using the streaming APIs.
5. Monitor processing status for each segment.
6. When status is READY, the output adSegment can be used with other LinkedIn APIs.
7. To add or remove users or companies from the segment, repeat steps 4-6

To create a DMP Segment and add users or companies, see the following links.

1. Create and Manage Segments
2. Optional: Create and Manage Segment Destinations
3. Create and Manage Segment Users
4. Create and Manage Segment Companies

DMP Segment State Transition

The mapping of users to a destination (ad exchange) is a continuous process and requires a certain workflow. When users are added to a DMP segment, the initial matching process can take up to 48 hours to resolve the IDs into a destination segment. Any subsequent addition or removal of users to or from an existing DMP Segment can take up to 24 hours.

Note

A streaming segment can always be in UPDATING status if user keeps streaming to the segment, although it doesn't affect previously matched members/companies.
Empty segments will now have status updated to READY about 48 hours after creation.

The following diagram outlines the various changes to the states:

A typical state transition can occur in following way:

1. Building: When a segment is first created, the initial state is Building, which means the segment doesn't have anything to serve.
2. Building to Failed: A segment is set to Failed status if a failure happened when uploading lists.
3. Building to Ready: A segment is set to Ready when it's fully available to be used in a campaign. The campaign should be able to serve right away.
4. Ready to Updating: A segment is updated either with a new list or some new users/companies have been streamed to it.
5. Updating to Ready: The updated input is ready to be used in a campaign.
6. Ready to Archived: A segment is not used continuously for 30 days in a draft or active campaign. Streaming updates to an unused segment do not prevent it from being archived.
7. Archived to Building: A segment is updated or added to some active campaign before it gets expired.
8. Archived to Expired: A segment is not used or updated for 90 days continuously. That means 60 more days after it gets archived.
9. Expired to Building: This transition only happens for list upload segments, when an expired segment is updated with a new list.
10. Building to Archived: A segment is not used continuously for 30 days in a draft or active campaign. Streaming updates to an unused segment do not prevent it from being archived.

FAQ

Note

To get better understanding on the integration best practices refer here.

Q: Which segment statuses are allowed in campaign targeting?

Segments with BUILDING, UPDATING, READY or ARCHIVED are allowed to be included/excluded in a campaign's targeting. Archived segments with 0 audience count will not become Ready even after being added to an active campaign.

Q: Which segment statuses are not allowed in campaign targeting?

Segments with EXPIRED, FAILED or ERROR status are not allowed to be included/excluded in a campaign's targeting.

Q: How to find expired segments?

From the Finder API, iterate through all the segments status with expired for a given sponsored account.

FINDER Example for dmpSegments

GET https://api.linkedin.com/rest/dmpSegments?q=account&account=urn:li:sponsoredAccount:516848833

From the response, check the status value from destinations object.

FINDER Example for adSegments

GET https://api.linkedin.com/rest/adSegments?q=accounts&accounts=urn:li:sponsoredAccount:511910281&start=0&count=5

From the response, check the status value for adSegments.

Q: What happens if campaign attempts to use an expired segment?

When a campaign attempts to use a segment that is expired, API returns a 400 error response with a detailed validation message.

Q: Can expired segment be updated again?

Yes. But please note that when an segment is expired, the input and resolved data is purged due to our data retention policy and compliance to GDPR. You can bring a segment back to BUILDING status by uploading another list, or stream new users or companies to it. The segment will be in BUILDING status, but it's essentially a new segment with the same segment ID.

Q: Why is a segment stuck in BUILDING status and not updated?

A segment is considered unused and set to ARCHIVED after it is not continuously used for 30 days in a draft or active campaign. Because of this, a segment may appear "stuck" in BUILDING when updates are streamed to an ARCHIVED segment, thus pushing it into the BUILDING state, and right before it is archived again, new updates are streamed to the unused segment.

Q: What data can be used to match?

Users can be matched with hashed email addresses and other identifiers.

Companies can be matched on companyname, companydomain, and other identifiers.

Q: What hash methods are acceptable for email addresses?

SHA256 and SHA512 are accepted when using the streaming API. CSV uploads accept SHA256 only.

Before hashing, capital letters and whitespace must be removed.

Q: I sent a request to remove a company from my audience segment but it wasn't removed, why?

Ensure that the same metadata sent to add the company is also sent to remove the company. If there is not a high enough confidence that the company attempting to be removed is a match, it will not be removed.

Q: I sent a batch request to add multiple users to my audience segment but the audience size is still 0, why?

If the segment status is in a READY state and the audience size is 0, there are two potential reasons:

• No matches were found.
• There were multiple matches with low relevance scores between match candidates. In this scenario, it is determined that who the advertiser was trying to target was unclear and thus no matches are returned.

Q: Can users be added or removed in batch?

Yes, the DMP Segments Users endpoint allows both batch creation and removal. See DMP Segment Users for more information.

Q: What match feedback/reach projections are available?

Audience size and matched count are returned as documented under DMP Segment Destinations.

Q: What limits exist on audience size?

The minimum audience size that can be used in a campaign is 300.

The maximum size of a CSV list upload is 300,000 hashed email addresses.

Q: How many users can be passed in a single API call?

Up to 5,000 hashed emails can be sent in a single call to DMP Segment Users.

Q: Are DMP Segments viewable in the LinkedIn UI?

Yes, the Matched Audiences page within Campaign Manager has this information.

Q: Is it possible to create multiple DMP Segments with the same name?

Yes, segment names are not required to be unique.

Q: Can DMP Segments be deleted or made inactive?

You can delete DMP Segments and the users, companies, and list uploads added to a DMP Segment. Matches are also automatically removed after 90 days. For details on deleting a DMP segment, see Deleting DMP Segments

Q: Can multiple CSV list uploads be associated with a single DMP Segment?

No, a DMP Segment can only have one list upload.

Q: Can DMP Segments of type "LIST_UPLOAD" receive streamed users or companies?

No, a list upload segment can only receive list uploads.

Q: Are there rate limits on DMP API usage?

Starting October 31, 2022, we will be introducing 1 minute per user (a.k.a member) rate limits for our DMP streaming APIs (Users and Companies to prevent abuse, ensure service stability, and consistent API availability. These limits will be enforced in addition to your current daily limits, which can be found through Developer Portal > My Apps > App > Analytics > Quotas and usage.

For the /users endpoint, an application will have a 1 minute limit of 500 requests per user. This means, that at any given minute, an application can make up to 500 requests on behalf of a single user.

For the /companies endpoint, an application will have a 1 minute limit of 200 requests per user.

If your application calls /dmpSegments/users or /dmpSegments/companies, you may get an HTTP 429 response while calling the endpoints too frequently, indicating that you are exceeding the rate limits.

If your application makes a large amount of automated, bulk data pushes that exceed tens of millions of calls, you can expect to see frequent throttling. While this might affect the throughput of your API calls, you will not see any differences in the matched audience processing SLA.

Q: How do I handle API calls that are rate limited?

Your application should be catching errors when making calls to /dmpSegments/users and /dmpSegments/companies.

Example response for 1 minute per user level throttling.

How to handle? Retry in 1 minute.

{
  "serviceErrorCode": 101,
  "message": "Too Many Requests",
  "status": 429
}

Example response for 24 hour per user level throttling and application level throttling (what is experienced today for daily limits).

How to handle? Slow down the frequency of requests. A common practice is exponential backoff, where the time between requests starts off small (a few seconds, for example), then doubles before each retry. This is continued until a request is successful or a reasonable maximum time between requests is reached (5 minutes, for example).

{
  "serviceErrorCode": 101,
  "message": "Resource level throttle APPLICATION_AND_MEMBER DAY limit for calls to this resource is reached",
  "status": 429
}

{
  "serviceErrorCode": 101,
  "message": "Resource level throttle APPLICATION DAY limit for calls to this resource is reached",
  "status": 429
}

Q: Can I get my application's rate limits increased?

No, the limits we intend to enforce will not be customizable at an application level. However, the limits will be enforced such that there is minimal interruption to existing applications and their users.

Q: Why am I seeing "Audience too small" even when the matched count is more than 300?

Upon processing the matched count, there is another filter that runs to finalize the audience count based on their privacy settings. If the member prefers to opt out of third-party data settings, then these members will be filtered out of the total audience count.