airbyte/docs/integrations/sources/linkedin-ads.md

LinkedIn Ads

This page guides you through the process of setting up the LinkedIn Ads source connector. The LinkedIn Ads source connector is based on a Airbyte CDK. Airbyte uses LinkedIn Marketing Developer Platform - API to fetch data from LinkedIn Ads.

Prerequisites

For Airbyte Cloud

• The LinkedIn Ads account with permission to access data from accounts you want to sync.

For Airbyte Open Source

• The LinkedIn Ads account with permission to access data from accounts you want to sync.
• Authentication Options:
  • OAuth2.0:
    • Client ID from your Developer Application
    • Client Secret from your Developer Application
    • Refresh Token obtained from successfull authorization with Client ID + Client Secret
  • Access Token:
    • Access Token obtained from successfull authorization with Client ID + Client Secret

Step 1: Set up LinkedIn Ads

1. Login to LinkedIn as the API user.

2. Create an App here:

   • App Name: airbyte-source
   • Company: search and find your company LinkedIn page
   • Privacy policy URL: link to company privacy policy
   • Business email: developer/admin email address
   • App logo: Airbyte's (or Company's) logo
   • Products: Select Marketing Developer Platform (checkbox)
   • Review/agree to legal terms and create app.

3. Verify App:

   • Provide the verify URL to your Company's LinkedIn Admin to verify and authorize the app.
   • Once verified, select the App in the Console here.
   • Review the Auth tab:
     • Record client_id and client_secret (for later steps).
     • Review permissions and ensure app has the permissions (above).
     • Oauth 2.0 settings: Provide a redirect_uri (for later steps): https://airbyte.io
     • Review the Products tab and ensure Marketing Developer Platform has been added and approved (listed in the Products section/tab).
     • Review the Usage & limits tab. This shows the daily application and user/member limits with percent used for each resource endpoint.

4. Authorize App:

   (Required for Airbyte Open Source, Optional for Airbyte Cloud)

   The authorization token lasts 60-days before expiring. The connector app will need to be reauthorized when the authorization token expires.

   Create an Authorization URL with the following pattern:

   • The permissions set you need to use is: r_emailaddress,r_liteprofile,r_ads,r_ads_reporting,r_organization_social
   • URL pattern: Provide the scope from permissions above (with + delimiting each permission) and replace the other highlighted parameters: https://www.linkedin.com/oauth/v2/authorization?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=r_emailaddress,r_liteprofile,r_ads,r_ads_reporting,r_organization_social
   • Modify and open the url in the browser.
   • Once redirected, click Allow to authorize app.
   • The browser will be redirected to the redirect_uri. Record the code parameter listed in the redirect URL in the Browser header URL.

5. Run the following curl command using Terminal or Command line with the parameters replaced to return your access_token. The access_token expires in 2-months.

   (Required for Airbyte Open Source, Optional for Airbyte Cloud)

    curl -0 -v -X POST https://www.linkedin.com/oauth/v2/accessToken\
    -H "Accept: application/json"\
    -H "application/x-www-form-urlencoded"\
    -d "grant_type=authorization_code"\
    -d "code=YOUR_CODE"\
    -d "client_id=YOUR_CLIENT_ID"\
    -d "client_secret=YOUR_CLIENT_SECRET"\
    -d "redirect_uri=YOUR_REDIRECT_URI"
   

6. Use the access_token from response from the Step 5 to autorize LinkedIn Ads connector.

   (Required for Airbyte Open Source, Optional for Airbyte Cloud)

Notes:

The API user account should be assigned the following permissions for the API endpoints: Endpoints such as: Accounts, Account Users, Ad Direct Sponsored Contents, Campaign Groups, Campaings, Creatives requires the next permissions set:

• r_ads: read ads (Recommended), rw_ads: read-write ads Endpoints such as: Ad Analytics by Campaign, Ad Analytics by Creatives requires the next permissions set:
• r_ads_reporting: read ads reporting The complete set of permissions is:
• r_emailaddress,r_liteprofile,r_ads,r_ads_reporting,r_organization_social

The API user account should be assigned one of the following roles:

• ACCOUNT_BILLING_ADMIN
• ACCOUNT_MANAGER
• CAMPAIGN_MANAGER
• CREATIVE_MANAGER
• VIEWER (Recommended)

Step 2: Set up the source connector in Airbyte

For Airbyte Cloud:

1. Log into your Airbyte Cloud account.
2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
3. On the source setup page, select LinkedIn Ads from the Source type dropdown and enter a name for this connector.
4. Add Start Date - the starting point for your data replication.
5. Add your Account IDs (Optional) if required.
6. Click Authenticate your account.
7. Log in and Authorize to the LinkedIn Ads account
8. click Set up source.

For Airbyte OSS:

1. Go to local Airbyte page.
2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
3. On the Set up the source page, enter the name for the connector and select LinkedIn Ads from the Source type dropdown.
4. Add Start Date - the starting point for your data replication.
5. Add your Account IDs (Optional) if required.
6. Choose between Authentication Options:
   • OAuth2.0:
     • Copy and paste info from your LinkedIn Ads developer application:
       • Client ID
       • Client Secret
       • Obtain the Refresh Token using Set up LinkedIn Ads guide steps and paste it into corresponding field.
   • Access Token:
     • Obtain the Access Token using Set up LinkedIn Ads guide steps and paste it into corresponding field.
7. Click Set up source.

Supported Streams and Sync Modes

This Source is capable of syncing the following data as streams:

• Accounts
• Account Users
• Campaign Groups
• Campaigns
• Creatives
• Ad Direct Sponsored Contents
• Ad Analytics by Campaign
• Ad Analytics by Creative

Sync Mode	Supported?(Yes/No)
Full Refresh Overwrite Sync	Yes
Full Refresh Append Sync	Yes
Incremental - Append Sync	Yes
Incremental - Append + Deduplication Sync	Yes

NOTE:

Ad Direct Sponsored Contents stream includes the information about VIDEO ADS, as well as SINGLE IMAGE ADS and other directly sponsored ads your account might have.

For Analytics Streams such as: Ad Analytics by Campaign, Ad Analytics by Creative the pivot column name is renamed to _pivot to handle the data normalization correctly and avoid name conflicts with certain destinations.

Data type mapping

Integration Type	Airbyte Type	Notes
number	number	float number
integer	integer	whole number
date	string	FORMAT YYYY-MM-DD
datetime	string	FORMAT YYYY-MM-DDThh:mm:ss
array	array
boolean	boolean	True/False
string	string

Performance considerations

There are official Rate Limits for LinkedIn Ads API Usage, more information here. Rate limited requests will receive a 429 response. Rate limits specify the maximum number of API calls that can be made in a 24 hour period. These limits reset at midnight UTC every day. In rare cases, LinkedIn may also return a 429 response as part of infrastructure protection. API service will return to normal automatically. In such cases you will receive the next error message:

"Caught retryable error '<some_error> or null' after <some_number> tries. Waiting <some_number> seconds then retrying..."

This is expected when the connector hits the 429 - Rate Limit Exceeded HTTP Error. If the maximum of available API requests capacity is reached, you will have the following message:

"Max try rate limit exceded..."

After 5 unsuccessful attempts - the connector will stop the sync operation. In such cases check your Rate Limits on this page > Choose you app > Analytics.

Changelog

Version	Date	Pull Request	Subject
0.1.9	2022-07-21	14924	Remove additionalProperties field from schemas
0.1.8	2022-06-07	13495	Fixed base-normalization issue on Destination Redshift caused by wrong casting of pivot column
0.1.7	2022-05-04	12482	Update input configuration copy
0.1.6	2022-04-04	11690	Small documenation corrections
0.1.5	2021-12-21	8984	Update connector fields title/description
0.1.4	2021-12-02	8382	Modify log message in rate-limit cases
0.1.3	2021-11-11	7839	Added oauth support
0.1.2	2021-11-08	7499	Remove base-python dependencies
0.1.1	2021-10-02	6610	Fix for Campaigns/targetingCriteria transformation, coerced Creatives/variables/values to string by default
0.1.0	2021-09-05	5285	Initial release of Native LinkedIn Ads connector for Airbyte