API Connector Documentation
Import LinkedIn Ads Data to Google Sheets
In this guide, we will pull data from the LinkedIn API directly into Google Sheets, using the API Connector add-on for Sheets.
The LinkedIn API limits data for privacy reasons; don't expect a way to pull out profile information for anyone but yourself. However, this API is perfect for pulling out advertising performance data from the LinkedIn Ads Reporting API.
Contents
- Before You Begin
- Part 1: Connect to the LinkedIn Ads API
- Part 2: Pull Data from LinkedIn Ads to Sheets
- Part 3: Create a Custom API Request
- Part 4: Handle Pagination
- Part 5: Notes
- Part 6: API Documentation
- Part 7: LinkedIn Reporting Template
- Appendix: Expand Campaign and Creative Names
Before You Begin
Click here to install the API Connector add-on from the Google Marketplace.
Part 1: Connect to the LinkedIn Ads API
The easiest way to get started with the LinkedIn Ads API is through API Connector’s built-in integration.
- Select LinkedIn Ads from the drop-down list of applications
- Under Authorization, click Connect to LinkedIn
- You will be directed to LinkedIn and asked to authorize the connection. Click Allow.
- You'll now be returned to your Google Sheet, and can verify that your LinkedIn API connection is active.
Part 2: Pull Data from LinkedIn Ads to Sheets
Now that we’re connected, let’s pull some data into Sheets.
- In the Endpoint section, choose
/adAnalytics?q=statisticsto get reporting data in your sheet. - In the Request parameters section, select one or more of your accounts from the dropdown menu.
- Fill in the other required parameters:
dateRange,fields,pivots, andtimeGranularity. FordateRange, select fixed dates from the calendar input or use dynamic values from the cells in your sheet.
- Click Edit fields to select just the fields you want and assign them to specific columns in your report.
- Run your request.
Part 3: Create a Custom API Request
Alternatively, you can create a custom request instead of using API Connector’s built-in integration, using any of the API URLs shown in the API documentation.
Example: Fetch metrics with Statistics Finder
Here's a complete example using LinkedIn's X-Restli protocol and their new versioned API. The LinkedIn Statistics Finder method allows you to include multiple "pivots" (i.e. dimensions). Substitute in your own account ID where it says your_account_id, and your own dates into the dateRange parameter..
- Application:
Custom - Method:
GET - Request URL:
https://api.linkedin.com/rest/adAnalytics?q=statistics&fields=pivotValues,dateRange,clicks,impressions,likes,shares,costInLocalCurrency&pivots=List(CREATIVE,CAMPAIGN,ACCOUNT)&dateRange=(start:(day:01,month:08,year:2023),end:(day:31,month:08,year:2023))&timeGranularity=DAILY&accounts=List(urn%3Ali%3AsponsoredAccount%3Ayour_account_id) - OAuth:
LinkedIn Ads - Headers
X-Restli-Protocol-Version:2.0.0LinkedIn-Version:202311
An earlier version of this article showed how to expand the URNs (IDs) returned in the elements.pivotValues fields. API Connector will now automatically expand URNs, so no further requests are needed. (For reference, the original information has been moved into the appendix.)
Part 4: Handle Pagination
By default, LinkedIn's /adAnalytics endpoint will return just 1000 records. To return more, apply API Connector's automatic pagination handling as follows
- Pagination:
next page URL - Next page path:
paging.links.href - Run until: choose when to stop fetching data
Part 5: Notes
- Use the visual field editor to re-arrange columns (just click Edit Fields before running your request).
- LinkedIn sends back dates split into separate year, month, and day fields. To transform these into a regular Sheets date, set a data destination of cell B1, and then add the following function into cell A1:
=arrayformula(if(J2:J<>"", date(J2:J,H2:H,I2:I),"")). The function assumes years are in column J, months are in H, and days are in I; adjust as needed. - To view or manage the connection on LinkedIn, click here: https://www.linkedin.com/psettings/permitted-services
Part 6: API Documentation
Official API documentation: https://docs.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting
Part 7: LinkedIn Reporting Template
Here's a template you can use to fetch an ads performance summary that looks like this:
The template also contains preset requests for ads performance broken down by various facets, as well as demographic reports. Check the "Information" tab to get started.
Report template link: Click here for a copy
Appendix: Expand Campaign and Creative Names
LinkedIn's API is rather inconveniently designed as it generally returns URNs (IDs) instead of names. For example, if you run the custom Statistics Finder request shown above, the response will include the creative, campaign, and account URNs. To convert these URNs into meaningful names, we need to make a separate requests, using the LinkedIn URN resolution lookup table to determine the correct endpoint.
API Connector now runs these separate requests automatically in the background to fetch associated names, but the following information is presented for reference, in case you're writing your own script, using an API client outside of API Connector, or want to fetch additional creative details like landing page URLs.
Example 1: Fetch campaign names with URN Resolution
For this example, we'll look at the elements.pivotValues field reading urn:li:sponsoredCampaign:xxxxxxxx . From the URN resolution lookup table, we can see that the sponsoredCampaign string means we call the /adCampaigns endpoint.
Plug your account ID and campaign ID into the request URL below.
- Application:
Custom - Method:
GET - Request URL:
https://api.linkedin.com/rest/adAccounts/your_account_id/adCampaigns/your_campaign_id - OAuth:
LinkedIn Ads - Headers
X-Restli-Protocol-Version:2.0.0LinkedIn-Version:202311
As you can see, that returned the campaign name.
Example 2: Fetch ad creative names and URLs with the content reference field
OK, now it gets a bit complicated 😀
- Create a statistics request in which
pivots=CREATIVEandfields=pivotValues. This will produce a response that contains URN values that look like thisurn:li:sponsoredCreative:xxxxxxxxx
- Now, just as in the above example for
sponsoredCampaign, use the URN resolution table to find the correct endpoint forsponsoredCreativeexpansion. That page shows that it's/creatives. - That means you need to run a request to the
/creativesendpoint, plugging in your own account ID and the creative ID from the URN, like this:https://api.linkedin.com/rest/adAccounts/your_account_id/creatives/urn%3Ali%3AsponsoredCreative%3Ayour_creative_id - The response will look like this. Note the value in the
content.referencefield as we need that next:
- Unlike the
/adAccountsand/adCampaignsendpoints, running a request to the/creativesendpoint does not directly return the ad name. Instead, you need to check thecontent.referencefield, and make a second call to the following "sub content" endpoints based on that value (source: cheat sheet provided by LinkedIn).content.reference example sub content endpoint none not needed urn:li:adInMailContent:1020065 https://api.linkedin.com/rest/inMailContents/urn%3Ali%3AadInMailContent%3A1020065 urn:li:share:6334225903081525248 https://api.linkedin.com/rest/posts/urn%3Ali%3Ashare%3A6334225903081525248 urn:li:ugcPost:6364155080052219904 https://api.linkedin.com/rest/posts/urn%3Ali%3AugcPost%3A6364155080052219904 - For example, my
content.referencevalue above contains thesharestring, so it corresponds to thehttps://api.linkedin.com/rest/posts/urn%3Ali%3Ashare%3A6334225903081525248example endpoint. If I plug in my own reference ID, it returns the ad name.
- Ta-da! That's the name of my ad (and the rest of the response contains additional creative fields). Hopefully this is useful/interesting for those confused or unsure of how to fetch ad creative names, links, and other information from the new LinkedIn APIs.
Hi! This was incredibly helpful. Unfortunately all the campaign, campaign groups, creatives, and companies are coming in as numbers instead of using the actual names. So it's very hard to match up which campaign goes with which campaign code. Is there an API that pulls in the name instead of just the value?
Hey Kat! Thanks for the message. Can you please try this?
https://api.linkedin.com/v2/adCampaignsV2/?q=searchI believe it will return a list of all your campaigns with both names and IDs, so you can use that to match up the data from the other queries. There might be a better way but that's how I did it :p. Let me know if that works for you.
Edit: you can get this all in one go using projection, I put some examples above.
Edit 2: LinkedIn has now deprecated their v2 API as well as projection, so you need to run a separate request for each URN to fetch its associated value. I updated the custom request section with info on how that works, and we updated our preset integration to make those fetches automatically in the background.
Hi I was hoping you might be able to give me some guidance.
I have all the data coming in fine, GREAT JOB, but i'm not able to pull any lead or conversion data from an Ad Campaign that is counting conversions as a download from LinkedIn itself.
Do you have any ideas the ExternalConversions won't work because its happening on LinkedIn. Thanks in Advance.
If you click this #metrics-available link, you can see all the metrics that LinkedIn provides. I just looked through and some of these look they might be what you're looking for: actionClicks, adUnitClicks, cardClicks, clicks, companyPageClicks, landingPageClicks, oneClickLeadFormOpens, oneClickLeads, totalEngagements. If you check the link you can see the descriptions of each metric, so please check and see if they get you what you need. If so, you'd just add them into the fields parameter of your request URL. Let me know if that works or you have any questions.
Thank you, it turned out that oneClickLead was the correct one. Thank you for doing the work on this
I cant seem to do a POST request using LinkedIn Connection?
What is the reason for this? Is it because it is a paid feature or something else?
Hey Ben, this is because LinkedIn's API requires approval for each specific scope (permission). API Connector limits the scopes it requests to r_ads, r_ads_reporting, and r_basicprofile, which only allow getting, not posting, data. Sorry for the inconvenience. One option would be for you to create your own custom OAuth2 connection to Linkedin, then you could request whatever scopes you need. Or could you please let me know a bit more about what you're trying to do? I will consider requesting additional scopes in the future.
Hi Ana, I'm looking to generate many ads & campaigns in bulk for an ABM use case where we cite a company name. I have a Custom App with the necessary permissions.
Maybe I can connect using that Connection using your custom Connection option?
Yeah, if you've already made your app on LinkedIn's side, you should be able to set up API Connector's custom OAuth2 connection like this:
Name: Custom LinkedIn
Authorization Base URL:
https://www.linkedin.com/oauth/v2/authorization?scope=r_ads%2Cr_ads_reporting%2Cr_basicprofile(add on other scopes here)Token URL:
https://www.linkedin.com/oauth/v2/accessTokenClient ID: provided by LinkedIn
Client Secret: provided by LinkedIn
Custom OAuth gets added in the Manage Connections screen. As long as you add your ad management scopes to the base URL, you will be able to access whatever you need in LinkedIn's API. Can you please try that and see how it goes?
Seems to work now, excellent. Thanks for your help!
I want to get the new leads from the ads that fill the forms
Is this what you're looking for? https://docs.microsoft.com/en-us/linkedin/marketing/integrations/lead-gen/ads-leadgen
If so, you can try a request like this:
https://api.linkedin.com/v2/adForms?q=account&account=urn:li:sponsoredAccount:111111111&totals=true&count=1&start=0Hi is it possible to catch the data about spended money on concrete campaign ?
Sure, you can use the costInLocalCurrency and costInUsd fields, e.g.
https://api.linkedin.com/v2/adAnalyticsV2?q=analytics&timeGranularity=MONTHLY&dateRange.start.year=2021&dateRange.start.month=1&dateRange.start.day=1&dateRange.end.year=2021&dateRange.end.month=2&dateRange.end.day=1&pivot=CAMPAIGN&fields=costInLocalCurrency,costInUsd,dateRange,pivotValues&accounts[0]=urn:li:sponsoredAccount:123456789Hi how to get the ad creative names ?
It depends on the specific ad type, but generally you can get it through projection or by directly calling the adCreatives endpoint:
https://api.linkedin.com/v2/adCreativesV2?q=searchEdit: API Connector will now fetch ad names automatically in the background.
Hi Ana,
last week you supported me to connect Linkedin Pages and it has worked correctly. I am currently trying to connect Linkedin Ads but when I connect it, in Linkedin Pages requests I get an error: {"serviceErrorCode":65601,"message":"The token used in the request has been revoked by the user","status ":401}. When I connect Linkedin Pages again I get the same error for Ads requests. Is there a problem with having both connected simultaneously?
I really appreciate your support.
I just tested and was able to connect and run requests from both LinkedIn Ads and LinkedIn Pages, so I'm not yet sure what the issue is. Are you connecting each connection to the same LinkedIn account?
Which metric/field provides the name of the ads
You can enter
projection=(,elements(*,pivotValue~()))to retrieve ad names and other metadata. You can find theprojectionfield in the integration menu, or enter it manually in a custom request.Edit: projection has been deprecated, and API Connector will now automatically fetch these names by running additional requests in the background.
@Ana, thanks for good example. i am trying to get all the performance metrics for all my campaing and using this endpoint :
https://api.linkedin.com/v2/adAnalyticsV2?q=campaign&dateRange.start.day=01&dateRange.start.month=01&dateRange.start.year=2023&dateRange.end.day=31&dateRange.end.month=01&dateRange.end.year=2023&pivot=DEMOGRAPHICS&fields=impressions,clicks,ctr,socialActions,videoViews,cpc,cpm,conversions,conversionRate,averageEngagement,engagementRate,frequency,spendBut does not work, where am i going wrong?
Looks like you're using the old v2 endpoints, which are now deprecated. Please check the custom request example above for an example using their new versioned API. You can also try using our preset integration instead as it's a lot easier to set up the requests.
Ana, your reply is much appreciated. How can I use your preset integration ?
Connect to LinkedIn as shown here, and then select LinkedIn from the dropdown menu as shown here. Just let me know if anything isn't clear and I'll be happy to help.
These are the fields that i want to bring into my worksheet.
Spent,Impressions,Clicks,Average CTR,Bid,Average CPM,Average CPC,Conversions,Cost Per,Conversion,Leads,Cost Per Lead
/adAnalytics?q=analytics is correct. Pivot =ACCOUNT but in the fields i cannot find the fields mentioned above. How do i achieve this?
You can see the full list of metrics available via API here: https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting?view=li-lms-2023-06&tabs=http#metrics-available
I believe all those metrics are available through API Connector, but if not, you can type them into the dropdown to manually add them to the list.
Please note that the names of API metrics are different from the metrics in the interface, e.g. the interface uses the word "Spent" while the API uses "costInLocalCurrency". Other metrics aren't provided at all via API and need to be calculated, e.g. "Average CPM" would be costInLocalCurrency divided by 1000 impressions.
Thank you very mcuh for clarifying and your help has been absolutely fantastic!
https://api.linkedin.com/v2/adAnalyticsV2?q=statistics&pivots[0]=CAMPAIGN&pivots[1]=CREATIVE&dateRange.start.day=1&dateRange.start.month=1&dateRange.start.year=2019&timeGranularity=DAILY&campaigns[0]=urn:li:sponsoredCampaign:124782804&fields=externalWebsiteConversions,dateRange,impressions,landingPageClicks,likes,shares,costInLocalCurrency,pivot,pivotValuesHi Ana, can you help me revise the above to get the
all campaign names
all creative names
daily segments
and dates by cell reference?
There's no way to get all campaign & creative names in one API call, since they return "urn" IDs from the main reporting endpoints, which then need to be looked up using additional endpoints to get the associated names. LinkedIn gave me a "cheat sheet" which you can see here, and I added some more detailed instructions on using it in the custom request section.
I suggest using API Connector's built-in integration, because this is a very complex API that's not easy to understand or customize. In addition, please note that the example you've provided uses LinkedIn's deprecated API that will be removed soon.
Hey there! Is there any way to search for all Campaign names within a specific Campaign Group?
Cannot for the life of me get this to work: https://api.linkedin.com/v2/adCampaignsV2?q=search to work, just throws error:
{"message":"Request would return too many entities. .","status":400}
Also, alternatively... and this is a lonnnnng shot... any way to extract links from individual ads? Would love to be able to see and parse UTM parameters from listed ads. Thanks!
{"message":"Request would return too many entities. .","status":400}
This error occurs when you have more than 1000 records (info).
Can you please try running that request using API Connector's preset integration instead? (Select LinkedIn Ads > Get Available Campaigns from API Connector's dropdown application menu). That way you'll a) be using LinkedIn's newest API (the v2 syntax you used will be deprecated soon), and b) can set the "count" parameter to 1000 or lower, and use pagination to get all the records.
As for extracting additional values, it's possible but you'll need to make separate calls based on the resolution table shown here.
Thank you!
Very clear explanation, thank you!
I only recieve this as the output when following custom GET request with Linkedin OAUTH copied and pasted from the example. This is what it was giving me previously with no changes when the query criteria changed
paging.start paging.count paging.links.1 elements.1
0 10
That means the request worked but LinkedIn didn't send back any data. I'd double check that the account you authenticated with has ads data available for the time period you've selected.
Hi Ana,
Even if I did the OATH successfully, I see no accounts during the setup. You can see it here: https://i.ibb.co/C9HxzsX/image.png
Do you have any idea why it is doing like this?
What happens if you click the Refresh icon on the right? The account list should appear then, let me know if not.
I'm encountering the error below when attempting to fetch data from LinkedIn Ads. This request has been working for over 12 months, but suddenly encountered this error:
{"message":"Projected field "pivotValue" not present in schema "com.linkedin.adsexternalapi.reportingapi.v3.AdAnalyticsV3"","status":400}
Screenshot: https://zwdrive.com/mmr3Rq
Any help would be greatly appreciated.
I can't say for sure without seeing your request configuration, but it sounds like you may be using the "pivotValue" field which was deprecated last year by LinkedIn (info). Please replace that field with their new field "pivotValues". If that doesn't work, feel free to share your request configuration through support, so we can give you more specific guidance.
Hi Ana,
When I try to get demographics report by pivotvalue "MEMBER_COUNTRY_V2", I get the following response:
https://i.ibb.co/hc5gS0n/image.png As you can see, I get the cost value but I can't get country string.
Maybe there is a problem with the request sent by the api connector?
I tested and wasn't able to replicate the issue on this side -- for me, countries are pulled in when I select the MEMBER_COUNTRY_V2 pivot. Please check the following:
1) Make sure you've selected "pivotValues" as one of your fields. This is required to get the value of the pivot (i.e. country, in this case).
2) Make sure your dates are within the past 2 years. LinkedIn only retains demographic data (e.g. member title, job function, seniority, etc.) for 2 years. Also make sure to include dates more than 1 day ago, since there may be a delay of up to 24 hours, and test with a timeGranularity of ALL.
3) Try testing with different metrics. Not all metrics are compatible with demographic breakdowns.
Just let me know if you're still running into issues after that. For reference you can see the full list of restrictions for this endpoint here.
Hi All,
Please help me how I can get the company name by account id or campaign id. I am calling adAnalytics API but didn't get any response:
https://api.linkedin.com/rest/adAnalytics?q=analytics&timeGranularity=DAILY&pivot=MEMBER_COMPANY&dateRange=(start:(year:2024,month:1,day:1),end:(year:2024,month:6,day:1))&accounts=List(urn%3Ali%3AsponsoredAccount%3A12345,urn%3Ali%3AsponsoredAccount%3A1234)&fields=externalWebsiteConversions,dateRange,impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValuesand getting below response:
{"paging": {
"start": 0,
"count": 10,
"links": []
},
"elements": []
}
Please let me know if am I missing something.
Do other pivots work for you? (e.g. if you replace MEMBER_COMPANY with ACCOUNT). If so, there's nothing wrong with the request configuration, and LinkedIn just hasn't made the MEMBER_COMPANY pivot value available. You can check their information on pivots here.
Hi Ana, Thanks for confirming that nothing wrong in my request but when I am calling this API with other couple of pivots i.e. ACCOUNT, COMPANY, MEMBER_COMPANY_SIZE, CAMPAIGN, CAMPAIGN_GROUP...getting same result.
What would be the possibilities that we are not getting any result? Is there any limitation to access those accounts data for that authenticated user.
On my side those other pivots work, so if you're not seeing data for any of them, I'd double check that there is data in the time period you're selecting. Do you see data when you try the "Get ad statistics" (
/adAnalytics?q=statistics) endpoint? I don't believe this issue is related to authorization since you'd be receiving an error message if you didn't have access to the account at all.Hi Ana, We found the root cause there was some authorization issue that I was not able to see any data in the API responses. Could you please help me how can I get the company details in any of the LinkedIn API.
Thanks
This URL worked for me:
https://api.linkedin.com/rest/adAnalytics?q=analytics&timeGranularity=ALL&pivot=MEMBER_COMPANY&dateRange=(start:(day:01,month:04,year:2024),end:(day:30,month:04,year:2024))&accounts=List(urn%3Ali%3AsponsoredAccount%3A11111111)&fields=externalWebsiteConversions,dateRange,impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValuesIf it's still not working for you, make sure you a) select a date recent enough, and b) try timeGranularity=ALL, since demographics data is only available for 2 years and can't always be broken down by day.
Hi Ana, I can see the organization urn under the pivotValues but not the company name anywhere as
"pivotValues": [
"urn:li:organization:12345"
],
Are you getting the company name directly or company url?
Just the URN, since LinkedIn requires a separate call to get the organization name as shown here. So you'll need to make another call for those IDs. There are a few ways you could handle this, here's one:
1) When you run your initial request, set the destination to C1 so you have a couple empty columns on the left for your formulas. This way your data won't get overwritten next time you run the request.
2) In cell A2, parse out the IDs from the URNs with a formula. There's probably something more elegant, but this worked for me:
=arrayformula(if(I2:I<>"",mid(I2:I,find("organization-",I2:I)+13,(find(")",I2:I)-(find("organization-",I2:I)+10)-3)),""))3) In cell B2, join all those IDs into a comma separated list using this formula:
=TEXTJOIN(",",1,A2:A2000)4) Now create a custom request with the following request settings. Substitute in your own sheet name and cell where it says Organizations!B2, since this references the cell value containing your comma-separated list of IDs.
Application:
CustomMethod:
GETRequest URL:
https://api.linkedin.com/rest/organizationsLookup?ids=List(+++Organizations!B2+++)OAuth:
LinkedInOutput Options > Report Style:
gridOutput Options > Report Style > Force rows:
checkedHi Ana,
This is all about the Organization details by organization urn id, I am specially looking company information. I hope Organization and Company both are different against account or campaign.
Thanks
The response returns company name, address, website, etc.
Hi All,
I am looking some API which can provide demographic details by account id, campaign id, creative id and data range. Please let me know if any API available for the same.
Thanks
Demographic values are only provided through the "Analytics Finder" method, which doesn't allow for additional campaign-based pivots. Please refer to this page for full information on what their API provides: https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting
Thanks Ana for all your support. I am able to pull Company name through LinkedIn APIs adAnalytics and organizationsLookup.
Any ability to pull in metrics specific to Conversation Ads, eg. Sent, Open Rate, etc?
Yes, the adAnalytics should return data for Conversation Ads as well as other types of ads. You can specify "sends" and "opens" by adding those both to the request parameter fields for the adAnalytics endpoint. From there, you would be able to calculate open rate in your sheet.
Full documentation can be found here: https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting?view=li-lms-2024-06&tabs=http#metrics-available_
Hi there, I've seen today that there's been an update, as the loading icon when running a query has changed and I'm having issues with my exports ever since. I'm coming across this error that is blocking me from running requests that were automated before:
Export 2025: Completed with errors
- We received an error from linkedin.com (426) show response.
Any ideas/help please? Everything worked fine before.
Hi - could you please re-load or re-save your request and run again? There was a previous LinkedIn API version that has been deprecated. Please let me know if you continue to experience any issues.
Hi Ian, thanks for that, it helped. Does that mean that I'll have to save all of the triggers again for them to work or would it fire normally from now on?
All the triggers should now fire as expected.