Integration Requirements for the Lead Sync API Program

To become a formal Certified API Partner, LinkedIn has a technical sign off process for the Lead Sync API program. This ensures that our members get the best experience whether using LinkedIn's native UI or a partner product. The technical review and sign off also ensures that there are no gaps in integrations and that partner products keep up with the latest features and updates released by LinkedIn.

As an API partner, please go through the requirements listed below. These are the capabilities that an integrating partner is expected to build in their product. We request you to plan and incorporate these features early in your design. When you are nearing completion, you must initiate a Technical Sign Off request by contacting your LinkedIn POC on the Business Development team.

A Demo will be scheduled during which you will be asked to showcase all your product capabilities. During this evaluation, LinkedIn may suggest modifications which will need to be completed for the sign off. If all criteria are met (as per the envisioned scope), the technical sign-off is awarded.

Note

Joint Go-To-Market efforts can only begin after receiving the tech sign off.

Requirements

Rule	API capabilities to be demonstrated in Demo	Demo Type	Expectations
	Basics
LGF-001	Demonstrate OAuth 2.0 integration, with right scopes, consent screen	demo	Provide the list of scopes. We want to see the the flow with the consent screen via a live demo
LGF-002	Demonstrate ability to periodically verify that an access token is valid (heartbeat /me)	explanation	Please let us know which API is used and at what frequency (as a heartbeat) OR which API call happens on a regular basis (daily or more), that can act as a heartbreak and detect token expiry
LGF-003	Demonstrate ability to detect access token expiry	explanation	Provide an explanation of your OAuth flow. Do you use any standard OAuth libraries? Do you have a custom library for LinkedIn?
LGF-004	Demonstrate ability to retrigger OAuth Flow incase token has expired or been invalidated	demo	If both access and refresh tokens have expired or have been revoked by LinkedIn or the user, we expect you to fallback to retriggering the entire authorization code flow
LGF-005	Demonstrate ability to use refresh tokens to mint new access tokens	explanation	Provide an explanation of your OAuth flow
LGF-006	Demonstrate ability to detect refresh token expiry and retrigger OAuth Flow	explanation	If both access and refresh tokens have expired or have been revoked by LinkedIn or the user, we expect you to fallback to retriggering the entire authorization code flow
LGF-007	Demonstrate ability to check user access and permissions to start receiving leads	explanation & demo	- Demo a user who does not have sufficient permissions on the Company Page - Explain your permission/role check logic - We expect you to check if a member has sufficient privileges on the Sponsored Account and Company Page to sync leads
	Core
LGF-101	Demonstrate ability to: Retrieve all Sponsored Accounts with status for the authenticated user Retrieve all Organizations the authenticated user is an administrator of	demo	We expect Sponsored Ad Account numbers to be shown. Your integration should be able to support a user that manages more than one ad account and/or organization.
LGF-102	Demonstrate ability to read all forms available per sponsored account and organization	demo
LGF-103	Demonstrate ability to automatically read all predefined fields (predefinedField) of a form	demo
LGF-104	Demonstrate ability to read all custom questions (and options) of a form	demo
LGF-105	Demonstrate ability to read all Hidden Fields of a form	demo
LGF-106	Demonstrate ability to read all Consent texts of a form	demo
LGF-107	Demonstrate ability to create datastore/tables as required for a lead form	code screenshot & explanation	Show how Leads are stored. The goal is to ensure fields are not hard-coded with a static list of fields and can be configured depending on the list of fields available on different forms. Addition of new fields or new types of fields should not be a breaking change for partner implementations
LGF-108	Demonstrate ability to fetch all leads across all available leadTypes and store them in the data store	demo	For push or pull method, we suggest an automatic pull of past 365 days leads upon integration creation. LinkedIn stores lead data for 365 days
LGF-109	Demonstrate an end-to-end test, when a lead flows from Campaign Manager UI and a Company Page all the way to data store	demo
LGF-110	Demonstrate ability to teardown/delete integration	demo and API logs	When an integration is deleted via your UI any associated webhooks should deleted as well
LGF-111	Demonstrate a single field failure does not block the lead syncing	explanation
LGF-112	Demonstrate a single lead failure will not break syncing of other leads	explanation
LGF-113	Demonstrate mappings are based on predefined field (predefinedField) values when available (Custom questions do not have a predefinedField field)	demo
LGF-114	Demonstrate ability to use metadata fields while syncing in addition to the form fields (Form id, campaign id, account id, creative id, campaign name, account name, form name, event name, organization name, etc.)	demo
	Push implementation (best practice with pull backup)
LGF-201	Demonstrate ability to recover from outages, missed PUSH notifications	explanation	In the rare case where leads cannot be pulled in either due to a LinkedIn or Partner issue, we recommend pulling all leads periodically, for example, every 24 hours
LGF-202	Demonstrate ability to create/register and update webhooks	demo & API logs	Allow users to register for webhooks at the Sponsored account and Organization level
	Advanced Push implementation - nice to have but not required
LGF-203	[optional] Demonstrate ability to register and listen for webhooks at the associatedEntity or form level	demo & API logs
	Pull implementation
LGF-301	[optional] Demonstrate ability to recover from outages using a time-bound PULL request to get missed leads	explanation	In the rare case where leads cannot be pulled in either due to a LinkedIn or Partner issue, we recommend pulling all leads periodically, for example, every 24 hours
LGF-302	[optional] Demonstrate ability to re-pull leads periodically	explanation & API logs	Pull form responses on a fixed time period
	Advanced Pull implementation - nice to have but not required
LGF-303	[optional] Demonstrate ability to configure the intervals between PULL requests	demo & API logs	Allow users to configure frequency of pulling leads

Demo Scenarios

Rules Section	Demo Scenarios
Basics	1. Your application should be able to detect whether or not an access token has expired (TTL 60 days) or has been invalidated/revoked. You should be using an API call has a heartbeat to check for this every 24 hours (proactively catch issues for your users) - Expired → use refresh token to mint a new access token - Invalidated/revoked → Allow the user retrigger oauth flow and notify user in some way Tech sign off Demo: login to your platform and authenticate. Then go to linkedin.com > me > Settings & Privacy > Data Privacy > Permitted Services > Remove your app. Go back to your platform - what is the experience for the user? 2. Your application should be able to detect when a refresh token has expired (TTL is 365 days) - Expired → Allow the user retrigger oauth flow - Best practice → proactively notify the user that their token will be expiring in x number of days and they should reauthenticate to avoid any issues. Notification could be via email, in app, manual reach out, etc. Tech sign off Demo: Explanation
Core	What happens if the authenticated user doesn’t have access to any ad accounts or company pages (organization)? What does the UI experience look like? - Suggestion: display a message stating: “It looks like you don’t have access to any Ad Accounts/Organizations. Reach out to an Admin on your team to grant access. <Steps to do on your platform once they are granted access>.” Tech sign off Demo: How can you demo this? Only the ad accounts and organizations the authenticated user has access to will be returned via the API. To simulate this, for all of the ad accounts and company pages you have access to, have an account manager remove you OR create a test profile and authenticate as this user on your platform (see section 2.3 of API terms of use)
Push & Pull Implementation	How do you handle this scenario: What happens if the authenticated member that set up the lead syncing leaves the company and either a) goes to their linkedin profile and revokes or apps access OR b) their access is revoked from all ad accounts and or company pages. In both scenarios, the API calls will fail. Suggestion: - Your API calls should have a back off mechanism implemented so your app does not indefinitely call the LinkedIn APIs. - An error message should be displayed in the UI indicating what the issue is based off of the error message returned from the API. - In the case where the original authenticated user is no longer able to re-authenticate, your platform should provide the ability for a different user to authenticate and take over the scheduled syncs. How can you test this? Revoke access via linkedin.com or remove access to ad accounts an company pages for your testing authenticated user