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 |