Training
Module
Manage forms and pages in Dynamics 365 Customer Insights - Journeys - Training
Learn how to manage forms and marketing pages in Dynamics 365 Customer Insights - Journeys. This module applies to outbound marketing features only.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Warning
Deprecation Notice
The Marketing Version 202311 (Marketing November 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
LinkedIn Lead Forms make it easy for advertisers to collect leads through forms that LinkedIn members can submit. With Lead Forms, marketers can collect leads at much higher conversion rates. See LinkedIn Lead Forms and Lead Sync Ads for more information.
Besides lead syncing with Ads, LinkedIn also provides the ability 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:
Description | leadType |
---|---|
Sponsored - Leads collected directly from an ad. | SPONSORED |
Event - Leads collected from an event page. | EVENT |
Company - Leads collected from a company page. | COMPANY |
Product - Leads collected from an organization's product page. | ORGANIZATION_PRODUCT |
Note
This page documents the APIs required to build a Lead Sync integration. Developers supporting ads and Non-ads leads will be be able to use the same integration with correct set of permissions for lead syncing.
The following APIs are designed to support Lead Forms:
leadForms
- Get or find Lead Forms that will appear on LinkedIn.leadFormResponses
- Fetch Lead Form responses.leadNotifications
- Create webhook subscriptions to be notified of Lead Form responses.Lead Sync API is a separate program and access to the Advertising API does not automatically grant you the access. You must apply separately to be considered for Lead Sync APIs.
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 in which the authenticated member has one of the following ad account roles:
|
|
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:
|
|
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 will not suffice):
|
|
Lead Sync API |
If the authenticated member does not have the appropriate ad account or company page/organization roles, we will return a 403 error.
See Account Access Controls for information on how to retrieve a member's ad account roles.
See Organization Access Control for information on how to retrieve a member's company page/organization roles.
Lead Forms are used to request data from members responding to the Lead Form. Lead Forms can include multiple questions, hidden fields, and custom consent checkboxes. Many of these components are structured as sub-objects of the Lead Form. In the next section, schemas of the parent and sub-objects are defined.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
id | Long | Numerical identifier for the form. | Yes | No | Yes |
created | Time | An epoch time corresponding to the creation of the form. | Yes | No | Yes |
lastModified | Time | An epoch time corresponding to the last modified of of the form. | Yes | No | Yes |
creationLocale | Locale | Locale of the entity. This field serves as the preferred locale for all fields within the Lead Form with an object type that is capable of localization, such as MultiLocaleString. | No | Yes | Yes |
owner | LeadGeNowner | URN that identifies the owner of the Lead Form. It's a Union of sponsoredAccount and organization . sponsoredAccount is an URN of SponsoredAccountUrn that idicates the account of the advertiser. organization is an URN of OrganizationUrn that idicates the company account of the marketer. |
No | Yes | Yes |
name | string | Name of the Lead Form provided by the owner. | No | Yes | Yes |
content | DisplayContent | Content of the Lead Form which will be displayed to the viewer. | No | Yes | Yes |
hiddenFields | HiddenField[] | Hidden fields used by the owner to track key attributes of the form that generated the lead. The field is empty if the owner chooses to not append any tracking attributes to the Lead Form. | No | Yes | Yes |
state | LeadGenLifecycleState | Information about the current state of the Lead Form. | Yes | No | Yes |
reviewInfo | LeadGenReviewInfo | Latest information about the content review of the Lead Form. It will not be present if the form has not been reviewed by the review pipeline. | Yes | No | Yes |
versionId | int | The version ID of the form. This is a derived field and is generated on the server side. | Yes | No | Yes |
versionTag | String | The number of times the form has been modified. | Yes | No | No |
Locale
is a data type in the Lead Form which indicate the locale of the form.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
language | string | An uppercase two-letter country code as defined by ISO-3166 | No | Yes | Yes |
country | string | A lowercase two-letter language code as defined by ISO-639-1 | No | Yes | Yes |
variant | string | Vendor or browser-specific code. | No | No | Yes |
DisplayContent
is a sub-object in the Lead Form which represents the form content to be shown to the viewers for collecting responses.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
headline | MultiLocaleString | Headline of the form. | No | Yes | Yes |
description | MultiLocaleString | Description of the form. Optional since the owner may choose to not have this information. | No | No | Yes |
questions | LeadGenFormQuestion[] | Questions to request information from the viewer. At least one question should be present. | No | Yes | Yes |
legalInfo | LeadGenFormLegalInfo | Legal information displayed alongside the Lead Form. | No | Yes | Yes |
postSubmissionInfo | PostSubmissionInfo | Information displayed to the user after submitting the form (e.g. thank you message, etc.). Optional since not all use cases require a post submission experience. | No | No | Yes |
MultiLocaleString
is a data type in the Lead Form which represents a textual field with values for multiple locales. Most readers should use the localized
field entry keyed by preferredLocale
. In the Lead Form, we use the creationLocale as the preferred locale.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
localized | map | Maps a locale to a localized version of the string. Each key is a Locale record converted to string format, with the language, country and variant separated by underscores. Examples: 'en', 'de_DE', 'en_US_WIN', 'de__POSIX', 'fr__MAC'." | No | Yes | Yes |
LeadGenFormQuestion
is a sub-object in the DisplayContent
which one Lead Form question.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
questionId | long | Unique identifier of the LeadGenFormQuestion. | Yes | No | Yes |
name | string | Name of the question, shown to the owner only. | No | Yes | Yes |
question | MultiLocaleString | The question prompt, shown to the viewer. | No | Yes | Yes |
textPrompt | MultiLocaleString | The description or hint of the question, shown to the viewer. Empty in case No hint is provided. | No | No | Yes |
predefinedField | PredefinedField | The predefined field that the question is requesting. This field is used for specifying viewer specific fields(e.g. First name, City, School, etc.) that should be used to prefill the question response. Customized questions do not request a predefined field and will leave this field empty. | No | No | Yes |
responseEditable | boolean | True if the member viewing the form can edit a pre-filled form response. Default is true. | No | No | Yes |
responseRequired | boolean | True if the response is required for the question. Default is true. | No | No | Yes |
questionDetails | Union of TextQuestionDetails, MultipleChoiceQuestionDetails | The specific details of the question including default answer, answer restrictions etc. We allow text and selection questions. | No | Yes | Yes |
questionSubmissionCriteria | optional Union of WorkEmailSubmissionCriteria | The criteria for submission of response for the question. For example: allow only Non-freemium emails for the work email form question. A question submission criteria is exclusive to the predefined field tied to the question. | No | No | Yes |
label | string | The label of the question specified by marketers. These labels for the questions are unique within the context of a single form. | No | No | Yes |
PredefinedField
is a sub-object in the LeadGenFormQuestion
that can be used as a question in a Lead Form. Responses to some of these fields can be prefilled using the viewer's profile.
Symbol | Description |
---|---|
FIRST_NAME | The first name of the viewer. |
LAST_NAME | The last name of the viewer. |
PHONE_NUMBER | The phone number of the viewer. |
The email of the viewer. | |
CITY | The city of the viewer. |
STATE | The state of the viewer. |
COUNTRY | The country of the viewer. |
ZIP_CODE | The postal code or zip code of the viewer. |
JOB_TITLE | The latest job title of the viewer. |
JOB_FUNCTION | The job function of the viewer's latest job (e.g. Sales, Engineering, etc.). |
SENIORITY | The seniority of the viewer's job title (e.g. manager, director, VP, etc.). |
COMPANY_NAME | The name of the company of the viewer's latest job. |
COMPANY_SIZE | The size of the company of the viewer's latest job. |
INDUSTRY | Industry of the viewer. |
DEGREE | The degree attained from the latest school attended by the viewer. |
FIELD_OF_STUDY | The field of study for the viewer's latest school attended. |
SCHOOL | The name of the school the viewer last attended. |
START_DATE | The start date of the viewer at the latest school attended. |
GRADUATION_DATE | The graduation date of the viewer at the latest school attended. |
GENDER | The gender of the viewer. |
WORK_EMAIL | The work email address of the viewer. |
LINKEDIN_PROFILE_LINK | The LinkedIn public profile URL of the viewer. |
WORK_PHONE_NUMBER | The work phone number of the viewer |
TextQuestionDetails
is a sub-object in the LeadGenFormQuestion
representing text question specific details.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
defaultResponse | string | Either the default response to a question as specified by the owner, or the prefilled viewer information for a predefined field. Can be empty in case the owner choose not to specify, or if the response couldn't be prefilled. | No | No | Yes |
maxResponseLength | int | The maximum length of the response, in characters. Default is 300. | No | No | Yes |
MultipleChoiceQuestionDetails
is a sub-object in the LeadGenFormQuestion
representing the details of a multiple choice question.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
options | MultipleChoiceQuestioNoption | The options for a multiple choice question. | No | Yes | Yes |
defaultSelectedOption | int | Id of the option which is selected by default when shown to the viewer. If empty then No option is shown as selected. | No | No | Yes |
MultipleChoiceQuestioNoption
is a sub-object in the MultipleChoiceQuestionDetails
, structured as an element in the array named options
. MultipleChoiceQuestioNoption
representing an option of a multiple choice question specified by the owner.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
id | int | The identifier for a MultipleChoiceQuestioNoption within the context of a MultipleChoiceQuestion. This will be unique only under the scope of a MultipleChoiceQuestion. | No | Yes | Yes |
text | MultiLocaleString | Text describing an option for a multiple choice question specified by the owner. | No | Yes | Yes |
label | string | The label of the multiple choice option specified by marketers. These labels for the multiple choice options are unique within the context of a single form. | No | No | Yes |
WorkEmailSubmissionCriteria
is a sub-object in the LeadGenFormQuestion
representing the criteria for submission of responses to WORK_EMAIL PredefinedField.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
freemiumEmailAllowed | boolean | If true, then a personal or freemium domain email address will be allowed to be submitted as the response of the WORK EMAIL PredefinedField. | No | Yes | Yes |
LeadGenFormLegalInfo
is a sub-object in the Lead Form representing Lead Form legal information to display to viewers.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
legalInfoId | long | Unique identifier of the LeadGenFormLegalInfo. | Yes | No | Yes |
privacyPolicyUrl | Url | The URL of the privacy policy that covers any data passed to the owner of the form. Optional since it is not required to be present for all the use cases. | No | No | Yes |
legalDisclaimer | MultiLocaleString | Owner's legal disclaimer to accompany this form. Optional since the owner may alternatively use other fields (e.g. legalDisclaimer, consents) to surface the privacy policy. | No | No | Yes |
consents | LeadGenFormConsent[] | Additional consents used to obtain member approval for using data collected via the Lead Form. This field is empty if No viewer consents are required by the owner. | No | Yes | Yes |
LeadGenFormConsent
is a sub-object in the LeadGenFormLegalInfo
, structured as an element in the array named consents
. LeadGenFormConsent
representing the Lead Form consent as defined by the owner of the form. Used for obtaining member approval to collecting data.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
id | int | The id of the consent, unique within LeadgenFormLegalInfo object. | No | Yes | Yes |
consent | MultiLocaleString | The custom text that appears next to the checkbox, informing the member of what use of data they are consenting to. | No | Yes | Yes |
checkRequired | boolean | Whether the consent is required to be checked by the member when submitting the form. Default is false. | No | Yes | Yes |
label | string | The label of the consent specified by marketers. These labels for the consents are unique within the context of a single form. | No | No | Yes |
PostSubmissionInfo
is a sub-object in the Lead Form representing the content for displaying to viewers after they submit the response.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
message | MultiLocaleString | The message displayed to a member after the Lead Form is submitted. | No | Yes | Yes |
callToAction | LeadGenFormCallToAction | Call to action shown after the Lead Form submission. | No | Yes | Yes |
LeadGenFormCallToAction
is a sub-object in the PostSubmissionInfo
representing a call to action in the form of a button or label a member can act on that opens a landing page.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
callToActionLabel | PostSubmissionCallToActionLabel | Label for the call to action shown to the viewer. Default is VISIT_COMPANY_WEBSITE | No | Yes | Yes |
callToActionTarget | optional Union of LandingPageUrl | Target where the user is taken after clicking on the CTA. E.g. a LandingPageUrl which is a url redirect to a web page. It can be empty for CTA's which don't require additional information. | No | No | Yes |
PostSubmissionCallToActionLabel
is a sub-object in the LeadGenFormCallToAction
that predefined values of call to action to be displayed after form submission.
Symbol | Description |
---|---|
VISIT_COMPANY_WEBSITE | Visit Company Website call to action. |
LEARN_MORE | Learn More call to action. |
VIEW_NOW | View Now call to action. |
DOWNLOAD_NoW | Download Now call to action. |
TRY_NOW | Try Now call to action. |
HiddenField
is a sub-object in the Lead Form, structured as an element in the array named hiddenFields
. HiddenField
is not displayed on the form, but can be used by marketers for tracking purposes.
The array can contain a maximum of 20 HiddenField.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
name | string | The name of the hidden field. | No | Yes | Yes |
value | string | The content of the hidden field. | No | Yes | Yes |
LeadGenLifecycleState
is a sub-object in the Lead Form that indicate the lifecycle stage of a Lead Form.
Symbol | Description |
---|---|
DRAFT | The form is still being edited. |
PUBLISHED | The form is published, i.e. it has gone through processing (e.g. manual review) and is ready to be used. |
ARCHIVED | The form is archived. |
LeadGenReviewInfo
is a sub-object in the Lead Form that indicate the review info of the form.
Field | Type | Description | Read Only | Required in Write | Returned by Default |
---|---|---|---|---|---|
reviewStatus | LeadGenFormReviewStatus | Indicate the state of review for the Lead Form. | Yes | No | Yes |
lastUpdated | Time | The epoch time in millisecond indicating when the review status is initiated/last updated. | Yes | No | Yes |
rejectionReasons | RejectionReason | An array of rejection reasons for the Lead Form. It's Non-empty if the review status is REJECTED in the latest review. | Yes | No | Yes |
LeadGenFormReviewStatus
is a sub-object in the LeadGenReviewInfo
that indicate whether the entity has been reviewed and the result of the review.
Symbol | Description |
---|---|
PENDING | The form is pending review and not serving. |
APPROVED | The form is approved for serving. |
REJECTED | The form is rejected. |
PREAPPROVED | The form has been pre-approved, it's ready for serving but still need further review. |
AUTO_APPROVED | The form has been auto approved by content model. |
NEEDS_REVIEW | The form has been rejected by content model or policy checker or returned by fallback case that auto approval didn't make any decision. |
AUTO_REJECTED | The form has been auto rejected by content model. |
Lead Forms can be fetched in 3 different ways.
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. The API requires Restli 2.0 header and URL encoding of URNs in the URL.
Since an owner can have a large volume of Lead Forms, this API supports pagination using the count
and start
parameters.
Parameter | Type | Description | Required |
---|---|---|---|
q | string | You must always set this to string owner . It indicates that you are 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 | Number | The number of results to display on each page. | No |
start | Number | The index of the form to begin your result page at. Indexes start at 0. Default is 0. | No |
GET https://api.linkedin.com/rest/leadForms?owner=(organization:urn%3Ali%3Aorganization%3A5509810)&q=owner&count=1&start=0
{
"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": []
}
}
Individual Lead Forms can be requested using the endpoint below that only requires Lead Form ID.
{
"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."
}
}
}
}
}
Multiple Lead Forms can be requested by chaining multiple ids
parameter that each have a Lead Form ID.
{
"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": {}
}
Currently, only ad forms can be created (creation of non sponsored forms is not supported yet). When setting the locale for an Ads Form, note that non-English forms can only be used for campaigns targeting that language, but English forms can be used with any campaign.
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-linkedin-id
response header.
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": {}
}
}
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.
{
"question": {
"localized": {
"en_US": "Are you interested"
}
},
"name": "Custom question 0",
"questionDetails": {
"multipleChoiceQuestionDetails": {
"options": [{
"text": {
"localized": {
"en_US": "Yes"
}
}
},
{
"text": {
"localized": {
"en_US": "No"
}
}
}
]
}
}
}
You can update sponsored forms while they are in two states: pre-published and published.
Note
Non sponsored forms don't support edits.
An Ad Form is in a pre-published state when one of the following conditions is met:
DRAFT
status.DRAFT
Ad 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:
If an Ad Form does not meet the above conditions, it is in the published state. In this state, you can edit the following fields:
Sponsored Forms linked to Sponsored InMail and Conversation Ads cannot be edited in this state.
Make sure to set the Content-Type header to application/json.
POST https://api.linkedin.com/rest/leadForms/656
{
"patch": {
"$set": {
"state": "ARCHIVED"
}
}
}
A successful response returns a 204 No Content
HTTP status code.
If the form is not in an editable state or you attempt to edit an uneditable field, you will receive a 400 Bad Request error.
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
.
POST https://api.linkedin.com/rest/leadForms/656
{
"patch": {
"$set": {
"state": "ARCHIVED"
}
}
}
The Lead Form Responses API returns the response data for leads that filled out a Lead Form. Collecting Lead Form responses requires the viewer is the owner of the Lead Form.
Field | Type | Description | Returned by Default |
---|---|---|---|
id | string | Unique id to identify the Lead Form Response. | Yes |
leadType | LeadType | Type of the lead representing the origination of the lead. | Yes |
form | VersionedLeadGenFormUrn | URN identifying which form this FormResponse belongs to. | No |
owner | LeadGenFormResponseOwner | Owner of this Lead Form Response. It is a Union of sponsoredAccount and organization . sponsoredAccount is an URN of SponsoredAccountUrn that indicates the ad account of the advertiser. organization is an URN of OrganizationUrn that indicates the company page of the advertiser. |
Yes |
ownerInfo | LeadGenFormResponseOwnerInfo | Record containing entity info that owns this Lead Form Response. It's a optional Union of sponsoredAccountInfo and organizationInfo . |
No |
leadMetadata | Union of SponsoredLeadMetadata | Metadata of a lead. This field is optional for test leads and other use cases where sponsored lead metadata (e.g. campaign) may not be relevant. If there is no value, the field is not returned. | Yes |
leadMetadataInfo | optional Union of SponsoredLeadMetadataInfo | Record containing a subset of fields resolved on demand from the lead metadata references (e.g. campaign name , campaign type). If there is no value, an empty object is returned. | No |
associatedEntity | Union of SponsoredCreativeUrn , OrganizationUrn , EventUrn , StandardizedProductUrn, OrganizationLandingPageUrn | URN identifying which entity the lead is associated with. This field is optional for test leads and other use cases where leads don't have any associatedEntity. If there is no value, the field is not returned. | Yes |
associatedEntityInfo | optional Union of SponsoredCreativeInfo, OrganizationInfo, EventInfo, StandardizedProductInfo, OrganizationLandingPageInfo | Record containing useful fields (creative status, ugc reference etc.) resolved on demand from the associated entity object. If there is no value, an empty object is returned. | No |
submittedAt | Time | An epoch timestamp that recording when the form response was submitted. | Yes |
responseId | TrackingId | The unique identifier for the form response generated in the front-end when a submitter submits the response. | Yes |
formResponse | FormResponse | Answers provided by the form submitter. | Yes |
testLead | Boolean | Whether this is a test lead created for testing purposes. | Yes |
LeadType
is a sub-object in the Lead Form Response that indicates the type of the response.
Symbol | Description |
---|---|
SPONSORED | The lead is collected from sponsored content. |
COMPANY | The lead is collected from the company page. |
EVENT | The lead is collected from the event page. |
ORGANIZATION_PRODUCT | The lead is collected from an organization product page. |
FormResponse
is a sub-object in the Lead Form Response representing the form response from submitter, which contains a set of answers and consentResponses.
Field | Type | Description | Returned by Default |
---|---|---|---|
answers | Answer[] | Answers provided by the submitter. | Yes |
consentResponses | ConsentResponse[] | Responses to the consents that are provided by the submitter. | Yes |
Answer
is a sub-object in FormResponse
, structured as an element in the array named answers
. It represents the submitter's response to the questions in the Lead Form.
Field | Type | Description | Returned by Default |
---|---|---|---|
questionId | long | The id of the question. | Yes |
name | string | Name of the question. | Yes |
accepted | Union of TextQuestionAnswer, MultipleChoiceAnswer | Answer provided by a submitter. | Yes |
TextQuestionAnswer
is a sub-object in the Answer
representing the response to a TextQuestion of form in text format.
Field | Type | Description | Returned by Default |
---|---|---|---|
answer | string | The answer to a single text-entry question. | Yes |
MultipleChoiceAnswer
is a sub-object in the Answer
representing a form response to a particular Lead Form, which contains a set of answers provided by the submitter.
Field | Type | Description | Returned by Default |
---|---|---|---|
options | int[] | The array of the chosen option ids for a MultipleChoiceQuestion by the submitter. Default as empty array if No choice answered by submitter. | Yes |
ConsentResponse
is a sub-object in FormResponse
, structured as an element in the array named consentResponses
. It represents the submitter's response to the consents in the legal info in the Lead Form.
Field | Type | Description | Returned by Default |
---|---|---|---|
consentId | int | The id of the consent, unique within LeadgenFormLegalInfo object. | Yes |
consent | string | The custom text that appears next to the checkbox, informing the member of what use of data they are consenting to. | Yes |
accepted | boolean | Consent answer provided by a submitter. True if the submitter chooses to opt-in. | Yes |
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.
Parameter | Type | Description | Required |
---|---|---|---|
q | String | You must always set this to string owner . It indicates that you're querying based via the Owner finder. |
Yes |
owner | LeadGenFormOwner | Urn indicating the owner of the form which generated the lead, e.g. 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 | Urn | Optional urn indicating which entity the lead is associated with, e.g. SponsoredCreativeUrn or OrganizationUrn. If specified, return the corresponding Lead Form responses associated with the associatedEntity, otherwise return all results not applying this filter. | No |
submittedAtTimeRange | TimeRange | Optional field indicating the lead submitted time range filter. If specified, return the corresponding Lead Form responses for the time range, otherwise return all results not applying this filter. | 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. By default the value is false and will return all the leads matching the filtering criteria. | No |
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
{
"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": "691c02e7-f7f0-430a-ae16-4fc7d76f61a6-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": []
}
}
You can use the lead id to fetch the corresponding response by making a GET call to the API.
GET https://api.linkedin.com/rest/leadFormResponses/691c02e7-f7f0-430a-ae16-4fc7d76f61a6-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": "691c02e7-f7f0-430a-ae16-4fc7d76f61a6-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
}]
}
}
If you already know the IDs of multiple Lead Forms you wish to fetch response, you can fetch the response by using ids
parameter. The API requires Restli 2.0 header.
The maximum number of permitted ids
is 1000.
GET https://api.linkedin.com/rest/leadFormResponses?ids=List("691c02e7-f7f0-430a-ae16-4fc7d76f61a6-5")&owner=(sponsoredAccount:urn%3Ali%3AsponsoredAccount%3A522529623)&leadType=(leadType:SPONSORED)
{
"results": {
"691c02e7-f7f0-430a-ae16-4fc7d76f61a6-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": "691c02e7-f7f0-430a-ae16-4fc7d76f61a6-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 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 will be 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 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.
You can register URLs to receive webhook notifications of new leads. Only HTTPS URLs are supported.
Field | Type | Description | Read Only | Required in Write |
---|---|---|---|---|
id | Long | Unique identifier of the subscription. | Yes | No |
webhook | URL | URL designating where the notification payloads are delivered. | No | Yes |
owner | Union of SponsoredAccountUrn,OrganizationUrn | URN identifying the owner of a Lead Form. Indicates that all forms under the owner are subject to triggering notifications. This can be the advertiser account or organization. | No | Yes |
leadType | Enum | Lead type for which the subscription is created. LeadType can be sponsored or organic. | No | Yes |
versionedFormUrn | VersionedLeadGenFormUrn | URN identifying the versioned Lead Form for which the subscription is created, e.g. urn:li:versionedLeadGenForm:(urn:li:leadGenForm:123,1). This is an optional field and will only be present if the subscription is made for a Lead Form, i.e. only actions such as lead submissions made on this particular form should trigger notifications. If a separate subscription containing only an owner exists, the same trigger will send payloads to both subscriptions if the webhooks are different. Otherwise, this will be null. | No | No |
associatedEntity | Union of SponsoredCampaignUrn , SponsoredCreativeUrn , OrganizationUrn , EventUrn | URN identifying the entity to which the Lead Form is attached. Leads are collected via the Lead Form attached to this entity, e.g. this could be a sponsored creative/ad (e.g. urn:li:sponsoredCreative:123456) with an attached Lead Form.This is an optional field and should only be included if the subscription is made for an associated entity to which the Lead Form is attached, only actions such as lead submissions made on this particular form should trigger notifications. If a separate subscription containing only an owner or an owner and form exists, the same trigger will send payloads to both subscriptions if webhooks are different. Otherwise, this will be null. Note : SponsoredCampaignUrn type is only supported from 202403 and above versions. |
No | No |
Existing Lead notification URLs can be requested individually through the following endpoint.
GET https://api.linkedin.com/rest/leadNotifications?q=criteria&owner=(value:(sponsoredAccount:urn%3Ali%3AsponsoredAccount%3A511849581))&leadType=(leadType:SPONSORED)
{
"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"
}
}
}
{
"owner": {
"sponsoredAccount": "urn:li:sponsoredAccount:520866471"
},
"webhook": "https://eogi5ry4pv6izmq.m.pipedream.net",
"id": 107708,
"leadType": "SPONSORED"
}
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.
Use the following endpoint to create a new leadNotificationSubscription
against an associated entity.
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"},"associatedEntity":{"event":"urn:li:event:123"}, "leadType": "SPONSORED"}’
A successful response returns a 201 Created
HTTP status code.
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.
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. For 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 will be encrypted with SSL.
You can remove a Lead notification URL when you No longer want to receive notifications.
Q: What happens if I have multiple subscriptions under an owner?
A: We honor all subscriptions and will 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 does not correctly return the HMAC-SHA256 encoding of the sent challenge code using the correct client secret. Please review 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, the behavior of our system is such that 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 below:
Field | Description |
---|---|
type | Will always be 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, will be set to "SPONSORED" for sponsored leads. |
leadAction | Action performed on the lead, will be either "CREATED" or "DELETED". |
occuredAt | Unix timestamp for when the action occurred. |
{
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
}
{
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
}
The following are the possible error codes and their resolutions:
HTTP STATUS CODE | ERROR MESSAGE | DESCRIPTION | RESOLUTION |
---|---|---|---|
401 | Member is not authorized to create LeadGenForm | Member does not 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 does not 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 does not 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 does not have lead access permission. | Member does not 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 does not meet validation checks. Owner of Lead Form does not 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 does not 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 be have unique values. |
Training
Module
Manage forms and pages in Dynamics 365 Customer Insights - Journeys - Training
Learn how to manage forms and marketing pages in Dynamics 365 Customer Insights - Journeys. This module applies to outbound marketing features only.