Lesson 04 · outer fringe

Matched Audiences

Your customer's own data, turned into something targetable. Two entities, one pipeline, a state machine that expires behind your back — and a separate API program you have to apply for.

≈15 min · pinned to li-lms-2026-08

What it is

Every facet you met in Lesson 03 targets attributes LinkedIn knows: job title, employer, seniority. Matched Audiences is the mechanism for targeting attributes your customer knows: their CRM contacts, their target account list, the people who visited their pricing page.

The mechanism is identity resolution. You hand LinkedIn a list of email addresses or company names; LinkedIn matches them against member profiles and company pages; you get back an opaque audience you can target but never read. You cannot ask "who matched" — that is the privacy boundary, and it is absolute.

Two entities, not one

This is the core of the vocabulary, and it is the thing you cannot guess.

DMP is Data Management Platform. The asymmetry is the whole design: you own the input side, LinkedIn owns the output side. The Ad Segment is created for you when matching completes, and it arrives in an unexpected place — nested inside the DMP Segment's destinations array, under the key destinationSegmentId:

GET /rest/dmpSegments/11204
{
  "id": 11204,
  "name": "Test DMP Segment 2",
  "account": "urn:li:sponsoredAccount:516848833",
  "type": "USER",
  "sourcePlatform": "PARTNER_API",
  "destinations": [{
    "status": "BUILDING",
    "destinationSegmentId": "urn:li:adSegment:848336"   // ← the targetable thing
  }]
}

Note what this implies: the status you care about is not on the segment, it is on the destination. A "destination" is an ad exchange — and today the only accepted value is LINKEDIN. So the array always has one element and the nesting buys you nothing. It exists because the platform was designed to fan out to multiple exchanges. Write your accessor to handle the general case anyway; a hardcoded destinations[0] is the kind of shortcut that survives until it doesn't.

The three ways in

Same two entities, three different input mechanisms — distinguished by type and sourcePlatform on the DMP Segment.

Two details in that table deserve attention.

First, CSV list upload uses rw_ads — the scope you already have. It sits inside the Matched Audiences docs but does not need the Matched Audiences scope. If you want first-party list targeting before your rw_dmp_segments application clears, this is the path.

Second, sourcePlatform is a declaration about what kind of business you are, and you must pick correctly:

Targeting it: the two-facet trap

Lesson 03 left you with a puzzle — two different facets with an identical value type:

urn:li:adTargetingFacet:audienceMatchingSegments   → urn:li:adSegment:10001
urn:li:adTargetingFacet:dynamicSegments           → urn:li:adSegment:10001

Here is the rule. The split is by provenance, not by type:

And the restrictions from Lesson 03 land squarely here: website retargeting segments may not be AND'ed with any clause targeting member behaviour or interests. So "people who visited our pricing page AND are interested in DevOps" is not expressible. Two facets, two different restriction profiles, one URN type.

The state machine

Segments are not static rows. They age, and they expire without you touching them.

stateDiagram-v2
  [*] --> BUILDING: create
  BUILDING --> READY: matched (up to 48h)
  BUILDING --> FAILED: list upload failed
  READY --> UPDATING: new list or streamed changes
  UPDATING --> READY: up to 24h
  READY --> ARCHIVED: 30 days unused
  BUILDING --> ARCHIVED: 30 days unused
  ARCHIVED --> BUILDING: added to an active campaign
  ARCHIVED --> EXPIRED: 90 days total unused
  EXPIRED --> BUILDING: new list upload only

Four things in there matter more than the diagram:

• Up to 48 hours for the initial match, up to 24 hours for subsequent changes. This is not a request/response API — it is a job queue with a two-day tail. Your UX has to say so.
• "Unused" means not in a draft or active campaign. Streaming updates do not count as use. You can faithfully sync a segment every hour for thirty days and watch it archive anyway, because nothing ever targeted it.
• The EXPIRED → BUILDING edge exists only for list-upload segments. An expired streaming segment is terminal — you must create a new one and re-push everything. Whether your recovery path is "upload a file" or "replay the whole audience" depends on a choice you made at create time.
• A streaming segment can sit in UPDATING permanently if you keep writing to it. Do not write a health check that waits for READY; it may never arrive, and previously matched members are serving fine regardless.

Limits and deletion

As of August 2026 a sponsored account is capped at 1,000 DMP segments, across Matched Audiences and Predictive Audiences combined. Exceeding it returns 429 with code SEGMENT_LIMIT_EXCEEDED.

This is recent and it is a real constraint for a platform product. If your design creates a segment per campaign, or per sync run, you will hit 1,000 on a large customer. Segments are a scarce, account-scoped resource — reuse them.

Deletion cascades, and it cascades further than you would expect:

DELETE /rest/dmpSegments/{id}
  → deletes the DMP segment
  → deletes its destinations
  → deletes the corresponding adSegment
  → deletes the uploaded list, if any

Deleting the staging entity destroys the targetable audience. But there is a guard: if the adSegment is in use by an active campaign, the delete fails with a 400. And you need write access to the owning sponsored account, or you get 403. So a "clean up old segments" job must handle both — and it is exactly the job you will need, given the 1,000 cap.

Predictive Audiences

Worth naming because it is the answer to a question Lesson 01 left open. You asked about Lookalike Audiences; LinkedIn's counterpart is Predictive Audiences — you supply a seed (contact list or company list), LinkedIn's model extends it to members likely to convert. Same rw_dmp_segments scope, same 1,000-segment budget, and it produces an ordinary adSegment you target like any other.

Practice

{  "name": "Acme CRM — marketing qualified",  "account": "urn:li:sponsoredAccount:516848833",  "type": "USER",  "sourcePlatform": "LIST_UPLOAD",  "destinations": [{ "destination": "LINKEDIN" }]}

const seg = await getDmpSegment(id);const audience = `urn:li:adSegment:${seg.id}`;if (seg.destinations[0].status === 'READY') {  await addToCampaignTargeting(campaignId, audience);}

{  "name": "Acme — tier 1 target accounts",  "account": "urn:li:sponsoredAccount:516848833",  "type": "COMPANY",  "sourcePlatform": "PARTNER_API",  "sourceSegmentId": "acme/tier1/v3"}

Retaining this

1. Start the Matched Audiences application now, ahead of the code. It is the only item in this whole path that is gated on someone else's calendar.
2. Two entities, one pipeline: dmpSegment is what you write, adSegment is what you target, and the second is nested inside the first as destinationSegmentId. If you retain one sentence, retain that one.
3. Tomorrow, draw the state machine from memory with just the numbers on the edges — 48h, 24h, 30d, 90d. Then ask yourself which single edge only exists for list uploads. That question is the whole lesson compressed.

Sources: Matched Audiences Overview, DMP Segments, Targeting Criteria Facet URNs, version li-lms-2026-08.