Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Warning
Deprecation Notice: The Marketing Version 202503 (Marketing March 2025) has been sunset. We recommend that you migrate to the latest versioned APIs to avoid disruptions. For information on all the supported versions, refer to the migrations documentation. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
LinkedIn Lead Forms allow advertisers to collect leads through forms that LinkedIn members can submit. Refer to LinkedIn Lead Forms and Lead Sync Ads for more information.
LinkedIn also allows you to collect and sync leads through organic surfaces which would be distinguished by a leadType during lead syncing.
The following types of leads are supported for syncing:
SPONSORED- Leads collected directly from an ad.EVENT- Leads collected from an event page.COMPANY- Leads collected from a company page.ORGANIZATION_PRODUCT- Leads collected from an organization's product page.
Note
- Developers supporting ads and Non-ads leads can use the same integration with correct set of permissions for lead syncing.
- Lead forms for LinkedIn Pages and Showcase Pages are no longer available.
- You can no longer create and download lead forms for your LinkedIn Page. Existing lead forms continue to function as expected. For more information, refer.
The following APIs are designed to support Lead Forms:
leadForms- Get or find Lead Forms that appear on LinkedIn.leadFormResponses- Fetch submitted Lead Form responses.leadNotifications- Create webhook subscriptions to be notified of Lead Form responses.
Permissions
Lead Sync API is a separate program, and access to the Advertising API does not automatically grant access. You must apply separately to be considered for Lead Sync API access.
| Permission | Description | Endpoints | Program |
|---|---|---|---|
| rw_ads | Manage and read an authenticated member's ad accounts data. Can manage and read ad forms. Cannot retrieve leads through leadFormResponses. Restricted to ad accounts where the authenticated member has one of the following ad account roles:
|
leadForms | Advertising API |
| r_ads | Read ad forms. Cannot retrieve leads through leadFormResponses. Restricted to ad accounts in which the authenticated member has one of the following ad account roles:
|
leadForms | Advertising API |
| r_marketing_leadgen_automation | Access an authenticated member's ad forms/organic forms and form responses (leads). Can manage and read leadNotifications. Reading forms and form responses are restricted to the following account and/or company page roles: Sponsored use case (leads from Ads): The authenticated user must have one of the following ad account and company page roles (on the company page associated with the Ad Account in Campaign Manager): Ad Account Roles:
Company Page (Organization) roles:
Organic use case (leads not from Ads): The authenticated user must have one of the following company page roles (Note: for Event leads, one of the roles highlighted in bold are required. The other roles does not suffice):
|
|
Lead Sync API |
For more information on how to retrieve a member's ad account roles, refer to Account Access Controls
For more information on how to retrieve a member's company page/organization roles, refer to Organization Access Control.
If the authenticated member does not have the appropriate ad account or company page/organization roles, a 403 error is returned.
Lead Form Schema
For more information on lead form schema, refer to Lead Form Schema
Get Lead Forms
Lead Forms can be fetched in 3 different ways.
Find Forms by Owner
This endpoint returns all forms that belong to a specified owner. This endpoint requires q=owner and a organization or sponsoredAccount URN in the owner parameter.
Since an owner can have a large volume of Lead Forms, this API supports pagination using the count and start parameters. The API requires Restli 2.0 header and URL encoding of URNs in the URL.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| q | string | You must always set this to string owner. It indicates that you're querying based on the Owner finder, and it's the only FINDER type currently available for Lead Forms. |
Yes |
| owner | SponsoredAccountUrn/OrganizationUrn | URN identifying the owner of the Lead Form. This is the advertiser account or organization. | Yes |
| count | int | The number of results to display on each page. | No |
| start | int | The index of the form to begin your result page at. Indexes start at 0. Default is 0. | No |
Sample Request
GET https://api.linkedin.com/rest/leadForms?owner=(organization:urn%3Ali%3Aorganization%3A5509810)&q=owner&count=1&start=0
Sample Response
{
"elements": [
{
"owner": {
"organization": "urn:li:organization:5509810"
},
"hiddenFields": [
{
"name": "Entity name",
"value": "Nimbus 2000"
}
],
"versionId": 1,
"creationLocale": {
"country": "US",
"language": "en"
},
"created": 1610579725356,
"name": "LeadGen form for Nimbus 2000",
"id": 6755260984438374400,
"lastModified": 1610579725356,
"state": "PUBLISHED",
"content": {
"questions": [
{
"questionId": 10548,
"question": {
"localized": {
"en_US": "First Name"
}
},
"responseEditable": true,
"name": "firstName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "FIRST_NAME",
"responseRequired": true
},
{
"questionId": 10540,
"question": {
"localized": {
"en_US": "Last Name"
}
},
"responseEditable": true,
"name": "lastName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "LAST_NAME",
"responseRequired": true
}
],
"description": {
"localized": {
"en_US": "Share your information below with {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} to be contacted with more information about Nimbus 2000"
}
},
"headline": {
"localized": {
"en_US": "Contact {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} about Nimbus 2000"
}
},
"legalInfo": {
"consents": [
{
"checkRequired": false,
"id": 1,
"consent": {
"localized": {
"en_US": "{localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} may contact me via email"
}
}
}
],
"legalInfoId": 5604,
"privacyPolicyUrl": "https://cadfad.com/abc",
"legalDisclaimer": {
"localized": {
"en_US": "All emails include an unsubscribe link; you may opt out at any time. {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} will not sell or distribute your email address. See our Privacy Policy for more information on how we product and manage your data."
}
}
}
}
}
],
"paging": {
"start": 0,
"count": 1,
"links": []
}
}
Get A Lead Form
Individual Lead Forms can be requested using the endpoint below that only requires Lead Form ID.
Sample Request
Sample Response
{
"owner": {
"organization": "urn:li:organization:5509810"
},
"hiddenFields": [
{
"name": "Entity name",
"value": "Nimbus 2000"
}
],
"versionId": 1,
"creationLocale": {
"country": "US",
"language": "en"
},
"created": 1610579725356,
"name": "LeadGen form for Nimbus 2000",
"id": 6755260984438374400,
"lastModified": 1610579725356,
"state": "PUBLISHED",
"content": {
"questions": [
{
"questionId": 10548,
"question": {
"localized": {
"en_US": "First Name"
}
},
"responseEditable": true,
"name": "firstName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "FIRST_NAME",
"responseRequired": true
},
{
"questionId": 10540,
"question": {
"localized": {
"en_US": "Last Name"
}
},
"responseEditable": true,
"name": "lastName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "LAST_NAME",
"responseRequired": true
},
{
"questionId": 9244,
"question": {
"localized": {
"en_US": "Email Address"
}
},
"responseEditable": true,
"name": "email",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "EMAIL",
"responseRequired": true
},
{
"questionId": 9252,
"question": {
"localized": {
"en_US": "Job title"
}
},
"responseEditable": true,
"name": "jobTitle",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "JOB_TITLE",
"responseRequired": true
},
{
"questionId": 9236,
"question": {
"localized": {
"en_US": "Company name"
}
},
"responseEditable": true,
"name": "company",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "COMPANY_NAME",
"responseRequired": true
}
],
"description": {
"localized": {
"en_US": "Share your information below with {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} to be contacted with more information about Nimbus 2000"
}
},
"headline": {
"localized": {
"en_US": "Contact {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} about Nimbus 2000"
}
},
"legalInfo": {
"consents": [
{
"checkRequired": false,
"id": 1,
"consent": {
"localized": {
"en_US": "{localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} may contact me via email"
}
}
}
],
"legalInfoId": 5604,
"privacyPolicyUrl": "https://cadfad.com/abc",
"legalDisclaimer": {
"localized": {
"en_US": "All emails include an unsubscribe link; you may opt out at any time. {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} will not sell or distribute your email address. See our Privacy Policy for more information on how we product and manage your data."
}
}
}
}
}
Fetch Multiple Lead Forms
Multiple Lead Forms can be requested by chaining multiple ids parameter that each have a Lead Form ID.
Sample Request
Sample Response
{
"statuses": {
"6083": 200,
"4073": 200
},
"results": {
"6083": {
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:522147830"
},
"reviewInfo": {
"rejectionReasons": [
"CRYPTOCURRENCY",
"OFFENSIVE_LANGUAGE"
],
"lastUpdated": 1675775914000,
"reviewStatus": "REJECTED"
},
"hiddenFields": [],
"versionId": 1,
"creationLocale": {
"country": "US",
"language": "en"
},
"created": 1676620173813,
"name": "Form - Feb 17, 2023",
"id": 6083,
"lastModified": 1678689182106,
"state": "PUBLISHED",
"content": {
"questions": [
{
"questionId": 100339966,
"question": {
"localized": {
"en_US": "First name"
}
},
"responseEditable": true,
"name": "First name",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "FIRST_NAME",
"responseRequired": true
},
{
"questionId": 400339966,
"question": {
"localized": {
"en_US": "Are you interested"
}
},
"responseEditable": true,
"name": "Custom question 0",
"questionDetails": {
"multipleChoiceQuestionDetails": {
"options": [
{
"id": 0,
"text": {
"localized": {
"en_US": "Yes"
}
}
},
{
"id": 1,
"text": {
"localized": {
"en_US": "No"
}
}
}
]
}
},
"responseRequired": true
}
],
"postSubmissionInfo": {
"message": {
"localized": {
"en_US": "Thank You"
}
},
"callToAction": {
"callToActionTarget": {
"landingPageUrl": "https://cadfad.com/abc"
},
"callToActionLabel": "VISIT_COMPANY_WEBSITE"
}
},
"headline": {
"localized": {
"en_US": "Test LGF"
}
},
"legalInfo": {
"consents": [],
"legalInfoId": 100339966,
"privacyPolicyUrl": "https://cadfad.com/abc"
}
}
},
"4073": {
"owner": {
"organization": "urn:li:organization:5509810"
},
"hiddenFields": [
{
"name": "Entity name",
"value": "Nimbus 2000"
}
],
"versionId": 1,
"creationLocale": {
"country": "US",
"language": "en"
},
"created": 1610579725356,
"name": "LeadGen form for Nimbus 2000",
"id": 4073,
"lastModified": 1610579725356,
"state": "PUBLISHED",
"content": {
"questions": [
{
"questionId": 10548,
"question": {
"localized": {
"en_US": "First Name"
}
},
"responseEditable": true,
"name": "firstName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "FIRST_NAME",
"responseRequired": true
},
{
"questionId": 10540,
"question": {
"localized": {
"en_US": "Last Name"
}
},
"responseEditable": true,
"name": "lastName",
"questionDetails": {
"textQuestionDetails": {
"maxResponseLength": 300
}
},
"predefinedField": "LAST_NAME",
"responseRequired": true
}
],
"description": {
"localized": {
"en_US": "Share your information below with {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} to be contacted with more information about Nimbus 2000"
}
},
"headline": {
"localized": {
"en_US": "Contact {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} about Nimbus 2000"
}
},
"legalInfo": {
"consents": [
{
"checkRequired": false,
"id": 1,
"consent": {
"localized": {
"en_US": "{localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} may contact me via email"
}
}
}
],
"legalInfoId": 5604,
"privacyPolicyUrl": "https://cadfad.com/abc",
"legalDisclaimer": {
"localized": {
"en_US": "All emails include an unsubscribe link; you may opt out at any time. {localized={en_US=Mario Kart 8 Deluxe, es_ES=Mario Coche 8 Deluxe}, preferredLocale={country=US, language=en}} will not sell or distribute your email address. See our Privacy Policy for more information on how we product and manage your data."
}
}
}
}
}
},
"errors": {}
}
Creating Lead Forms
When setting the locale for an Ads Form, non-English forms can only be used for campaigns targeting that language. English forms can be used with any campaign, regardless of the campaign's target language.
Sample Request
POST https://api.linkedin.com/rest/leadForms
{
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:507857085"
},
"hiddenFields": [
{
"name": "Entity name",
"value": "Nimbus 2000"
}
],
"creationLocale": {
"country": "US",
"language": "en"
},
"name": "LeadGen Form Creation Testing",
"state": "DRAFT",
"content": {
"questions": [
{
"question": {
"localized": {
"en_US": "First Name"
}
},
"name": "firstName",
"questionDetails": {
"textQuestionDetails": {}
},
"predefinedField": "FIRST_NAME"
},
{
"question": {
"localized": {
"en_US": "Last Name"
}
},
"name": "lastName",
"questionDetails": {
"textQuestionDetails": {}
},
"predefinedField": "LAST_NAME"
}
],
"description": {
"localized": {
"en_US": "Share your information below with to be contacted with more information about Nimbus 2000"
}
},
"headline": {
"localized": {
"en_US": "Contact us about Nimbus 2000"
}
},
"postSubmissionInfo": {
"message": {
"localized": {
"en_US": "This is a test"
}
},
"callToAction": {
"callToActionTarget": {
"landingPageUrl": "http://www.example.com"
},
"callToActionLabel": "VISIT_COMPANY_WEBSITE"
}
},
"legalInfo": {
"consents": [
{
"checkRequired": false,
"id": 1,
"consent": {
"localized": {
"en_US": "may contact me via email"
}
}
}
],
"privacyPolicyUrl": "http://cadfad.com/abc",
"legalDisclaimer": {
"localized": {
"en_US": "All emails include an unsubscribe link; you may opt out at any time. will not sell or distribute your email address. See our Privacy Policy for more information on how we product and manage your data."
}
}
}
}
}
A successful response returns a 201 Created HTTP status code and the ID of the form in the x-restli-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 15 options.
The following example creates an multiple choice question with 2 options.
Sample Request
{
"question": {
"localized": {
"en_US": "Are you interested"
}
},
"name": "Custom question 0",
"questionDetails": {
"multipleChoiceQuestionDetails": {
"options": [{
"text": {
"localized": {
"en_US": "Yes"
}
}
},
{
"text": {
"localized": {
"en_US": "No"
}
}
}
]
}
}
}
Updating Lead Forms
Update sponsored forms while they are in two states:
- pre-published
- published
Note
Organic (i.e., non-sponsored) forms do not support edits on published forms.
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: > 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.
Published State
If an Ad Form doesn't meet the above conditions, it's in the published state. In this state, you can edit the following fields:
- headline
- description
- legalDisclaimer
- landingPageUrl
- privacyPageUrl
- thankYouMessage
- thankYouPageCta
- status
Sponsored Forms linked to Sponsored InMail and Conversation Ads can't be edited in this state.
Sample Request
POST https://api.linkedin.com/rest/leadForms/656
{
"patch": {
"$set": {
"state": "ARCHIVED"
}
}
}
A successful response returns a 204 No Content HTTP status code.
Note
If the form is not in an editable state or you attempt to edit an uneditable field, you'll receive a 400 Bad Request error.
Updating Form Status
Form status can be changed from PUBLISHED to ARCHIVED. 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.
Note
When you perform an update, the header X-RestLi-Method must be included in the request and set to PARTIAL_UPDATE.
Sample Request
POST https://api.linkedin.com/rest/leadForms/656
{
"patch": {
"$set": {
"state": "ARCHIVED"
}
}
}
Get Lead Form Responses
The Lead Form Responses API returns the response data for leads that filled out a Lead Form. Collecting Lead Form responses requires that the viewer is the owner of the Lead Form.
Lead Form Response Schema
For more information on the schema, refer to Lead Form Response Schema.
Find Lead Form Responses by Owner
Response can be retrieved for a specified owner. This endpoint takes in 2 required parameters: owner={OrganizationUrn or SponsoredAccountUrn} & leadType. This API requires Restli 2.0 header and URL encoding URNs in URL.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| q | String | You must always set this to string owner. It indicates that you're querying via the Owner finder. |
Yes |
| owner | Union of SponsoredAccountUrn, OrganizationUrn |
URN indicating the owner of the form which generated the lead. Example: OrganizationUrn or SponsoredAccountUrn. |
Yes |
| leadType | LeadType | Indicates LeadType used to filter Lead Form responses. | Yes |
| versionedLeadGenFormUrn | (optional) VersionedLeadGenFormUrn | Optional field indicating the specific form and version to retrieve the Lead Form Response. If specified, return the corresponding Lead Form responses for the versionedLeadGenFormUrn, otherwise return all results not applying this filter. |
No |
| associatedEntity | (optional) URN | Optional URN indicating the entity with which the lead is associated. Example: SponsoredCreativeUrn or OrganizationUrn. If specified, returns the corresponding Lead Form responses associated with the associatedEntity, otherwise returns all results not applying this filter. |
No |
| submittedAtTimeRange | (optional) TimeRange | Optional field indicating the lead submitted time range filter. If specified, returns the corresponding Lead Form responses for the time range, otherwise returns all results not applying this filter. Note: The submittedAtTimeRange field accepts Epoch format only. |
No |
| limitedToTestLeads | boolean(default=false) | If true, only return the test leads matching the filtering criteria. Clients could use this filter to only retrieve test leads for the purpose of testing the functionality of Lead Forms. Note: By default the value is false and returns all the leads matching the filtering criteria. | No |
Sample Request
GET https://api.linkedin.com/rest/leadFormResponses?owner=(sponsoredAccount:urn%3Ali%3AsponsoredAccount%3A522529623)&leadType=(leadType:SPONSORED)&limitedToTestLeads=false&versionedLeadGenFormUrn=urn%3Ali%3AversionedLeadGenForm%3A%28urn%3Ali%3AleadGenForm%3A3162%2C1%29&q=owner
Sample Response
{
"elements": [
{
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:522529623"
},
"submitter": "urn:li:person:MpGcnvaU_p",
"versionedLeadGenFormUrn": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:3162,1)",
"leadMetadata": {
"sponsoredLeadMetadata": {
"campaign": "urn:li:sponsoredCampaign:367378525"
}
},
"ownerInfo": {
"sponsoredAccountInfo": {
"name": "Angela Test"
}
},
"testLead": false,
"associatedEntity": {
"associatedCreative": "urn:li:sponsoredCreative:121608865"
},
"leadType": "SPONSORED",
"leadMetadataInfo": {
"sponsoredLeadMetadataInfo": {
"campaign": {
"name": "Brand awareness - May 3, 2022",
"type": "SPONSORED_UPDATES",
"id": "urn:li:sponsoredCampaign:367378525"
}
}
},
"associatedEntityInfo": {
"associatedCreative": {
"intendedStatus": "ACTIVE",
"content": {
"reference": "urn:li:ugcPost:6927151919538794496"
},
"id": "urn:li:sponsoredCreative:121608865"
}
},
"id": "aaaabbbb-0000-cccc-1111-dddd2222eeee-5",
"submittedAt": 1686182358881,
"formResponse": {
"answers": [
{
"answerDetails": {
"textQuestionAnswer": {
"answer": "Hello World-testing purpose"
}
},
"questionId": 1
},
{
"answerDetails": {
"multipleChoiceAnswer": {
"options": [
1,
3
]
}
},
"questionId": 2
}
],
"consentResponses": [
{
"accepted": true,
"consentId": 4
}
]
}
}
],
"paging": {
"count": 10,
"start": 0,
"total": 1,
"links": []
}
}
Get a single Lead Form Response
Use the lead id to fetch the corresponding response by making a GET call to the API.
Sample Request
GET https://api.linkedin.com/rest/leadFormResponses/aaaabbbb-0000-cccc-1111-dddd2222eeee-5
Sample Response
{
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:522529623"
},
"submitter": "urn:li:person:MpGcnvaU_p",
"versionedLeadGenFormUrn": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:3162,1)",
"leadMetadata": {
"sponsoredLeadMetadata": {
"campaign": "urn:li:sponsoredCampaign:367378525"
}
},
"ownerInfo": {
"sponsoredAccountInfo": {
"name": "Angela Test"
}
},
"testLead": false,
"associatedEntity": {
"associatedCreative": "urn:li:sponsoredCreative:121608865"
},
"leadType": "SPONSORED",
"leadMetadataInfo": {
"sponsoredLeadMetadataInfo": {
"campaign": {
"name": "Brand awareness - May 3, 2022",
"type": "SPONSORED_UPDATES",
"id": "urn:li:sponsoredCampaign:367378525"
}
}
},
"associatedEntityInfo": {
"associatedCreative": {
"intendedStatus": "ACTIVE",
"content": {
"reference": "urn:li:ugcPost:6927151919538794496"
},
"id": "urn:li:sponsoredCreative:121608865"
}
},
"id": "aaaabbbb-0000-cccc-1111-dddd2222eeee-5",
"submittedAt": 1686182358881,
"formResponse": {
"answers": [{
"answerDetails": {
"textQuestionAnswer": {
"answer": "Hello World-testing purpose"
}
},
"questionId": 1
},
{
"answerDetails": {
"multipleChoiceAnswer": {
"options": [
1,
3
]
}
},
"questionId": 2
}
],
"consentResponses": [{
"accepted": true,
"consentId": 4
}]
}
}
Get Multiple Lead Form responses
If you already know the IDs of multiple Lead Forms you wish to fetch response, you can fetch the response by using ids parameter. This API requires Restli 2.0 header and URL encoding URNs in URL.
The maximum number of permitted ids is 1000.
Sample Request
GET https://api.linkedin.com/rest/leadFormResponses?ids=List("aaaabbbb-0000-cccc-1111-dddd2222eeee-5")&owner=(sponsoredAccount:urn%3Ali%3AsponsoredAccount%3A522529623)&leadType=(leadType:SPONSORED)
Sample Response
{
"results": {
"aaaabbbb-0000-cccc-1111-dddd2222eeee-5": {
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:522529623"
},
"submitter": "urn:li:person:MpGcnvaU_p",
"versionedLeadGenFormUrn": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:3162,1)",
"leadMetadata": {
"sponsoredLeadMetadata": {
"campaign": "urn:li:sponsoredCampaign:367378525"
}
},
"ownerInfo": {
"sponsoredAccountInfo": {
"name": "Angela Test"
}
},
"testLead": false,
"associatedEntity": {
"associatedCreative": "urn:li:sponsoredCreative:121608865"
},
"leadType": "SPONSORED",
"leadMetadataInfo": {
"sponsoredLeadMetadataInfo": {
"campaign": {
"name": "Brand awareness - May 3, 2022",
"type": "SPONSORED_UPDATES",
"id": "urn:li:sponsoredCampaign:367378525"
}
}
},
"associatedEntityInfo": {
"associatedCreative": {
"intendedStatus": "ACTIVE",
"content": {
"reference": "urn:li:ugcPost:6927151919538794496"
},
"id": "urn:li:sponsoredCreative:121608865"
}
},
"id": "aaaabbbb-0000-cccc-1111-dddd2222eeee-5",
"submittedAt": 1686182358881,
"formResponse": {
"answers": [{
"answerDetails": {
"textQuestionAnswer": {
"answer": "Hello World-testing purpose"
}
},
"questionId": 1
},
{
"answerDetails": {
"multipleChoiceAnswer": {
"options": [
1,
3
]
}
},
"questionId": 2
}
],
"consentResponses": [{
"accepted": true,
"consentId": 4
}]
}
},
"statuses": {},
"errors": {}
}
}
Test Leads
Test leads can be generated from the Campaign Manager UI. These leads can then be downloaded via the Lead Form Response API or UI. The testLead field on a response is equal to true for test leads.
Note
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 are still downloadable, but the associated campaign is no longer retrievable which may cause problems in some integrations.
For more information on generating test leads, refer to Sending a Test Lead in Campaign Manager.
Lead Notification Subscriptions
Register and validate your webhook URL endpoints to receive push notifications of new leads.
Note
Only HTTPS URLs are supported. Starting March 16, 2026, new lead notifications will only be pushed to webhooks that have been validated.
Schema
For more information on the schema, refer to Lead Subscriptions Schema
Fetch Lead Notification Subscriptions
Existing Lead notification URLs can be requested individually through the following endpoint.
Sample Request
GET https://api.linkedin.com/rest/leadNotifications?q=criteria&owner=(value:(sponsoredAccount:urn%3Ali%3AsponsoredAccount%3A511849581))&leadType=(leadType:SPONSORED)
Sample Response
{
"results": {
"owner": {
"organization": "urn:li:organization:5622087"
},
"id": 7012,
"leadType": "SPONSORED",
"versionedForm": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:6851219773716516864,1)",
"associatedEntity": {
"event": "urn:li:event:123"
}
}
}
Fetch a single Lead Notification Subscription
Sample Request
Sample Response
{
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:520866471"
},
"webhook": "https://eogi5ry4pv6izmq.m.pipedream.net",
"id": 107708,
"leadType": "SPONSORED"
}
Create a Lead Notification Subscription - Owner Level
Use the following endpoint to create a new leadNotificationSubcription against an owner entity.
Note
- Only HTTPS URLs are supported.
- The provided URL should be publicly accessible and accept POST bodies without any additional requirements such as authorization tokens.
POST https://api.linkedin.com/rest/leadNotifications --data '{"webhook": "https://eogi5ry4pv6izmq.m.pipedream.net","owner": {"sponsoredAccount": "urn:li:sponsoredAccount:520866471"}, "leadType": "SPONSORED"}'
A successful response returns a 201 Created HTTP status code.
Create a Lead Notification Subscription - Associated Entity Level
Use the following endpoint to create a new leadNotificationSubscription against an associated entity.
Note
- Only HTTPS URLs are supported.
- The provided URL should be publicly accessible and accept POST bodies without any additional requirements such as authorization tokens.
Sample Request
POST https://api.linkedin.com/rest/leadNotifications” --data ‘{“webhook”: “https://linkedin.com”,"owner": {"organization": "urn:li:organization:1"},"associatedEntity":{"event":"urn:li:event:123"}, "leadType": "SPONSORED"}’
A successful response returns a 201 Created HTTP status code.
Create a Lead Gen Notification Subscription - Form Level
Use the following endpoint to create a new leadNotificationSubscription against a Lead Gen Form.
Note
- Only HTTPS URLs are supported.
- The provided URL should be publicly accessible and accept POST bodies without any additional requirements such as authorization tokens.
POST https://api.linkedin.com/rest/leadNotifications” --data ‘{“webhook”: “https://linkedin.com”,"owner": {"organization": "urn:li:organization:1"},"versionedForm": "urn:li:versionedLeadGenForm:(urn:li:leadGenForm:818,1)", "leadType": "SPONSORED"}’
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 the creation. Example: https://mywebservice.example.com/notificationHandler?secret=some-generated-token
Note
All notifications are sent via HTTPS, so your payload and parameters on the URL are encrypted with SSL.
Delete Lead notification URL
Remove a Lead notification URL when you no longer want to receive notifications.
Sample Request
Frequently Asked Questions
Q: What happens if I have multiple subscriptions under an owner?
A: We honor all subscriptions and send push notifications for each valid subscription matching the context in which a lead was submitted/deleted.
Q: Why is my webhook invalid or why was it invalidated?
A: In most cases a webhook fails validation because it doesn't correctly return the HMAC-SHA256 encoding of the sent challenge code using the correct client secret. Please refer to the webhook documentation to ensure all steps are completed properly. Also, note that validation is ongoing and the webhook is challenged in a regular interval (~2 hours) so ensure no limitations are in place to prevent our service from calling the webhook.
Q: Which subscription flow should I implement?
A: While each option is serviceable, unless there is an explicit need to have unique webhook URLs on a per form or associated entity basis, we recommend creating subscriptions at the owner level. This simplifies subscription management in that only a single subscription needs to exist per owner.
Q: What happens if I create a subscription with both a form and an associated entity?
A: For a single subscription containing both a form and an associated entity, a notification is sent only when a lead is submitted that matches both the provided form and associated entity values.
Q: What content can I expect to be included in the notification payloads?
A: Please refer to the schema as follows:
| Field | Description |
|---|---|
| type | Always set to LEAD_ACTION. |
| leadGenFormResponse | URN of the lead. |
| owner | Owner of the lead. For the SPONSORED lead type the owner is a sponsored account URN. For all other lead types the owner is an organization URN. |
| associatedEntity | URN identifying which entity the lead is associated with. |
| leadGenForm | URN of the Lead Gen Form. |
| leadType | Type of the lead. Set to SPONSORED for sponsored leads. |
| leadAction | Action performed on the lead. It is either CREATED or DELETED. |
| occurredAt | Unix timestamp for when the action occurred. |
Example payload for when a member registers for an event
{
type: “LEAD_ACTION”,
leadGenFormResponse: “urn:li:leadGenFormResponse:1a2b3c-4”,
leadGenForm: “urn:li:versionedLeadGenForm:(urn:li:leadGenForm:1, 1)”,
owner: {“organization”: “urn:li:organization:123”},
associatedEntity: {“event”: “urn:li:event:123”},
leadType: "EVENT",
leadAction: “CREATED”,
occurredAt: 123456789
}
Example payload for when a member unregisters from an event
{
type: “LEAD_ACTION”,
leadGenFormResponse: “urn:li:leadGenFormResponse:1a2b3c-4”,
leadGenForm: “urn:li:versionedLeadGenForm:(urn:li:leadGenForm:1, 1)”,
owner: {“organization”: “urn:li:organization:123”},
associatedEntity: {“event”: “urn:li:event:123”},
leadType: "EVENT"
leadAction: “DELETED”
occurredAt: 1233589
}
API Error Details
The following are the possible error codes and their resolutions:
| HTTP STATUS CODE | ERROR MESSAGE | ERROR DESCRIPTION | RESOLUTION |
|---|---|---|---|
| 401 | Member is not authorized to create LeadGenForm | Member doesn't have enough permissions under the sponsoredAccount to create a Lead Form |
Check whether the right Permissions are present to manage forms. |
| 401 | Member is not authorized to BatchGet LeadGenForms | Member doesn't have enough permissions under the sponsoredAccount/Organization to get a Lead Form |
Check whether the right Permissions are present to manage forms. |
| 401 | Member is not authorized to fetch LeadGenForms under a SponsoredAccount/Organization |
Member doesn't have enough permissions under the sponsoredAccount/organization to fetch Lead Forms using criteria finder. |
Check whether the right Permissions are present to manage forms. |
| 401 | The member doesn't have lead access permission. | Member doesn't have enough permissions to access the collected leads. | Check whether the right Permissions are present to fetch leads. |
| 400 | Failed to generate Lead Form identifier. | Create request for Lead Form is not correct. | Please make sure the request payload is as per the schema. |
| 400 | Please specify a concrete LeadType and Owner for your request. | Batch get request is missing leadType or owner param in the request. | Make sure both the params are present when making the batch get request. |
| 400 | Malformed subscription creation request that doesn't meet validation checks. Owner of Lead Form doesn't match that of the subscription. | The subscription being accessed is not under the same sponsoredAccount/Organization as the Lead Form. | Make sure owners for both Lead Form and the subscription are same. |
| 403 | Unauthorized! the member doesn't have permission to take this action on a subscription for the owner. | Not enough permissions to take actions on the lead notification subscription. | Check whether the right Permissions are present to manage lead notification subscriptions. |
| 409 | The Lead Form has duplicate {field}. | The Form being created has duplicate fields which is not allowed. | Fix the fields in the error message to have unique values. |