Lead Gen Forms

LinkedIn Lead Gen Forms make it easy for advertisers to collect leads through forms that LinkedIn members can submit. With Lead Gen Forms, advertisers can collect leads at much higher conversion rates. See LinkedIn Lead Gen Forms and Lead Gen Ads for more information.

The following APIs are available to work with Lead Gen 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.

Lead Gen is a separate program than the Marketing Developer Platform. Access to the Marketing Developer Platform does not automatically grant access to the above APIs. Developers must apply separately to be considered for Lead Gen APIs.

Permissions

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.
  • adForms
  • adFormQuestions
r_ads Read an authenticated member's ad accounts data. Can read ad forms. Cannot retrieve leads through adFormResponses.
  • adForms
  • adFormQuestions
r_ads_leadgen_automation Access an authenticated member's ad forms and leads. Can manage and read leadNotificationUrls. This permission belongs to the Lead Gen program and is not granted automatically as part of the Marketing Developer Platform.
  • adForms
  • adFormQuestions
  • adFormResponses
  • leadNotificationUrls

If you are using legacy permissions, please refer to this page for requesting legacy permissions.

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.
landingUrl 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 gen 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.
EMAIL 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.

  1. Fetch all forms associated with an Ad Account
  2. Fetch an individual form
  3. 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

GET https://api.linkedin.com/v2/adForms?q=account&account=urn:li:sponsoredAccount:12345678&totals=true&count=1&start=0

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

GET https://api.linkedin.com/v2/adForms/12345

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

GET https://api.linkedin.com/v2/adForms?ids=6083&ids=4073

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/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

Note that you can only update form content while the form meets one of the following conditions:

  • Form is in DRAFT status.
  • Form is not linked to an Ad Creative.
  • Form is only linked to Ad Creatives that are part of DRAFT Ad Campaigns.

Form status can still be updated even if it does not meet these conditions.

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.

  1. Delete previously created test leads synced to any 3rd-party partner applications they use.
  2. Re-map the form schema with the updated form fields in the 3rd-party application.

Sample Request

POST https://api.linkedin.com/v2/adForms/656

Make sure to set the Content-Type header to application/json.

{
    "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 no longer in an editable state, you will receive a 400 Bad Request error.

Updating Form Status

Form status can be changed from SUBMITTED to PAUSED, ARCHIVED or CANCELED status even after the form itself is no longer in an editable state. 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.

Sample Request

POST https://api.linkedin.com/v2/adForms/656
{
    "patch": {
        "$set": {
            "status": "PAUSED"
        }
    }
}

Fetching Ad Form Questions

The Ad Form Questions API provides details on individual Lead Gen 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

GET https://api.linkedin.com/v2/adFormQuestions/form=urn:li:adForm:4703&questionId=1

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

GET https://api.linkedin.com/v2/adFormQuestions?ids[0].form=urn:li:adForm:123314&ids[0].questionId=1&ids[1].form=urn:li:adForm:123314&ids[1].questionId=2

Encoded Sample Request

GET https://api.linkedin.com/v2/adFormQuestions?ids%5B0%5D.form=urn%3Ali%3AadForm%3A123314&ids%5B0%5D.questionId=1&ids%5B1%5D.form=urn%3Ali%3AadForm%3A123314&ids%5B1%5D.questionId=2

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.

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}.

GET https://api.linkedin.com/v2/adFormResponses?q=account&account={sponsoredAccountUrn}

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.

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/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.

GET https://api.linkedin.com/v2/adFormResponses/{adFormResponseId}?account={adAccountUrn}

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/v2/adFormResponses/34d3a849-8aa3-432d-9325-58d0a4b53958-4?account=urn:li:sponsoredAccount:507543058&projection=(id,account,form~(form(hiddenFields)),campaign,creative,leadType,formResponse(consentResponses,submittedAt,answers*(question~(name),answerDetails)))

Sample Response

{
    "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": true,
                "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"
}

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.

GET https://api.linkedin.com/v2/adFormResponses?account={sponsoredAccountUrn}&ids={adFormResponseId1}&ids={adFormResponseId2}

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/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.

The key fields requires a developerApplication URN. This can be constructed

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.

sponsoredEntity is the account you're requesting notifications from.

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

GET https://api.linkedin.com/v2/leadNotificationUrls/sponsoredEntity=urn:li:sponsoredAccount:67890&developerApplication=urn:li:developerApplication:12345

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.

POST https://api.linkedin.com/v2/leadNotificationUrls
{
    "key": {
        "developerApplication": "urn:li:developerApplication:12345",
        "sponsoredEntity": "urn:li:sponsoredAccount:67890"
    },
    "status": "ACTIVE",
    "url": "https://www.example.com"
}

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

POST https://api.linkedin.com/v2/leadNotificationUrls/sponsoredEntity=urn:li:sponsoredAccount:67890&developerApplication=urn:li:developerApplication:12345
{
    "patch": {
        "$set": {
            "url": "https://example.com/someNewUrl"
        }
    }
}

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

DELETE https://api.linkedin.com/v2/leadNotificationUrls/sponsoredEntity=urn:li:sponsoredAccount:67890&developerApplication=urn:li:developerApplication:12345

If there is no compound key of developerApplication and sponsoredEntity, a 404 Not Found HTTP status code is returned.