LinkedIn Ads Integration for Nodus
1. Introduction to the LinkedIn Ads Integration
What Is This Integration?
LinkedIn Ads integration connects your LinkedIn advertising platform data with Nodus, allowing you to extract, analyze, and transform campaign performance metrics, creative insights, and other advertising data. This integration functions as a source connector, bringing your LinkedIn Ads data into the Nodus ecosystem.
Prerequisites:
- An active LinkedIn Ads account with Account Manager or higher permissions
- Valid LinkedIn Ads Account ID
- Authorization via LinkedIn Single Sign-On (SSO)
- Access to LinkedIn's Marketing Developer Platform
Connection Overview:
The integration uses LinkedIn's Marketing API to extract advertising data and analytics. Authentication is handled through OAuth 2.0, and the connector can retrieve both account configuration data and performance metrics.
2. Platform Setup Documentation (Setup Form for LinkedIn Ads)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and LinkedIn Ads by providing the necessary authentication credentials and account details.
Field-by-Field Breakdown:
Integration Name
- Field Name & Label: Integration Name
- Description & Purpose: A descriptive name to identify this LinkedIn Ads integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "LinkedIn Ads - Marketing Team", "LinkedIn B2B Campaigns"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific LinkedIn Ads account or purpose.
LinkedIn Ads Account ID
- Field Name & Label: LinkedIn Ads Account ID
- Description & Purpose: The unique identifier for your LinkedIn Ads account, used to access campaign data.
- Validation Rules & Format: Numeric string, required field.
- Examples: "123456789"
- Troubleshooting Tips: You can find your Account ID in LinkedIn Campaign Manager under Account Settings. Make sure you're using the correct Account ID if you have access to multiple accounts.
External Link
- Link Label: "Find Your Account ID"
- URL: https://www.linkedin.com/help/lms/answer/a417869
- Purpose: Helps users locate their LinkedIn Ads Account ID in the LinkedIn interface.
Step-by-Step Guide:
- Log in to LinkedIn Campaign Manager
- Navigate to Account Settings to locate your Account ID
- Enter your Account ID and a meaningful Integration Name in the Nodus setup form
- Click Authorize to launch the LinkedIn SSO authorization flow
- Grant permissions when prompted by LinkedIn
- Verify connection and save the configuration
Reference Links:
3. Extraction/Query Configuration (Extraction Form for LinkedIn Ads)
Purpose & Overview
This section explains how to configure data extraction from LinkedIn Ads. LinkedIn offers various templates for extracting different types of advertising data and analytics.
Template & Field Documentation:
Template Selection
- Field Name & Label: Select a template
- Description & Purpose: Defines which type of LinkedIn Ads data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- Ad Creative Analytics - Performance metrics for ad creatives including clicks, impressions, video views, etc.
- Ad Creative Analytics Engagement - Engagement metrics like comments, likes, follows, etc.
- Campaign Groups - Campaign group data including budgets, scheduling, and status
- Campaigns - Campaign level data including targeting, budgets, and performance settings
- Creatives - Creative content and settings for all ad formats
Lookback Range
- Field Name & Label: Lookback Range
- Description & Purpose: Specifies how many days back to extract data
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- Last 7 days
- Last 30 days
- Last 90 days
- Troubleshooting Tips: Select a longer range for historical analysis or a shorter range for recent performance data.
Historic Date Selection
- Field Name & Label: Historic Date
- Description & Purpose: For historical data extraction, specifies a custom date range
- Validation Rules & Format: Date picker, required field
- Troubleshooting Tips: LinkedIn maintains historical data for several years, but very old data may have limitations.
Workflow & Examples:
- Select the appropriate template (e.g., "Ad Creative Analytics" for performance metrics)
- Choose a lookback period or specific historic date range
- Preview the query to confirm configuration
- Execute extraction
Example Use Cases:
Ad Performance Analysis:
- Template: Ad Creative Analytics
- Metrics: Clicks, impressions, conversions, cost, video views
- Lookback: Last 30 days
Engagement Analysis:
- Template: Ad Creative Analytics Engagement
- Metrics: Comments, likes, follows, shares
- Lookback: Last 7 days
Campaign Structure Audit:
- Template: Campaigns
- Data: Campaign settings, targeting criteria, budget, status
- Historic Date: Custom range for specific campaign periods
4. Data Mapping & Underlying Models for LinkedIn Ads
Data Mapping & Underlying Models for LinkedIn Ads
Data Overview
The LinkedIn Ads API returns structured data based on the selected template. Each template corresponds to specific API endpoints and data structures.
Schema & Field Mapping
Ad Creative Analytics Schema
| Field | Description |
|---|---|
| actionClicks | Number of clicks on the call to action button |
| adUnitClicks | Number of clicks on the ad unit |
| clicks | Total number of clicks |
| conversionValueInLocalCurrency | Value of conversions in local currency |
| costInUsd | Total cost in USD |
| externalWebsiteConversions | Number of website conversions |
| externalWebsitePostClickConversions | Number of website conversions after clicking |
| externalWebsitePostViewConversions | Number of website conversions after viewing |
| impressions | Number of ad impressions |
| landingPageClicks | Number of clicks to the landing page |
| oneClickLeadFormOpens | Number of one-click lead form opens |
| oneClickLeads | Number of one-click leads generated |
| opens | Number of ad opens |
| videoCompletions | Number of complete video views |
| videoFirstQuartileCompletions | Number of video views that reached 25% |
| videoMidpointCompletions | Number of video views that reached 50% |
| videoThirdQuartileCompletions | Number of video views that reached 75% |
| videoStarts | Number of video starts |
| videoViews | Total number of video views |
| pivotValues | JSON object containing pivot information |
| dateRange | JSON object containing date range information |
Ad Creative Analytics Engagement Schema
| Field | Description |
|---|---|
| approximateUniqueImpressions | Approximate number of unique impressions |
| cardImpressions | Number of card impressions |
| commentLikes | Number of likes on comments |
| comments | Number of comments |
| companyPageClicks | Number of clicks to company page |
| follows | Number of follows |
| likes | Number of likes |
| leadGenerationMailContactInfoShares | Number of contact info shares from lead gen forms |
| leadGenerationMailInterestedClicks | Number of "interested" clicks on lead gen forms |
| pivotValues | JSON object containing pivot information |
| dateRange | JSON object containing date range information |
Campaign Schema
| Field | Description |
|---|---|
| id | Campaign ID |
| name | Campaign name |
| status | Campaign status (ACTIVE, PAUSED, etc.) |
| totalBudget | JSON object containing budget information |
| storyDeliveryEnabled | Whether story delivery is enabled |
| targetingCriteria | JSON object containing targeting settings |
| connectedTelevisionOnly | Whether campaign is limited to connected TV |
| pacingStrategy | Strategy for ad delivery pacing |
| locale | JSON object containing locale information |
| type | Campaign type |
| runSchedule | JSON object containing campaign schedule details |
| optimizationTargetType | Type of optimization target |
| changeAuditStamps | JSON object containing audit information |
| costType | Cost type (CPM, CPC, etc.) |
| creativeSelection | Method of creative selection |
| offsiteDeliveryEnabled | Whether offsite delivery is enabled |
| audienceExpansionEnabled | Whether audience expansion is enabled |
| test | Whether campaign is in test mode |
| format | Campaign format |
| servingStatuses | JSON object containing serving status information |
| version | JSON object containing version information |
| objectiveType | Campaign objective |
| associatedEntity | Associated entity |
| offsitePreferences | JSON object containing offsite preferences |
| campaignGroup | Reference to parent campaign group |
| dailyBudget | JSON object containing daily budget information |
| unitCost | JSON object containing unit cost information |
| account | Reference to account |
Campaign Group Schema
| Field | Description |
|---|---|
| id | Campaign group ID |
| name | Campaign group name |
| status | Campaign group status (ACTIVE, PAUSED, etc.) |
| runSchedule | JSON object containing schedule information |
| test | Whether campaign group is in test mode |
| changeAuditStamps | JSON object containing audit information |
| servingStatuses | JSON object containing serving status information |
| backfilled | Whether campaign group is backfilled |
| account | Reference to account |
Creative Schema
| Field | Description |
|---|---|
| id | Creative ID |
| intendedStatus | Intended status of creative |
| campaign | Reference to parent campaign |
| name | Creative name |
| content | JSON object containing creative content and format |
| isServing | Whether creative is currently serving |
| review | JSON object containing review status information |
| createdBy | Reference to creator |
| createdAt | Creation timestamp |
| lastModifiedAt | Last modification timestamp |
| leadgenCallToAction | JSON object containing lead generation call to action |
| servingHoldReasons | JSON object containing reasons creative might be on hold |
5. Troubleshooting & FAQs for LinkedIn Ads
Common Issues & Error Messages
Authentication Failures
- Error: "Invalid access token" or "Token expired"
- Solution: Re-authorize the integration through LinkedIn SSO. LinkedIn access tokens expire after 60 days and refresh tokens expire after 12 months.
Rate Limit Exceeded
- Error: HTTP 429 Too Many Requests
- Solution: LinkedIn has rate limits of about 100 queries per day per user. Reduce extraction frequency or optimize query templates.
Missing Data
- Common Causes:
- Campaign status filtering (only active campaigns shown by default)
- Date range outside of campaign activity period
- Insufficient permissions for the account
- Solution: Adjust template filters, check campaign dates, verify account permissions
Field Mapping Issues
- Error: "Unknown field in query"
- Solution: LinkedIn occasionally updates their API fields. Check the latest API documentation or use a simpler template with core fields.
Logging & Diagnostic Tools
- LinkedIn Campaign Manager provides UI reports that can be used to verify data
- Enable verbose logging in Nodus to capture API request/response details
Contact & Support Information
- LinkedIn Marketing Developer Platform support: https://www.linkedin.com/help/linkedin/ask/API-DVP
- Nodus Support: support@nodus.com
OAuth Token Management
LinkedIn uses OAuth 2.0 for authentication with the following characteristics:
- Access tokens expire after 60 days
- Refresh tokens expire after 12 months
- Required scopes: r_ads, r_ads_reporting, rw_ads
Data Retention & Limitations
- LinkedIn Ads API can return data for a maximum of 2 years
- Some metrics (like video views) may only be available for more recent campaigns
- Ad creative content may be limited for certain formats (e.g., Carousel ads)