Advertiser Transparency API
LinkedIn’s Advertiser Transparency API enables advertisers based in the European Economic Area or Switzerland to carry out verification of their LinkedIn advertisements inventory, through their verification vendor. LinkedIn is providing the Advertiser Transparency API in response to the Digital Markets Act (DMA) - a new EU law that regulates large online platforms to ensure fair competition, protect consumer rights, and foster innovation in the digital economy. The Advertiser Transparency API returns verification data at the ad account level which can be used to verify that ads in LinkedIn Feed and other LinkedIn owned and operated placements were viewed by real persons in a brand safe environment. These insights help advertisers make the most of their LinkedIn ads experience and ensure the safety and compliance of their campaigns on LinkedIn.
Note: This is a private API, available only to qualified developers who meet certain criteria. To learn more about qualifications and how to request access, please see the FAQ. If you believe you are a qualified developer and need access to this API, please submit a Zendesk support ticket.
Permissions
| Permission | Description |
|---|---|
| r_dma_advertiser_trust | Allow access to LinkedIn Ads Data to perform independent verification |
The Advertiser Transparency API requires a 3-legged OAuth member token and your developer application needs to be provisioned with the Advertiser Transparency Data qualification, as outlined above. Once you have been approved for access, you can use the valid member access token to access the API.
Eligibility for Access
The Advertiser Transparency API is a private API and can only be accessed by developers who meet the eligibility criteria defined here.
Request
GET https://api.linkedin.com/rest/advertiserTransparencyData/{sponsoredAccountUrn}?month={month}
Path Parameter
| Field | Format | Description | Required |
|---|---|---|---|
| sponsoredAccountUrn | SponsoredAccountUrn | URN of the sponsoredAccount for which the data should be retrieved. It is of type urn:li:sponsoredAccount:{sponsoredAccountId}. |
Yes |
Query Parameter
| Field | Format | Description | Required |
|---|---|---|---|
| month | int | monthYear for which the data is requested for. It is of format YYYYMM example, month=202309 |
Yes |
Validations and Minimum Requirements
- Data retrieval can only be done for advertisers whose billing information is in the EEA or Switzerland region.
- At any given time, once the developer is approved for access to the Advertiser Transparency API, the developer gets access to the prior six calendar months of data. For example, if a developer is approved for access in November of 2024, they would have access to the previous six months (from May 2024 - October 2024).
- The earliest available data is from March 6, 2024. The only exception here is for viewability data for display ads - the earliest available data is from the day the access is approved for the ad account. For example, if a developer is approved for access in November of 2024, they would have access to display viewability data from November 2024 onwards. We will not be able to backfill data outside of our retention policy.
- Reports for the preceding month will be available 12 days after the month ends [eg: the monthly report for September will be available after 12th October].
Sample Request
GET https://api.linkedin.com/rest/advertiserTransparencyData/urn%3Ali%3AsponsoredAccount%3A509090297?month=202311
X-Restli-Protocol-Version: 2.0.0
Linkedin-Version: {version number}
Authorization: Bearer {token}
Response Schema
| Field | Format | Description |
|---|---|---|
| downloadUrl | Url | Provides the Ambry URL endpoint for downloading advertiser transparency data. This URL will only be valid for 15 mins and will expire post that |
The URL will point to a CSV file, with the following content. Please note that access to the specific data fields below is based on your specific access rights.
| Field | Format | Description | Nullable |
|---|---|---|---|
| CampaignId | Integer | CampaignId associated with the creative | No |
| Page URL | String | URL where ad appeared. It can be null or have possible values - Linkedin home page (https://www.linkedin.com/feed/) or Company page URL (https://www.linkedin.com/company/ernstandyoung/) | Yes |
| Category of posts | Array[String] | List of categories of adjacent posts, it will be populated only if the ad was shown in Feed. Data shared is only limited to LinkedIn’s categorization of organic content (High/Mid) according to GARM brand safety floor and suitability frameworks Eg:[HATE_SPEECH_HIGH_RISK,GRAPHIC_CONTENT_MEDIUM_RISK] |
Yes |
| IPAddress | String | IPAddress where the entity was served, it could be IPv4 or IPv6 | No |
| UserAgent | String | UserAgent of the request | Yes |
| Platform type | Enum(String) | String enum with possible values as - WEB/ANDROID/IOS | Yes |
| Serving timestamp | Long | Epoch timestamp when request was served | No |
| Viewability AdFormat | Boolean | Signals the video ad occured, possible values are true/false | No |
| Video Started | Boolean | When the client video started or an individual creative within the ad was loaded and playback began. | Yes |
| Video viewed | Boolean | Playing for at least 2 continuous seconds 50% in-view. | Yes |
| Video First Quartile | Boolean | The creative played at 25% of the total duration at normal speed, including play that skipped to this point. | Yes |
| Video Second Quartile | Boolean | The creative played at 50% of the total duration at normal speed, including play that skipped to this point. | Yes |
| Video Third Quartile | Boolean | The creative played at 75% of the total duration at normal speed, including play that skipped to this point. | Yes |
| Video Completed | Boolean | The creative was played 97-100% of the total duration at normal speed in which the event will start firing at 97%. | Yes |
| Video Fully Completed | Boolean | The creative was played to 100% of the total duration at normal speed. | Yes |
| Ad Paused | Boolean | The user clicked the pause control and stopped the creative. | Yes |
| Ad Resumed | Boolean | The user activated the resume control after the creative had been stopped or paused. | Yes |
| Full Screen | Boolean | The user activated a control to full screen. | Yes |
| Seek | Boolean | The user activated a control to scrub over the video. | Yes |
| Click on play video | Boolean | The user clicked the play control for the video ad. | Yes |
| Replay video | Boolean | The user activated the replay control during playing the video ad. | Yes |
| One-pixel continuous time (ms) | Boolean | Maximum milliseconds of continuous time in which at least 1 pixel of the ad is in-view | Yes |
| 50 Percent continuous time (ms) | Boolean | Maximum milliseconds of continuous time in which at least 50% of the pixels of the ad are in-view | Yes |
| 80 Percent continuous time (ms) | Boolean | Maximum milliseconds of continuous time in which at least 80% of the pixels of the ad are in-view | Yes |
| 100 Percent continuous time (ms) | Boolean | Maximum milliseconds of continuous time in which at least 100% of the pixels of the ad are in-view | Yes |
| One-pixel cumulative time (ms) | Boolean | Milliseconds of cumulative time in which at least 1 pixel of the ad is in-view for any period | Yes |
| 50 Percent cumulative time (ms) | Boolean | Milliseconds of cumulative time in which at least 50% of the pixels of the ad are in-view | Yes |
| 80 Percent cumulative time (ms) | Boolean | Milliseconds of cumulative time in which at least 80% of the pixels of the ad are in-view | Yes |
| 100 Percent cumulative time (ms) | Boolean | Milliseconds of cumulative time in which at least 100% of the pixels of the ad are in-view | Yes |
Sample Response
{
"downloadUrl": "https://www.linkedin.com/ambry/?x-li-ambry-ep=AQJ5NgSW2VNjnwAAAYtliYavvNBT1RRBcug-ZsQATuFPj9B2gz-c71hhjTVbh1S02AX6RX4jQp0E_t8taTQgeMrv5PV8fmUK1kKWJS9BrEeGUg-sifqWApxFxtKgHKbCAXVfwRG2iGwM9gOo4IBVMqgf-g9lVINkDDqljL1v5KcNAeV4oQ_hs8nkLtCc_O6fTQj2p5CHnTz3vW7E4zSplAs4-J5dj0rvBePFH_R6_zPmtS892J7H0oJq3afYz-OlO7NzDa-kGHvIEq6HrrwF9vHSfrDAA19XbqYe55nTnhsKEkCAStlTzQwboFhlUjXudb2VRs_MtJvA9LO9D0eY7NInItp992pED8Us9t8YNJoTtHpxsNnwFSe2197k3GF3XWT-7Cg9VegO6AiyDQEnQ5ZsGz9173VscYWdOAtEfh9EHI5sEPFUzDmCqmSCVJ1YhZsxB0SGeJLB_vxAMpmVMSMOTrp8EdLba_Q6qbDAHq3KHk8_CWpZQ9X975kZZQ21AdcVGVTiZNB3J_oElv7alF4"
}
API Error Details
| HTTP Status Code | ERROR MESSAGE | DESCRIPTION | ERROR RESOLUTION |
|---|---|---|---|
| 400 | INVALID_ACCOUNT | Account present in the API request is of incorrect format | Make sure that sponsoredAccountUrn is of correct format |
| 400 | DATE_OLDER_THAN_SIX_MONTHS | Date can’t be older than 6 months | Request data for month within last 6 months of current date |
| 400 | ADVERTISER_NOT_IN_EEA_OR_SWITZERLAND | Advertiser is not eligible for retrieving data since they are not present in Switzerland/EEA region | Request data retrieval for advertisers that are present in EEA/Switzerland |
| 400 | Invalid monthYear parameter, should be of yyyyMM format | Invalid monthYear parameter, should be of yyyyMM format | Enter monthYear in yyyyMM format |
| 401 | EMPTY_ACCESS_TOKEN | Empty oauth2 access token | Use a valid member access token |
| 401 | INVALID_ACCESS_TOKEN | Invalid oauth2 access token | Use a valid member access token |
| 401 | REVOKED_ACCESS_TOKEN | The token used in the request has been revoked by the user | Make sure user has granted you access to their data |
| 403 | ACCESS_DENIED | Not enough permissions to access the resource | Make sure your developer application is provisioned with the required permissions. |
| 403 | USER_NOT_AUTHORIZED | Member present in the request does not have sufficient access to the Ad Account | Make sure the member associated with access token has a user role on the provided Ad Account |
| 404 | NOT_FOUND | Could not find entity. | Verify the provided entity ID is correct. |
| 404 | UNABLE_TO_FETCH_ADVERTISER_DETAILS | Unable to fetch billing details for the requested advertiser account | Make sure that the account is valid and has been configured correctly. |
| 500 | INTERNAL_SERVER_ERROR | Server encountered an unexpected condition that prevented it from fulfilling the request. | N/A |
Frequently Asked Questions
Please review our Advertiser Transparency FAQ
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for