Lead Sync Forms
Warning
Deprecation Notice
The Marketing Version 202311 (Marketing November 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
Warning
Deprecation Notice
The Ads Lead Sync APIs have been deprecated and will reach end of life at the end of July, 2024. New integrations should use the new Lead Sync APIs
Warning
Deprecation Notice
The Marketing Version 202311 (Marketing November 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
LinkedIn Lead Sync Forms make it easy for advertisers to collect leads through forms that LinkedIn members can submit. With Lead Sync Forms, advertisers can collect leads at much higher conversion rates. See LinkedIn Lead Sync Forms and Lead Sync Ads for more information.
The following APIs are available to work with Lead Sync Forms:
adForms- Create and manage forms that will appear on LinkedIn.adFormQuestions- Fetch individual form questions.adFormResponses- Fetch response data to ad forms.leadNotificationUrls- Register URLs to receive webhook notifications of new leads.
Permissions
Lead Sync is a separate program than the LinkedIn Marketing API Program. Access to the LinkedIn Marketing API Program does not automatically grant access to the above APIs. Developers must apply separately to be considered for Lead Sync APIs.
| Permission | Description | Endpoints |
|---|---|---|
| rw_ads | Manage and read an authenticated member's ad accounts data. Can manage and read ad forms. Cannot retrieve leads through adFormResponses. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
|
| r_ads | Read an authenticated member's ad accounts data. Can read ad forms. Cannot retrieve leads through adFormResponses. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
|
|
| r_ads_leadgen_automation | Access an authenticated member's ad forms and leads. Can manage and read leadNotificationUrls. This permission belongs to the Lead Sync program and is not granted automatically as part of the LinkedIn Marketing API Program. Restricted to ad accounts in which the authenticated member has one of the following ad account roles.
Pulling leads is restricted to company pages in which the authenticated member has one of the following company page/organization roles.
|
|
If the authenticated member does not have the appropriate ad account or company page/organization roles, we will return a 403 error.
See Account Access Controls for information on how to retrieve a member's ad account roles.
See Organization Access Control for information on how to retrieve a member's company page/organization roles.
Ad Forms
Ad Forms can be created and managed through the API to determine what data to request from members responding to the Ad Form. Ad Forms can include multiple questions, hidden fields, and custom consent checkboxes. Many of these components are structured as sub-objects of the Ad Form. In the next section, schemas of the parent and sub-objects are defined.
Ad Form Schema
| Field | Type | Description |
|---|---|---|
| account | SponsoredAccountUrn | URN identifying the owner of the form. This is the advertiser account. |
| locale | Locale | Locale of the form. The form can only be used for campaigns that target the same language as specified in the locale. |
| id | long | Numerical identifier for the form. |
| form | Form | The content of the form including name, description, question, consent checkbox, landing URL, privacy policy, etc. |
| reviewInfo | ReviewInfo | The reasons for rejection (if rejected), the date of review, and the status. |
| created.time | Long | Creation time. |
| lastModified.time | Long | Last modified time. |
| versionTag | String | The number of times the form has been modified. |
| status | String | DRAFT, SUBMITTED, PAUSED, ARCHIVED, or CANCELED. Draft allows for editing. Submitted is servable if approved. Paused is stopped from serving by the advertiser. Archived is stopped from serving and should be separated from non-archived forms in any UI. Canceled forms cannot be used again, and all associated creatives will be canceled too. |
Form Sub-Object
An Ad Form may contain one form sub-object which defines the content.
| Field | Type | Description |
|---|---|---|
| description | Optional String | Description of the form, visible to both the owner and the viewer. |
| headline | Optional String | Headline of the form, visible to both the owner and the viewer. |
| hiddenFields | Array of AdFormHiddenField default="[]" | The hidden fields which are not shown to viewers and only used by advertisers to track some key attributes of the form that generated the lead. Each form can have 0~20 hidden fields. |
| landingPage | Optional URL | The landing page URL after the viewer clicks on submit. If omitted, the form will be submitted and a thank you page will be shown to the viewer. |
| name | String | Name of the form, visible to the owner of the form but not visible to the viewer. |
| privacyPolicy | URL | The URL of the privacy policy that covers any data passed to the owner of the form. |
| questions | Array of Questions | Questions to request information from the viewer. |
| consents | Array of Consents | Consent checkboxes to present to the viewer. |
| thankYouMessage | optional string | The message displayed to a member after the form is submitted. The max size is 300 characters. |
| legalDisclaimer | string | Advertiser's legal disclaimer to accompany this form. This is shown to the viewer in addition to a standard LinkedIn legal disclaimer. The max size is 2000 characters. |
| thankYouPageCallToAction | optional string | The message displayed on the call-to-action button. It can be set to one of these values: LEARN_MORE, VIEW_NOW, DOWNLOAD_NOW, TRY_NOW, VISIT_COMPANY_WEBSITE (default). Note: This is just the text on the button. The URL is controlled by the landingUrl attribute. |
Question Sub-Object
questions is a sub-object of form that is structured as an array of questions. Each question represents information you would like to request from the member.
Questions can use predefined fields that would be pre-filled based on the member's profile data. While these fields are pre-filled, members can edit them as they wish at form submission. This functionality is controlled by specifying an enum value in the predefinedField setting on questions. For example, setting predefinedField=INDUSTRY would pre-fill the industry the member works in.
Custom questions are also supported allowing you to ask members for information that cannot be pre-filled. Leave predefinedField blank to create a custom question that the member must manually answer.
Custom questions should only be used for requesting information not available under predefined fields. Predefined fields are preferable because they are localized.
Currently, the maximum number of total questions is 12. This includes both predefined and custom questions. Lead Sync integrations should be able to dynamically handle more than 12 questions if this limit changes.
| Field | Type | Description |
|---|---|---|
| description | Optional String | The description of the question. |
| predefinedField | Optional predefinedField | The predefined member profile field that the question is requesting. Possible predefinedField values are defined in the next table. This field will be empty for custom questions. |
| name | String | Name of the question, shown to the advertiser only. |
| question | String | The question shown to the viewer. |
| questionId | Int | Index of the question. Optional to provide when creating the form. |
| typeSpecificQuestionDetails | Union of TextQuestionDetails key-value attributes | The type specific details of the question, including default answer, answer restrictions, etc. Only text questions are allowed. |
Possible predefinedField values:
| Value | Description |
|---|---|
| FIRST_NAME | The first name of the member. |
| LAST_NAME | The last name of the member. |
| PHONE_NUMBER | The phone number of the member. |
| WORK_PHONE_NUMBER | The work phone number of the member. |
| The email of the member. | |
| WORK_EMAIL | The work email address of the member. |
| LINKEDIN_PROFILE_LINK | The LinkedIn profile link of the member. Available from September 25, 2019. |
| CITY | The city of the member. |
| STATE | The state of the member. |
| COUNTRY | The country of the member. |
| ZIP_CODE | The postal code or zip code of the member. |
| JOB_TITLE | The latest job title of the member. |
| JOB_FUNCTION | The job function of the member's latest job. |
| SENIORITY | The seniority of the member's job title, i.e. manager, director, VP, etc. |
| COMPANY_NAME | The name of the company of the member's latest job. |
| COMPANY_SIZE | The size of the company of the members latest job. |
| INDUSTRY | Localizable name of industry as entered by the member. |
| DEGREE | Degree attained of the member at the latest school attended. |
| FIELD_OF_STUDY | The field of study for the member's latest school attended. |
| SCHOOL | The school name for the member's latest education. |
| START_DATE | The start date at the latest school attended. |
| GRADUATION_DATE | The graduation date at the latest school attended. |
Hidden Field Sub-Object
hiddenFields is a sub-object of form that is structured as an array of hidden fields. Hidden fields are not displayed on the form, but can be used by advertisers for tracking purposes.
The maximum number of hidden fields is 20.
| Field | Type | Description |
|---|---|---|
| name | string | The name of the hidden field. |
| value | string | The content of the hidden field. |
Consents Sub-Object Schema
With consent checkboxes, you can collect separate, optional consents for the permission to send and use collected member data through Ad Forms. You can present up to 5 custom checkboxes with custom messaging, which allows you to ask for specific permissions for how a member's data is used or transmitted.
You can configure the checkboxes to be required or not required in consentRequired in order to submit the form.
| Field | Type | Description |
|---|---|---|
| consent | String | The checkbox message shown to the viewer. |
| consentRequired | Boolean | Indicates if the viewer must click the consent checkbox to submit the form. |
| consentId | Optional Int | Index of the consent checkbox. Optional when creating the form. |
Fetching Ad Forms
Ad Forms can be fetched 3 different ways.
- Fetch all forms associated with an Ad Account
- Fetch an individual form
- Fetch multiple specified forms
Fetch All Forms for an Ad Account
This endpoint returns all forms that belong to a specified Ad Account. This endpoint requires q=account and a sponsoredAccount URN in the account parameter.
Since an Ad Account can have a large volume of Ad Forms, this API supports pagination using the count and start parameters. Using the totals parameter instructs the downstream service to calculate the total number of existing entries.
Parameters
| Parameter | Type | Description |
|---|---|---|
| q | String | You must always set this to account. It indicates that you're querying based on account, and it's the only FINDER type currently available for ad forms. |
| account | SponsoredAccountUrn | URN identifying the owner of the form. This is the advertiser account. |
| count | Number | How many results to display on each page. |
| start | Number | The index of the form to begin your result page at. Indexes start at 0. Default is 0. |
| totals | Boolean | If true, the total value of the paging metadata in the result will be calculated. This metadata is useful to know how many total ad forms entries you have for this account. |
Sample Request
Sample Response
{
"elements": [
{
"account": "urn:li:sponsoredAccount:505303614",
"changeAuditStamps": {
"created": {
"time": 1533171156000
},
"lastModified": {
"time": 1533177577000
}
},
"created": {
"time": 1533171156000
},
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
},
{
"name": "myHiddenField2",
"value": "LSNR-4567-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer which is mandatory",
"name": "My Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"memberProfileField": "FIRST_NAME",
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"memberProfileField": "EMAIL",
"name": "email",
"predefinedField": "EMAIL",
"question": "Email address",
"questionId": 2,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have a multiple choice question for you! ?",
"questionId": 3,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
},
{
"name": "customTextQuestion",
"question": "I have a text question for you! ?",
"questionId": 4,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentId": 0,
"consentRequired": true,
"content": "This is a required checkbox"
},
{
"consentId": 1,
"consentRequired": false,
"content": "This is an optional checkbox"
}
],
"thankYouMessage": "thanks!",
"thankYouPageCallToAction": "VISIT_COMPANY_WEBSITE"
},
"id": 645434,
"lastModified": {
"time": 1533177577000
},
"locale": {
"country": "US",
"language": "en"
},
"reviewInfo": {
"rejectionReasons": [],
"reviewStatus": "APPROVED",
"reviewedAt": 1533177577261
},
"status": "SUBMITTED",
"version": {
"versionTag": "3"
},
"versionTag": "3"
}
]
}
Fetch an Ad Form
Individual Ad Forms can be requested using the endpoint below that only requires an Ad Form ID.
Sample Request
Sample Response
{
"account": "urn:li:sponsoredAccount:500612780",
"changeAuditStamps": {
"created": {
"time": 1500508960000
},
"lastModified": {
"time": 1500510251000
}
},
"created": {
"time": 1500508960000
},
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
},
{
"name": "myHiddenField2",
"value": "LSNR-4567-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer",
"name": "My UPDATED Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"memberProfileField": "FIRST_NAME",
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have a multiple choice question for you! ?",
"questionId": 2,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
}
],
"consents": [
{
"consentId": 0,
"consentRequired": true,
"content": "This is a required checkbox"
},
{
"consentId": 1,
"consentRequired": false,
"content": "This is an optional checkbox"
}
],
"thankYouMessage": "thanks!"
},
"id": 12345,
"lastModified": {
"time": 1500510251000
},
"locale": {
"country": "US",
"language": "en"
},
"status": "DRAFT",
"version": {
"versionTag": "3"
},
"versionTag": "3"
}
Fetch Multiple Ad Forms
Multiple Ad Forms can be requested by chaining multiple ids parameter that each have an Ad Form ID.
Sample Request
Sample Response
{
"errors": {},
"results": {
"4073": {
"account": "urn:li:sponsoredAccount:512086349",
"created": {
"time": 1484786822000
},
"form": {
"description": "Some description goes here",
"headline": "This is my form",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-5678-LI-MKTG"
}
],
"landingPage": "http://anotherexample.com",
"legalDisclaimer": "This is a legal disclaimer",
"name": "XYZ",
"privacyPolicy": "http://anotherexample.com",
"questions": [
{
"name": "Email address",
"predefinedField": "EMAIL",
"question": "Email address",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentId": 0,
"consentRequired": true,
"content": "This is a required checkbox"
},
{
"consentId": 1,
"consentRequired": false,
"content": "This is an optional checkbox"
}
],
"thankYouMessage": "Thank you!"
},
"id": 4073,
"lastModified": {
"time": 1484786822000
},
"locale": {
"country": "US",
"language": "en"
},
"reviewInfo": {
"rejectionReasons": [],
"reviewStatus": "AUTO_APPROVED",
"reviewedAt": 1484786822843
},
"status": "SUBMITTED",
"versionTag": "1"
},
"6083": {
"account": "urn:li:sponsoredAccount:511183580",
"created": {
"time": 1484786822000
},
"form": {
"description": "Detail",
"headline": "Headline",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
}
],
"landingPage": "http://example.com",
"legalDisclaimer": "This is a legal disclaimer",
"name": "Abc",
"privacyPolicy": "http://example.com",
"questions": [
{
"name": "First name",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "Email address",
"predefinedField": "EMAIL",
"question": "Email address",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [],
"thankYouMessage": "Thanks"
},
"id": 6083,
"lastModified": {
"time": 1484786822000
},
"locale": {
"country": "US",
"language": "en"
},
"reviewInfo": {
"rejectionReasons": [],
"reviewStatus": "AUTO_APPROVED",
"reviewedAt": 1484786822843
},
"status": "SUBMITTED",
"versionTag": "1"
}
},
"statuses": {}
}
Creating Ad Forms
When setting the locale, note that non-English forms can only be used for campaigns targeting that language, but English forms can be used with any campaign.
The schema for creating an Ad Form is defined in the sample request below.
Sample Request
POST https://api.linkedin.com/rest/adForms
{
"account": "urn:li:sponsoredAccount:500612780",
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
},
{
"name": "myHiddenField2",
"value": "LSNR-4567-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer which is mandatory",
"name": "My Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First Name",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "email",
"predefinedField": "EMAIL",
"question": "Email Address",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have a multiple choice question for you! ?",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
},
{
"name": "customTextQuestion",
"question": "I have a text question for you! ?",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentRequired": true,
"content": "This a required checkbox"
},
{
"consentRequired": false,
"content": "This is an optional checkbox"
}
],
"thankYouMessage": "thanks!",
"thankYouPageCallToAction": "VISIT_COMPANY_WEBSITE"
},
"locale": {
"country": "US",
"language": "en"
},
"status": "DRAFT"
}
POST https://api.linkedin.com/v2/adForms
{
"account": "urn:li:sponsoredAccount:500612780",
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
},
{
"name": "myHiddenField2",
"value": "LSNR-4567-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer which is mandatory",
"name": "My Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First Name",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "email",
"predefinedField": "EMAIL",
"question": "Email Address",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have a multiple choice question for you! ?",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
},
{
"name": "customTextQuestion",
"question": "I have a text question for you! ?",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentRequired": true,
"content": "This a required checkbox"
},
{
"consentRequired": false,
"content": "This is an optional checkbox"
}
],
"thankYouMessage": "thanks!",
"thankYouPageCallToAction": "VISIT_COMPANY_WEBSITE"
},
"locale": {
"country": "US",
"language": "en"
},
"status": "DRAFT"
}
A successful response returns a 201 Created HTTP status code and the ID of the form in the x-linkedin-id response header.
Custom Text Questions
Free form text questions can be included in forms. The response lengths must be between 1 and 300 characters.
{
"name": "customTextQuestion",
"question": "I have a text question for you! ?",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
Custom Multiple Choice Question
Multiple choice questions can be included in forms. These questions require a minimum of 2 options. They can have up to 5 options.
The following example creates an multiple choice question with 3 options.
{
"name": "customMCQ",
"question": "I have a multiple choice question for you!",
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
}
Updating Ad Forms
You can update ad forms while they are in two states: pre-published and published.
Pre-Published State
An Ad Form is in a pre-published state when one of the following conditions is met.
- Form is in
DRAFTstatus. - Form is not linked to an Ad Creative.
- Form is only linked to Ad Creatives that are part of
DRAFTAd Campaigns.
In this state, you can update all fields in the form.
Important
Advertisers may have linked their forms to 3rd-party applications such as CRM or Marketing Automation tools. Editing a form after its schema has been ingested into the 3rd-party application may break ingestion of lead data. LinkedIn recommends warning users of this risk if your application allows editing of forms. Please advise the user to complete the following steps after editing.
- Delete previously created test leads synced to any 3rd-party partner applications they use.
- Re-map the form schema with the updated form fields in the 3rd-party application.
Published State
If an Ad Form does not meet the above conditions, it is in the published state. In this state, you can edit the following fields:
- headline
- description
- legalDisclaimer
- landingPageUrl
- privacyPageUrl
- thankYouMessage
- thankYouPageCta
- status
Ad Forms linked to Sponsored InMail and Conversation Ads cannot be edited in this state.
Sample Request
Make sure to set the Content-Type header to application/json.
Even if making partial updates to the form, you still need to send the entire form body.
POST https://api.linkedin.com/rest/adForms/656
{
"patch": {
"$set": {
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer which is mandatory",
"name": "My UPDATED Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"memberProfileField": "FIRST_NAME",
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"memberProfileField": "EMAIL",
"name": "email",
"predefinedField": "EMAIL",
"question": "Email address",
"questionId": 2,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have an UPDATED multiple choice question for you! ?",
"questionId": 3,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "Added a fourth option (update)"
}
}
]
}
}
},
{
"name": "customTextQuestion",
"question": "I have an UPDATED text question for you!",
"questionId": 4,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentId": 0,
"consentRequired": true,
"content": "This is an updated required checkbox"
},
{
"consentId": 1,
"consentRequired": false,
"content": "This is an updated optional checkbox"
},
{
"consentId": 2,
"consentRequired": false,
"content": "Added an additional optional checkbox"
}
],
"thankYouMessage": "thanks!"
}
}
}
}
POST https://api.linkedin.com/v2/adForms/656
{
"patch": {
"$set": {
"form": {
"description": "Amazing offer description.",
"headline": "Offer!",
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
}
],
"landingPage": "http://example.com/landingPage",
"legalDisclaimer": "This is a legal disclaimer which is mandatory",
"name": "My UPDATED Form (with custom questions)",
"privacyPolicy": "http://example.com/privacy",
"questions": [
{
"memberProfileField": "FIRST_NAME",
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"memberProfileField": "EMAIL",
"name": "email",
"predefinedField": "EMAIL",
"question": "Email address",
"questionId": 2,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
{
"name": "customMCQ",
"question": "I have an UPDATED multiple choice question for you! ?",
"questionId": 3,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "Added a fourth option (update)"
}
}
]
}
}
},
{
"name": "customTextQuestion",
"question": "I have an UPDATED text question for you!",
"questionId": 4,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
],
"consents": [
{
"consentId": 0,
"consentRequired": true,
"content": "This is an updated required checkbox"
},
{
"consentId": 1,
"consentRequired": false,
"content": "This is an updated optional checkbox"
},
{
"consentId": 2,
"consentRequired": false,
"content": "Added an additional optional checkbox"
}
],
"thankYouMessage": "thanks!"
}
}
}
}
A successful response returns a 204 No Content HTTP status code.
If the form is not in an editable state or you attempt to edit an uneditable field, you will receive a 400 Bad Request error.
Updating Form Status
Form status can be changed from SUBMITTED to PAUSED, ARCHIVED or CANCELED status. This can be done using a partial update request. Note that the status change only affects whether the form and the associated creative gets served or not. Including the entire form body is not required to change status.
Sample Request
Fetching Ad Form Questions
The Ad Form Questions API provides details on individual Lead Sync questions. These can be fetched individually or as a batch request.
Fetch a Single Ad Form Question
An individual Ad Form Question can be requested by passing in an adForm URN in form and the ID in questionID.
Sample Request
Sample Response
{
"name": "First Name",
"predefinedField": "FIRST_NAME",
"question": "First Name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
}
Fetch Multiple Ad Form Questions
Multiple Ad Form Questions can be requested by passing in multiple pairs of adForm URNs and questionId. Each pair should be passed in as an array of ids parameters. For example, ids[0].form={adFormUrn}&ids[0].questionId={questionId} would be one pair. A second pair in the same API call would be ids[1].form={adFormUrn}&ids[1].questionId={questionId}.
Special characters like [ or : must be URL encoded. An unencoded sample request is available below for readability.
Unencoded Sample Request
Encoded Sample Request
Sample Response
{
"errors": {},
"results": {
"form=urn%3Ali%3AadForm%3A123314&questionId=1": {
"memberProfileField": "FIRST_NAME",
"name": "firstName",
"predefinedField": "FIRST_NAME",
"question": "First name",
"questionId": 1,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.TextQuestionDetails": {}
}
},
"form=urn%3Ali%3AadForm%3A123314&questionId=2": {
"name": "customMCQ",
"question": "I have a multiple choice question for you! ?",
"questionId": 2,
"typeSpecificQuestionDetails": {
"com.linkedin.ads.MultipleChoiceQuestionDetails": {
"options": [
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your first option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your second option"
}
},
{
"com.linkedin.ads.TextOptionQuestion": {
"text": "This is your third option"
}
}
]
}
}
}
},
"statuses": {}
}
Fetching Ad Form Responses
The Ad Form Responses API returns the response data for leads that filled out a form within the last 90 days. Older responses are not included. Collecting Ad Form Responses requires certain criteria to be met. For more information on required permissions to access leads, see the help page.
Push vs. Pull
Syncing leads from LinkedIn can be done using two workflows. The Push model utilizes webhook notifications to listen for alerts of new leads immediately after they are created in LinkedIn. The Pull model periodically queries our API checking for new leads since the last query.
The most robust integrations will implement both these workflows to optimize for both speed and reliability. If only one workflow can be implemented, we recommend the Push model.
Ad Form Response Schema
| Field | Type | Description |
|---|---|---|
| account | SponsoredAccountUrn | The URN that describes which account the response was generated under. |
| campaign | SponsoredCampaignUrn | URN identifying the campaign to which the form response is responding. |
| creative | SponsoredCreativeUrn | URN identifying the creative to which the form response is responding. |
| form | AdFormUrn | URN identifying which form this response responds to. |
| formResponse | FormResponse | Answers provided by a member to questions and consents. |
| id | AdFormResponseUrn | URN identifying the ad form response. |
| leadType | LeadType | Type of the lead. This field indicates whether the lead is collected from sponsored content or viral share. |
| testLead | boolean, default=false | Determines whether this is an advertiser created test lead. |
Fetch Responses by Ad Account
Respones can be retrieved for a specified Ad Account. This endpoint takes in 2 required parameters: q=account and account={adAccountUrn}.
Responses can be further filtered based on a variety of parameters such as time range, Ad Form, or campaign. See the list of parameters for all the possibilities.
Note
Ensure that the keys in the query adhere to the hierarchy of advertiserId/formId/leadType/campaignId/creativeId/memberId. If any sub-key is missing, the corresponding sub-keys lower in the hierarchy cannot be specified. For example, both the formId and leadType must be included in the request before filtering based on the campaign can be applied.
Parameters
| Parameter | Type | Description |
|---|---|---|
| account | SponsoredAccountUrn | The URN which describes which account the response is generated under. |
| campaign | SponsoredCampaignUrn (optional) | URN identifying the campaign to which the form response is responding. |
| creative | SponsoredCreativeUrn (optional) | URN identifying the creative to which the form response is responding. |
| form | AdFormUrn (optional) | URN identifying which form this response responds to. |
| leadType | LeadType (optional) | Type of the lead. This field indicates whether the lead is collected from sponsored content or viral share. Defaults to SPONSORED. |
| timeRange.start and timeRange.end | Long (optional) | Number of milliseconds since midnight, January 1, 1970 UTC. It must be a positive number. |
Sample Request
This example includes additional non-required parameters specifying an adForm URN and projection. The projection parameter is used to select only certain fields and decorate the response. See our pages on Projection and Decoration for more information on how to use these.
GET https://api.linkedin.com/rest/adFormResponses?q=account&account=urn:li:sponsoredAccount:507543058&form=urn:li:adForm:506416&projection=(paging,elements*(id,account,form~(form(hiddenFields)),campaign,creative,leadType,testLead,formResponse(consentResponses,submittedAt,answers*(question~(name),answerDetails))))
GET https://api.linkedin.com/v2/adFormResponses?q=account&account=urn:li:sponsoredAccount:507543058&form=urn:li:adForm:506416&projection=(paging,elements*(id,account,form~(form(hiddenFields)),campaign,creative,leadType,testLead,formResponse(consentResponses,submittedAt,answers*(question~(name),answerDetails))))
Sample Response
{
"elements": [
{
"account": "urn:li:sponsoredAccount:507543058",
"campaign": "urn:li:sponsoredCampaign:132826556",
"creative": "urn:li:sponsoredCreative:56171166",
"form": "urn:li:adForm:506416",
"formResponse": {
"answers": [
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "newlead@example.com"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:506416,2)",
"question~": {
"name": "email"
}
},
{
"answerDetails": {
"com.linkedin.ads.MultipleChoiceAnswer": {
"options": [
{
"com.linkedin.ads.TextOptionAnswer": {
"index": 0
}
}
]
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:506416,3)",
"question~": {
"name": "customMCQ"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "1532630375"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:506416,4)",
"question~": {
"name": "customTextQuestion"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "Kevin"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:506416,1)",
"question~": {
"name": "firstName"
}
}
],
"submittedAt": 1532642045682,
"consentResponses": [
{
"accepted": false,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,0)"
},
{
"accepted": false,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,1)"
}
]
},
"form~": {
"form": {
"hiddenFields": [
{
"name": "myHiddenField1",
"value": "LSNR-1234-LI-MKTG"
},
{
"name": "myHiddenField2",
"value": "LSNR-4567-LI-MKTG"
}
]
}
},
"id": "urn:li:adFormResponse:34d3a849-8aa3-432d-9325-58d0a4b53958-4",
"leadType": "SPONSORED",
"testLead": true
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
Fetch a Single Ad Form Response
If you already know the ID of the lead you wish to fetch, you can get the responses directly by passing the ID and the associated Ad Account.
Sample Request
This example includes a projection parameter that is used to select only certain fields and decorate the response. Response decoration can be used to fetch fields for associated objects such as the Ad Creative or Ad Form linked to this lead without having to make additional calls to those endpoints. See our pages on Projection and Decoration for more information on how to use these.
GET https://api.linkedin.com/rest/adFormResponses/34d3a849-8aa3-432d-9325-58d0a4b53958-4?account=urn:li:sponsoredAccount:507543058&projection=(id,account~(id,name),campaign~(id,name),creative~(variables(data(*(*,share~(*),userGeneratedContentPost~(*))))),leadType,formResponse(submittedAt,answers*(answerDetails,question~(name,question,predefinedField,typeSpecificQuestionDetails,questionId)),consentResponses*(accepted,consent~(*))),form~(form(hiddenFields*(name,value))))
GET https://api.linkedin.com/v2/adFormResponses/34d3a849-8aa3-432d-9325-58d0a4b53958-4?account=urn:li:sponsoredAccount:507543058&projection=(id,account~(id,name),campaign~(id,name),creative~(variables(data(*(*,share~(*),userGeneratedContentPost~(*))))),leadType,formResponse(submittedAt,answers*(answerDetails,question~(name,question,predefinedField,typeSpecificQuestionDetails,questionId)),consentResponses*(accepted,consent~(*))),form~(form(hiddenFields*(name,value))))
Sample Response
{
"creative~":{
"variables":{
"data":{
"com.linkedin.ads.SponsoredUpdateCreativeVariables":{
"activity":"urn:li:activity:1234",
"callToActionEnabled":false,
"sponsoredStatusUpdateContentType":"TEXT",
"share":"urn:li:share:1234",
"share~":{
"owner":"urn:li:organization:1234",
"agent":"urn:li:sponsoredAccount:507543058",
"activity":"urn:li:activity:1234",
"edited":true,
"created":{
"actor":"urn:li:person:abcd-vwxyz",
"time":1582767200176
},
"subject":"new test ad",
"content":{
"contentEntities":[
{
"description":"Use LinkedIn self-service ads to target and reach more than 610 million professionals worldwide.",
"entityLocation":"https://www.linkedin.com/ads",
"title":"LinkedIn Marketing Solutions",
"thumbnails":[
{
"imageSpecificContent":{
"width":800,
"height":800
},
"resolvedUrl":"https://media-exp1.licdn.com/dms/image/sync/C4D27AQEMLymLIED8YA/articleshare-shrink_800/0/1588683591731?e=1613764800&v=beta&t=DQmOBwkbF_pCcbyb7SN2aXf9JW_tIgtD5Jl6rXBjqj0"
}
],
"entity":"urn:li:article:1234"
}
],
"shareMediaCategory":"ARTICLE",
"description":"Use LinkedIn self-service ads to target and reach more than 610 million professionals worldwide.",
"title":"LinkedIn Marketing Solutions"
},
"clientApp":"urn:li:developerApplication:1234",
"id":"1234",
"lastModified":{
"actor":"urn:li:csUser:0",
"time":1598298244330
},
"text":{
"text":"Connect to Opportunity on LinkedIn"
}
},
"directSponsoredContent":true
}
}
}
},
"form~":{
"form":{
"hiddenFields":[
{
"name":"test initiative",
"value":"test campaign"
}
]
}
},
"account~":{
"name":"Test Account",
"id":507543058
},
"creative":"urn:li:sponsoredCreative:1234",
"form":"urn:li:adForm:1234",
"leadType":"SPONSORED",
"campaign":"urn:li:sponsoredCampaign:1234",
"campaign~":{
"name":"Lead generation - Feb 12, 2019",
"id":1234
},
"id":"urn:li:adFormResponse:34d3a849-8aa3-432d-9325-58d0a4b53958-4",
"account":"urn:li:sponsoredAccount:507543058",
"formResponse":{
"answers":[
{
"question":"urn:li:adFormQuestion:(urn:li:adForm:1234,1)",
"answerDetails":{
"com.linkedin.ads.TextQuestionAnswer":{
"answer":"Test"
}
},
"question~":{
"questionId":1,
"question":"First name",
"typeSpecificQuestionDetails":{
"com.linkedin.ads.TextQuestionDetails":{
}
},
"name":"First name",
"predefinedField":"FIRST_NAME"
}
},
{
"question":"urn:li:adFormQuestion:(urn:li:adForm:1234,2)",
"answerDetails":{
"com.linkedin.ads.TextQuestionAnswer":{
"answer":"McTester"
}
},
"question~":{
"questionId":2,
"question":"Last name",
"typeSpecificQuestionDetails":{
"com.linkedin.ads.TextQuestionDetails":{
}
},
"name":"Last name",
"predefinedField":"LAST_NAME"
}
},
{
"question":"urn:li:adFormQuestion:(urn:li:adForm:1234,3)",
"answerDetails":{
"com.linkedin.ads.TextQuestionAnswer":{
"answer":"2ndtestforduplicate@testerson.com"
}
},
"question~":{
"questionId":3,
"question":"Work email",
"typeSpecificQuestionDetails":{
"com.linkedin.ads.TextQuestionDetails":{
}
},
"name":"Work email",
"predefinedField":"WORK_EMAIL"
}
},
{
"question":"urn:li:adFormQuestion:(urn:li:adForm:1234,4)",
"answerDetails":{
"com.linkedin.ads.TextQuestionAnswer":{
"answer":"LinkedIn"
}
},
"question~":{
"questionId":4,
"question":"Company name",
"typeSpecificQuestionDetails":{
"com.linkedin.ads.TextQuestionDetails":{
}
},
"name":"Company name",
"predefinedField":"COMPANY_NAME"
}
}
],
"submittedAt":1608141037794,
"consentResponses":[
{
"accepted":false,
"consent":"urn:li:adFormConsent:(urn:li:adForm:1234,0)",
"consent~":{
"consentId":0,
"consentRequired":false,
"content":"I consent to receive monthly emails from LinkedIn"
}
}
]
}
}
Fetch Multiple Ad Form Responses
If you already know the ID of multiple leads you wish to fetch, you can fetch multiple responses by passing in the Ad Account and chaining together multiple ids parameters.
The maximum number of permitted ids is 1000.
Sample Request
This example includes a projection parameter that is used to select only certain fields and decorate the response. See our pages on Projection and Decoration for more information on how to use these.
GET https://api.linkedin.com/rest/adFormResponses?account=urn:li:sponsoredAccount:507426820&ids=98dd5df4-805d-4bc3-966a-60cb14211cbd&ids=25869cf6-1fc9-47ab-86cb-ea78af9b0633&projection=(results*(id,account,form,campaign,creative,leadType,formResponse(consentResponses,submittedAt,answers*(question~(name),answerDetails))))
GET https://api.linkedin.com/v2/adFormResponses?account=urn:li:sponsoredAccount:507426820&ids=98dd5df4-805d-4bc3-966a-60cb14211cbd&ids=25869cf6-1fc9-47ab-86cb-ea78af9b0633&projection=(results*(id,account,form,campaign,creative,leadType,formResponse(consentResponses,submittedAt,answers*(question~(name),answerDetails))))
Sample Response
{
"results": {
"25869cf6-1fc9-47ab-86cb-ea78af9b0633": {
"account": "urn:li:sponsoredAccount:507426820",
"campaign": "urn:li:sponsoredCampaign:123578756",
"creative": "urn:li:sponsoredCreative:42314246",
"form": "urn:li:adForm:436",
"formResponse": {
"answers": [
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "Peter"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,1)",
"question~": {
"name": "First name"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "Cushing"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,2)",
"question~": {
"name": "Last name"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "tarkin@starwars.com"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,3)",
"question~": {
"name": "Email address"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "(123) 456-7890"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,4)",
"question~": {
"name": "Phone number"
}
}
],
"submittedAt": 1484836017000,
"consentResponses": [
{
"accepted": false,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,0)"
},
{
"accepted": true,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,1)"
}
]
},
"id": "urn:li:adFormResponse:25869cf6-1fc9-47ab-86cb-ea78af9b0633",
"leadType": "SPONSORED"
},
"98dd5df4-805d-4bc3-966a-60cb14211cbd": {
"account": "urn:li:sponsoredAccount:507426820",
"campaign": "urn:li:sponsoredCampaign:123578756",
"creative": "urn:li:sponsoredCreative:42314246",
"form": "urn:li:adForm:436",
"formResponse": {
"answers": [
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "Alec"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,1)",
"question~": {
"name": "First name"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "Guinness"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,2)",
"question~": {
"name": "Last name"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "obiwan@starwars.com"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,3)",
"question~": {
"name": "Email address"
}
},
{
"answerDetails": {
"com.linkedin.ads.TextQuestionAnswer": {
"answer": "(123) 456-7890"
}
},
"question": "urn:li:adFormQuestion:(urn:li:adForm:436,4)",
"question~": {
"name": "Phone number"
}
}
],
"submittedAt": 1484828817000,
"consentResponses": [
{
"accepted": true,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,0)"
},
{
"accepted": true,
"consent": "urn:li:adFormConsent:(urn:li:adForm:179744,1)"
}
]
},
"id": "urn:li:adFormResponse:98dd5df4-805d-4bc3-966a-60cb14211cbd",
"leadType": "SPONSORED"
}
}
}
Test Leads
Test leads can be generated from the Campaign Manager UI. These leads can then be downloaded via the Ad Form Response API or UI. The testLead field on a response will be equal to true for test leads.
Test leads currently cannot be generated for InMail campaigns with lead forms.
Deleting draft campaigns associated with test leads is not recommended. Test leads linked to a deleted campaign will still be downloadable, but the associated campaign will no longer be retrievable which may cause problems in some integrations.
More information on generating test leads is available in Sending a Test Lead in Campaign Manager.
Lead Notification Webhooks
You can register URLs to receive webhook notifications of new leads. Only HTTPS URLs are supported.
Your application must have an access token with the r_ads_leadgen_automation permission to use this API.
Schema
| Field | Type | Description |
|---|---|---|
| key | Compound key | Takes a developerApplication URN and a sponsoredEntity. See the following table for more information. |
| status | Enum | ACTIVE, PAUSED, or CANCELED. Paused URLs do not receive push notifications. Canceled URLs are permanently canceled. |
| URL | String | Must be an HTTPS URL with a domain ending in .com, .net, or .io. |
| Field | Type | Description |
|---|---|---|
| key.developerApplication | developerApplication URN | Entity representing the developer application that should receive notifications. This is constructable. You can retrieve your application's ID by visiting https://www.linkedin.com/developers/apps and selecting your application. The numeric ID in your browser's address bar is your application ID. Use the ID in the developerApplication URN. For example urn:li:developerApplication:12345. |
| key.sponsoredEntity | sponsoredAccount URN, sponsoredCampaign URN, or sponsoredCreative URN | The sponsored entity that you would like to receive webhooks for. You will receive notifications only for the requested sponsored entity. sponsoredAccount triggers notifications for all leads generated by Ad Campaigns within that Ad Account. sponsoredCampaign triggers notifications only for leads generated by the requested Ad Campaign. sponsoredCreative triggers notifications for all leads generated by Ad Campaigns for the requested creative. |
Lead Notification Content
When a new lead is created, you'll receive a notification. LinkedIn attempts to send the notification up to 5 times before giving up.
The content of the notification is as follows.
{
"createdTime": 1489428028784,
"accountUrn": "urn:li:sponsoredAccount:123456",
"campaignUrn": "urn:li:sponsoredCampaign:789012",
"creativeUrn": "urn:li:sponsoredCreative:11223344",
"formUrn": "urn:li:adForm:123456",
"adFormResponseUrn": "urn:li:adFormResponse:abc123-abab-abab-abab-abc123abc123",
}
These notifications will be sent with a header of Content-Type : text/plain; charset=UTF-8. The notification content should be parsed as JSON.
Parse the adFormResponse ID from the adFormResponseUrn URN to be used to fetch the full lead data through the Ad Form Response endpoint.
Fetch Lead Notification URL
Existing Lead Notification URLs can be requested individually through the following endpoint. It takes a compound key of the developerApplication and sponsoredEntity.
Sample Request
Sample Response
{
"createdAt": 1489012519105,
"key": {
"developerApplication": "urn:li:developerApplication:12345",
"sponsoredEntity": "urn:li:sponsoredAccount:67890"
},
"status": "PAUSED",
"url": "https://www.example.com"
}
Create Lead Notification URL
Use the following endpoint to create a new leadNotificationUrl.
Only HTTPS URLs are supported. The domain name must end in .com, .net, or .io.
The provided URL should be publicly accessible and accept POST bodies without any additional requirements such as authorization tokens.
A successful response returns a 201 Created HTTP status code.
Security
To verify that the notification is originated from LinkedIn, you can configure your service to only accept notifications that include a verification parameter that you explicitly set during creation time. For example, https://mywebservice.example.com/notificationHandler?secret=some-generated-token
All notifications are sent via HTTPS, so your payload and parameters on the URL will be encrypted with SSL.
Update Lead Notification URL
Lead Notification URLs can be updated to new URLs or change status.
Sample Request
Delete Lead Notification URL
You can remove a Lead Notification URL when you no longer want to receive notifications for an Ad Account.
Sample Request
If there is no compound key of developerApplication and sponsoredEntity, a 404 Not Found HTTP status code is returned.