LinkedIn Ads Integration

What It Does

The LinkedIn Ads integration connects ILLIXIS to LinkedIn's Marketing API, allowing you to sync retargeting audiences as DMP Segments (Matched Audiences), create ad campaigns, and generate AI-written ad copy optimized for B2B professionals -- all without leaving the platform.

ILLIXIS handles the full ad creation pipeline: Campaign Group, Campaign, and Creative. Everything is created in a PAUSED state so you can review, set your budget, and activate in LinkedIn Campaign Manager. The integration also monitors your GA4 traffic data and sends notifications when articles qualify for LinkedIn retargeting, prompting you to create audiences targeting those readers.

Unlike Meta, LinkedIn supports refresh tokens. Access tokens are valid for 60 days and refresh tokens for 365 days. ILLIXIS refreshes your access token automatically before it expires, so you rarely need to re-authorize manually.

Prerequisites

| Requirement | Where to Get It | Why It's Needed |
|-------------|-----------------|-----------------|
| LinkedIn Campaign Manager account | linkedin.com/campaignmanager | Required for ad management access |
| Ad Account (numeric ID) | Campaign Manager > Account Assets | Container for campaigns and creatives; used in URN format internally |
| LinkedIn Insight Tag installed on your website | Campaign Manager > Account Assets > Insight Tag | Tracks website visitors for DMP Segment (Matched Audience) creation |
| Company Page (Organization) | Your LinkedIn Company Page admin | Required for Sponsored Content -- every ad references your Organization URN |
| Marketing Developer Platform approval | LinkedIn Developer Portal | LinkedIn requires app-level approval for Marketing API scopes |

Your Ad Account ID is a numeric value (e.g., 123456789). Internally, ILLIXIS converts this to LinkedIn's URN format (urn:li:sponsoredAccount:123456789) for all API calls. You never need to enter the URN yourself.

Connecting Your Account

1. Go to Settings > Integrations and find the LinkedIn section (under Advertising).
2. Click Connect LinkedIn.
3. You are redirected to LinkedIn. Sign in if prompted.
4. LinkedIn shows a consent screen requesting these permissions:

| Scope | Purpose |
|-------|---------|
| r_ads | Read ad accounts and campaigns |
| r_ads_reporting | Read campaign analytics |
| rw_ads | Create and manage ads targeting existing audiences |
| w_organization_social | Create Direct Sponsored Content (ad-only posts on your Company Page) |

5. Click Allow to authorize.
6. ILLIXIS exchanges the authorization code for an access token (valid 60 days) and a refresh token (valid 365 days).
7. You are redirected to the Account Selection page.
8. Select your Ad Account from the dropdown. If your account does not appear, enter the Ad Account ID manually (numeric format, e.g., 123456789).
9. ILLIXIS detects Insight Tags (conversion tracking accounts) associated with the selected ad account and lists them. Select the correct one if you have multiple.
10. Click Save. The connection is now active.

After connecting, go to Settings > Integrations > LinkedIn and enter your Organization (Company Page) ID. This is required before you can create Sponsored Content ads. The Organization ID is the numeric ID of your LinkedIn Company Page (visible in your Company Page URL or admin settings).

Note on rw_dmp_segments scope: ILLIXIS does not request the rw_dmp_segments scope. Instead, it uses a hybrid workflow: you create DMP Segments (Matched Audiences) manually in LinkedIn Campaign Manager, then paste the URN back into ILLIXIS. This avoids the additional LinkedIn approval process for DMP segment creation. Alternatively, if your app does have this scope, ILLIXIS can create audiences programmatically via the audience sync feature.

Syncing Audiences

ILLIXIS creates DMP Segments (Matched Audiences) in LinkedIn from your existing retargeting audiences. These are website-traffic audiences built using your Insight Tag, matching URL patterns that correspond to your content topics.

How Audience Sync Works

1. ILLIXIS analyzes your content clusters and builds URL-pattern rules (e.g., pages containing content-marketing or seo-strategy in the path).
2. These rules are translated to LinkedIn URL match rules using CONTAINS string matching.
3. The rules are sent to LinkedIn's DMP Segments API, attached to your Insight Tag with a lookback window (default: 90 days, maximum: 180 days).
4. LinkedIn populates the audience with visitors matching those URL patterns over the retention window.
5. The audience is marked as "synced" in ILLIXIS with a linkedin_audience_urn.

Filter Rule Translation

ILLIXIS translates its internal filter format to LinkedIn's URL match rules:

| ILLIXIS Format | LinkedIn API Format |
|----------------|---------------------|
| page_path_keywords: ['content-marketing', 'seo'] | Multiple urlMatchRuleInput entries with stringMatchType: CONTAINS (OR logic) |
| page_path_contains: '/blog/guide' | Single urlMatchRuleInput with stringMatchType: CONTAINS |
| page_path_regex: '.*marketing.*' | Simplified to CONTAINS (LinkedIn does not support regex directly) |

If no rules are specified, a broad audience matching all Insight Tag visitors is created.

Triggering a Sync

All audiences: Go to Advertising and click Sync to LinkedIn. This pushes all unsynced audiences to LinkedIn.

Single audience: On any audience detail page, click Sync to LinkedIn to push just that audience.

Hybrid Workflow (Manual Audience Creation)

If you prefer to create audiences directly in LinkedIn Campaign Manager:

1. Create a Matched Audience in Campaign Manager using your Insight Tag.
2. Copy the audience URN (format: urn:li:dmpSegment:1234567890).
3. In ILLIXIS, click Link LinkedIn Audience and paste the URN.
4. ILLIXIS creates a RetargetingAudience record linked to that URN, enabling the ad creation pipeline.

Audience Statuses

| Status | Meaning |
|--------|---------|
| Not Synced | Audience exists in ILLIXIS only; not yet pushed to LinkedIn |
| Syncing | Sync in progress (background task running) |
| Synced | Live in LinkedIn Campaign Manager as a DMP Segment |
| Error | Sync failed; check error message for details |

Creating Ads

Once an audience has a LinkedIn URN (either synced or manually linked), you can create a full ad directly from ILLIXIS.

Ad Creation Pipeline

ILLIXIS creates three objects in your LinkedIn Ad Account, all in PAUSED/DRAFT state:

| Step | Object | Naming | Notes |
|------|--------|--------|-------|
| 1 | Campaign Group | [ILLIXIS] {Content Title} - {Date} | Container for campaigns |
| 2 | Campaign | [ILLIXIS] {Content Title} Campaign | Targeting, budget (USD 10/day default), objective (WEBSITE_VISIT), CPM bidding, auto-bid |
| 3 | Creative | Sponsored Content (via UGC post) | Headline, description, destination URL, optional image |

The creative is built by first creating a share (UGC post) on your Company Page, then referencing it in the creative. The share is deleted from your Company Page after the creative is created -- the ad still works because LinkedIn caches the content.

Step 1: Open the Ad Creator

On the audience detail page, click Create LinkedIn Ad. ILLIXIS loads:

• AI-generated ad copy (headline and description)
• A CTA selector
• A destination URL field
• A preview image (if linked content has a featured image)

Step 2: Review and Edit Ad Copy

ILLIXIS generates ad copy optimized for LinkedIn's B2B professional audience. The copy uses your brand voice settings and follows LinkedIn ad best practices. You can:

• Edit the headline and description directly
• Regenerate the copy by clicking the regenerate button (produces a fresh variation, avoiding the previous version)
• Save as draft to return later without pushing to LinkedIn

Character limits enforced by the system:

| Field | Maximum Length | Recommended Length |
|-------|---------------|--------------------|
| Headline | 200 characters | 70 characters |
| Description | 600 characters | 100 characters |

Step 3: Select a CTA

Choose the call-to-action button for your ad:

| CTA Value | Button Text | Best For |
|-----------|-------------|----------|
| LEARN_MORE | Learn More | Educational content, guides, blog posts |
| SIGN_UP | Sign Up | Lead generation, newsletter, webinar registration |
| DOWNLOAD | Download | Whitepapers, ebooks, templates |
| APPLY | Apply | Job postings, program applications |
| REQUEST_DEMO | Request Demo | SaaS products, enterprise software |
| SUBSCRIBE | Subscribe | Ongoing content, newsletter |
| GET_QUOTE | Get Quote | Custom pricing, B2B services |

Step 4: Set Destination URL

Enter the URL where users land after clicking your ad. If linked content has a published URL, it is pre-filled. The URL must be set before the ad can be created.

Step 5: Push to LinkedIn

Click Create Ad. After creation, ILLIXIS stores the campaign group URN, campaign URN, and creative URN on the audience record. You get a link to LinkedIn Campaign Manager to review, adjust budget, and activate.

Ad Draft System

You do not have to create the ad immediately. The draft system lets you:

• Save headline, description, CTA, and destination URL as a draft
• Return later to the same audience and your draft is preserved
• Regenerate copy without losing your draft
• Push the draft to LinkedIn when ready

Campaign Types and Objectives

Retargeting Campaigns

The default for audiences synced from content clusters. Uses WEBSITE_VISIT objective, targeting your DMP Segment (Matched Audience).

| Setting | Default Value |
|---------|--------------|
| Objective | WEBSITE_VISIT |
| Daily Budget | USD 10.00 |
| Cost Type | CPM |
| Optimization | MAX_CLICK |
| Audience Expansion | Disabled |
| Offsite Delivery | Disabled |
| Status | DRAFT (must be activated in Campaign Manager) |

Prospecting Campaigns

ILLIXIS supports three prospecting campaign objectives for reaching new audiences:

| Objective | API Value | Optimization Target | Use Case |
|-----------|-----------|---------------------|----------|
| Website Visit | WEBSITE_VISIT | MAX_CLICK | Drive traffic to content or landing pages |
| Brand Awareness | BRAND_AWARENESS | MAX_IMPRESSION | Maximize reach and impressions |
| Engagement | ENGAGEMENT | SOCIAL_ACTIONS | Drive likes, comments, shares |

Prospecting campaigns support combining audience targeting with professional targeting facets (see B2B Targeting below).

Ad Formats

The default ad format is Sponsored Content -- a single-image feed post that appears in the LinkedIn feed. The creative includes:

• Commentary text (your description)
• Article link with title and description
• Optional thumbnail image
• CTA button

For Message Ads (InMail), Text Ads, Lead Gen Forms, or other formats, create the initial campaign through ILLIXIS and then edit the format in LinkedIn Campaign Manager.

B2B Professional Targeting

LinkedIn's strongest differentiator is its professional targeting capabilities. After creating a campaign, you can layer targeting facets to reach specific professional audiences.

Available Targeting Facets

| Facet | API Facet Name | Example Values | Use Case |
|-------|----------------|----------------|----------|
| Job Title | urn:li:adTargetingFacet:titles | VP of Marketing, CMO, Data Analyst | Target specific decision-makers |
| Industry | urn:li:adTargetingFacet:industries | Software, Financial Services, Healthcare | Reach specific verticals |
| Company Size | urn:li:adTargetingFacet:staffCountRanges | 1-10, 51-200, 1001-5000 | Target by company size |
| Seniority | urn:li:adTargetingFacet:seniorities | Director, VP, C-Suite, Manager | Filter by seniority level |
| Company (ABM) | urn:li:adTargetingFacet:employers | Specific organization URNs | Target employees at named companies |

Targeting facets use AND logic between categories and OR logic within a category. For example: (VP of Marketing OR CMO) AND (Software OR SaaS) AND (51-200 employees).

Facet Search

ILLIXIS provides a search API for discovering targeting facet values. Search by keyword to find URNs for job titles, industries, skills, or employers, along with their display names.

Account-Based Marketing (ABM)

Target employees at specific companies by adding company URNs to your campaign targeting. This is useful for:

• Targeting prospects at named accounts in your sales pipeline
• Reaching decision-makers at competitor companies
• Running campaigns against a custom account list

Lookalike Audiences (Predictive Audiences)

Create a Lookalike Audience from an existing DMP Segment to find similar professionals:

• Seed segment must have at least 300 members
• LinkedIn calls these "Predictive Audiences"
• Specify the country for audience expansion
• Created via the dmpSegments API with type: LOOKALIKE

Retargeting Opportunity Notifications

ILLIXIS automatically monitors your GA4 traffic data and notifies you when published articles reach the threshold for LinkedIn retargeting.

How It Works

1. A daily automated task checks all published content with URLs.
2. Articles with pageviews at or above the threshold (default: 200 in 30 days) get a notification.
3. The notification appears in your bell dropdown and triggers an email.
4. You create the audience manually in LinkedIn Campaign Manager, paste the URN into ILLIXIS, and ILLIXIS deploys the ad.

Notification Actions

| Action | What It Does |
|--------|--------------|
| Link Audience | Paste a LinkedIn URN to create a RetargetingAudience and mark notification as actioned |
| Snooze (7 or 30 days) | Temporarily hide the notification; it reappears after the snooze period |
| Dismiss | Permanently hide the notification |

Configuration

| Setting | Default | Location |
|---------|---------|----------|
| Enable notifications | On | Tenant Settings |
| Traffic threshold | 200 pageviews (30 days) | Tenant Settings |

Token Management

LinkedIn's token model is more favorable than Meta's because it supports refresh tokens.

Token Lifecycle

| Token Type | Validity | Renewal |
|------------|----------|---------|
| Access Token | 60 days | Refreshed automatically using the refresh token |
| Refresh Token | 365 days | Issued during OAuth; a new one may be issued during refresh |

Automatic Refresh

ILLIXIS checks token validity before every API call. If the access token has expired (or will expire within 5 minutes), it automatically uses the refresh token to obtain a new access token. This happens transparently -- you do not need to take action.

When Re-Authorization Is Required

You must re-authorize in these cases:

• The refresh token has expired (after 365 days of no use)
• The refresh token was revoked (you changed your LinkedIn password or revoked app access)
• No refresh token was issued during the original OAuth flow

Re-Authorization

1. Go to Settings > Integrations > LinkedIn.
2. Click Reconnect.
3. Complete the OAuth flow again (same steps as initial connection).
4. Your ad account and Insight Tag selection are preserved -- you just need to re-authorize.

Automation Schedule

ILLIXIS manages LinkedIn-related tasks on these schedules:

| Task | Frequency | Timing |
|------|-----------|--------|
| Retargeting opportunity check | Daily | 7:00 AM UTC (after GA4 metrics sync) |
| Token refresh | On demand | Before any API call where access token has expired |
| Audience sync | Manual | Triggered via "Sync to LinkedIn" button |

What this means for you:

• You receive notifications automatically when articles qualify for retargeting. No manual monitoring needed.
• Token refresh is handled transparently. You will not see interruptions unless the refresh token itself expires after 365 days.
• Audience sync and ad creation are manual actions you trigger when ready.

Manual actions: Click "Sync to LinkedIn" on any audience or on the dashboard. Click "Create LinkedIn Ad" on any audience with a linked URN.

API Rate Limits

LinkedIn enforces stricter rate limits than other ad platforms:

| Limit | Value |
|-------|-------|
| General API | 100 requests/day/user |
| DMP Segment name | 100 characters max |
| Campaign name | 255 characters max |
| Audience retention | 180 days max |
| Lookalike seed size | 300 members minimum |

ILLIXIS respects these limits by truncating names and capping retention windows automatically.

Troubleshooting

"LinkedIn not connected"

Cause: No active, authorized LinkedInConnection found for your tenant.

Fix: Go to Settings > Integrations and click "Connect LinkedIn" to start the OAuth flow.

"LinkedIn ad account not selected"

Cause: OAuth completed but you did not finish the account selection step.

Fix: Go to Settings > Integrations > LinkedIn and complete the ad account selection.

"LinkedIn access token expired. Please reconnect."

Cause: Both the access token and refresh token have expired or been revoked. Automatic refresh failed.

Fix: Click "Reconnect" in Settings > Integrations > LinkedIn and complete the OAuth flow again.

"LinkedIn organization (company page) not configured"

Cause: No Organization ID is saved on your connection. This is required for creating Sponsored Content ads.

Fix: Go to Settings > Integrations > LinkedIn and enter your Company Page's numeric Organization ID.

"Permission denied. Ensure your LinkedIn account has Campaign Manager access"

Cause: The authenticated user does not have the required permissions on the ad account, or the Marketing Developer Platform permissions were not granted during OAuth.

Fix:

1. Verify the user has Campaign Manager access to the ad account.
2. Re-authorize and ensure all requested scopes are approved.
3. Check that your LinkedIn app has Marketing Developer Platform approval.

"This audience doesn't have a LinkedIn URN linked"

Cause: You tried to create an ad for an audience that has not been synced to LinkedIn or linked to a URN.

Fix: Either sync the audience to LinkedIn (click "Sync to LinkedIn") or link a manually-created audience URN.

Ad Creation Failed with API Error

Cause: LinkedIn's API rejected the request. Common reasons include missing Organization permissions, invalid audience URN, or policy violations.

Fix:

1. Check the error message stored on the audience record.
2. Verify your Company Page has the required admin permissions.
3. Ensure the DMP Segment exists and is ACTIVE in Campaign Manager.
4. Check that your ad content complies with LinkedIn's advertising policies.

"Failed to refresh LinkedIn access token"

Cause: The refresh token is invalid, expired, or was revoked.

Fix: Click "Reconnect" in Settings > Integrations > LinkedIn to obtain fresh tokens.

Related Guides

• Advertising Overview -- Dashboard, audience management, and ad platform overview
• LinkedIn Retargeting Opportunities -- Traffic-based notifications for high-performing content
• Prospecting Campaigns -- Interest targeting, lookalike audiences, and new customer acquisition
• GA4 Audiences -- How topic-based audiences are created from your analytics data
• Lookalike Audiences -- Expanding reach with predictive audience modeling