Matched Audiences
Contact lists, company lists, engagement retargeting, and website retargeting
Matched Audiences
Four LinkedIn audience types, all through POST /v1/ads/audiences, discriminated by type. adAccountId is the numeric LinkedIn sponsored account id.
type | Built from |
|---|---|
customer_list | Emails you upload (SHA-256 hashed server-side) |
company_list | Company names / domains / LinkedIn page URLs |
engagement | People who engaged with your ads, pages, or events |
website_retargeting | Insight Tag visitors matching URL rules |
Contact list
Create the (empty) list-upload segment, then upload members. Email only (any phone is ignored); values are SHA-256 hashed server-side.
// 1. Create the (empty) list-upload segment
await zernio.adaudiences.createAdAudience({
body: {
accountId: 'acc_linkedinads_123',
adAccountId: '517258773',
type: 'customer_list',
name: 'Webinar attendees',
},
});
// 2. Upload the member list (full replace each call)
await zernio.adaudiences.addUsersToAdAudience({
path: { audienceId: 'aud_abc123' },
body: { users: [{ email: 'jane@example.com' }, { email: 'sam@example.com' }] },
});client.ad_audiences.create_ad_audience(
account_id="acc_linkedinads_123",
ad_account_id="517258773",
type="customer_list",
name="Webinar attendees",
)
client.ad_audiences.add_users_to_ad_audience(
audience_id="aud_abc123",
users=[{"email": "jane@example.com"}, {"email": "sam@example.com"}],
)curl -X POST "https://zernio.com/api/v1/ads/audiences" \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "accountId": "acc_linkedinads_123", "adAccountId": "517258773", "type": "customer_list", "name": "Webinar attendees" }'
curl -X POST "https://zernio.com/api/v1/ads/audiences/AUDIENCE_ID/users" \
-H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{ "users": [{ "email": "jane@example.com" }, { "email": "sam@example.com" }] }'Each upload is a full replace, not an append: send the complete member list every time.
Company list
Target (or exclude) specific companies, up to 300,000 rows. Each row needs at least one of name, domain, website, linkedinPageUrl:
{
"type": "company_list",
"accountId": "...", "adAccountId": "517258773", "name": "Target ICP Q3",
"companies": [
{ "name": "Microsoft", "domain": "microsoft.com" },
{ "linkedinPageUrl": "https://www.linkedin.com/company/linkedin" }
]
}Engagement retargeting
People who interacted with your ads, pages, or events:
{
"type": "engagement",
"accountId": "...", "adAccountId": "517258773", "name": "Video Q1 viewers",
"sourceType": "VIDEO_ADS",
"trigger": "FIRST_QUARTILE",
"lookbackDays": 90,
"engagementSources": ["urn:li:sponsoredCampaign:777301293"]
}| Field | Notes |
|---|---|
sourceType | VIDEO_ADS, LEAD_GEN_FORMS, ORGANIZATION_PAGES, EVENT_PAGES, SINGLE_IMAGE_ADS |
trigger | The action, e.g. FIRST_QUARTILE, VIEW, CTA_CLICK, LEAD_FORM_SUBMIT. LinkedIn validates the pairing with sourceType. |
lookbackDays | 30 / 60 / 90 / 180 / 365 |
engagementSources[] | Campaign URNs for ad sources, organization URNs for pages and events. Max 50. |
This is LinkedIn's engagement type. Meta's engagement audiences are a different type (meta_engagement) with different fields, documented on Meta Ads. Using either type on the wrong platform's account returns a 422.
Website retargeting
Visitors matching URL rules, fed by the LinkedIn Insight Tag:
{
"type": "website_retargeting",
"accountId": "...", "adAccountId": "517258773", "name": "Pricing page visitors",
"matchRules": [
{ "matchType": "STARTS_WITH", "matchValue": "https://zernio.com/pricing" },
{ "matchType": "EXACT", "matchValue": "zernio.com" }
]
}matchType:EXACT,STARTS_WITH,CONTAINS,ENDS_WITH. Up to 50 rules.- The segment only starts filling once the customer's site has the Insight Tag installed and reporting visits; creating the chain doesn't require the tag, delivery does.
- The returned
platformAudienceIdis a real LinkedIn adSegment id, usable downstream (attach to a campaign, seed a lookalike). Retargeting segments appear inGET /v1/ads/audiencesonce LinkedIn finishes building them.
Managing segments
GET /v1/ads/audiences lists them, DELETE /v1/ads/audiences/{audienceId} deletes. Audience builds are eventually consistent on LinkedIn's side: a members read issued right after an upload can come back empty; re-read after a minute rather than retrying the upload.