Lead Sync Schema

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.

Note

This page describes schemas using a column Returned by Default. Any field that has a non-null value is included by default. This does not apply for empty optional fields; that is, an optional field with a null value is not included in the response.

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 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's capable of localization, such as MultiLocaleString.	No	Yes	Yes
owner	Union of SponsoredAccountUrn, OrganizationUrn	URN that identifies the owner of the Lead Form. It's a union of sponsoredAccount and organization. sponsoredAccount is an URN of SponsoredAccountUrn that indicates the account of the advertiser. organization is an URN of OrganizationUrn that indicates the company page 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 is 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. (Optional) It is not present if the form hasn't 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 dataType

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
country	string	An uppercase two-letter country code as defined by ISO-3166.	No	Yes	Yes
language	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 object

DisplayContent is a 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	(Optional) 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	(Optional) Information displayed to the user after submitting the form (e.g. thank you message, etc.). It is optional since not all use cases require a post submission experience.	No	No	Yes

MultiLocaleString dataType

MultiLocaleString is a data type in the Lead Form that represents a textual field with values for multiple locales. We recommend to use the localized field entry keyed by preferredLocale. In the Lead Form, we use the creationLocale as the preferredLocale.

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 sub-Object

LeadGenFormQuestion is a sub-object in the DisplayContent object for each 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	A human-readable, language-agnostic name for the question, used by the form owner to identify it within a form. This name is not visible to the viewer in the rendered form.	No	Yes	Yes
question	MultiLocaleString	The question prompt, shown to the viewer.	No	Yes	Yes
textPrompt	MultiLocaleString	(Optional) The description or hint of the question, shown to the viewer. Empty if no hint is provided.	No	No	Yes
predefinedField	PredefinedField	(Optional) 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 don't request a predefined field and 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	Union of WorkEmailSubmissionCriteria	(Optional) Criteria for submitting a response to the question. Example: Only non-freemium emails are allowed for the work email question. Applies only to questions using a predefined field.	No	No	Yes
label	string	(Optional) 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 sub-Object

PredefinedField is a sub-object within the LeadGenFormQuestion, which specifies that the question should use a predefined field in a Lead Form. Some of these fields can be prefilled using the viewer's profile information.

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.
EMAIL	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 sub-Object

TextQuestionDetails is a sub-object in the LeadGenFormQuestion that represents 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 could not be prefilled.	No	No	Yes
maxResponseLength	int	The maximum length of the response, in characters. Default is 300.	No	No	Yes

MultipleChoiceQuestionDetails sub-Object

MultipleChoiceQuestionDetails is a sub-object in the LeadGenFormQuestion that represents 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 sub-Object

MultipleChoiceQuestionOption is a sub-object in the MultipleChoiceQuestionDetails, structured as an element in the array named options. MultipleChoiceQuestionOption represents 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 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	(optional) 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 sub-Object

WorkEmailSubmissionCriteria is a sub-object in the LeadGenFormQuestion that represents 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 is allowed to be submitted as the response of the WORK EMAIL PredefinedField.	No	Yes	Yes

LeadGenFormLegalInfo sub-Object

LeadGenFormLegalInfo is a sub-object in the Lead Form that represents 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	(Optional) 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	(Optional) 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. The array can be empty if no viewer consents are required by the owner. By default, this is an empty array.	No	No	Yes

LeadGenFormConsent sub-Object

LeadGenFormConsent is a sub-object in the LeadGenFormLegalInfo, structured as an element in the array named consents. LeadGenFormConsent that represents 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're 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	(Optional) 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 sub-Object

PostSubmissionInfo is a sub-object in the Lead Form that represents 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 sub-Object

LeadGenFormCallToAction is a sub-object in the PostSubmissionInfo that represents 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. Example: A LandingPageUrl which is a URL redirect to a web page. It can be empty for CTAs which do not require additional information.	No	No	Yes

PostSubmissionCallToActionLabel sub-Object

PostSubmissionCallToActionLabel is a sub-object in the LeadGenFormCallToAction that predefines 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 sub-Object

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.

HiddenField values support both static and dynamic entries similar to Dynamic UTM Tracking. For more details about hidden fields behavior, refer to Lead Gen Form hidden fields. For a list of supported dynamic values, refer to Supported tracking parameters.

Note

Hidden field dynamic values follow the pattern {{DYNAMIC_VALUE}} where DYNAMIC_VALUE is replaced by the specific parameter name (e.g., {{ACCOUNT_ID}}).

The array can contain a maximum of 20 HiddenField elements.

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 sub-Object

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 sub-Object

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 sub-Object

LeadGenFormReviewStatus is a sub-object in the LeadGenReviewInfo that indicates 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 Form Response Schema

Field	Type	Description	Returned by Default
id	string	Unique id to identify the Lead Form Response.	Yes
leadType	LeadType	Type of the lead that represents the origination of the lead.	Yes
form	LeadGenForm	The Lead Gen Form associated to the lead.	No
owner	Union of SponsoredAccountURN, OrganizationURN	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	(optional) LeadGenFormResponseOwnerInfo	Record containing entity info that owns this Lead Form Response. It's an optional Union of sponsoredAccountInfo and organizationInfo.	No
leadMetadata	(optional) Union of SponsoredLeadMetadata	Metadata entity reference for a lead as SponsoredLeadMetadata with campaign field which is an URN of SponsoredCampaignUrn. This field is optional for test leads and other use cases where sponsored lead metadata (e.g. campaign) may not be relevant.	Yes
leadMetadataInfo	(optional) Union of SponsoredLeadMetadataInfo	Metadata entity reference details. Record containing a subset of fields resolved on demand from the lead metadata references (e.g. campaign name , campaign type). Can be empty for test leads and cases where no lead metadata is relevant.	No
associatedEntity	Union of SponsoredCreativeUrn , OrganizationUrn , EventUrn , StandardizedProductUrn, OrganizationLandingPageUrn	URN identifying which entity the lead is associated with. This field should match with the leadType if there is an associatedEntity. This field is optional for test leads and other use cases where leads don't have any associatedEntity. If there's 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.	No
submitter	URN	From version 202408 onwards, Guest Leads (when a user submits a form without being logged in) submitted to lead forms, submitter field is treated as a null field and omitted from the JSON response. For non-guest leads, the submitter field is included in the response and provides the person's URN. Ex: "submitter": "urn:li:person:MpGcnvaU_p".	Yes
submittedAt	Time	An epoch timestamp that records 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 Sub-Object

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.

LeadGenFormResponseOwnerInfo Sub-Object

LeadGenFormResponseOwnerInfo is a sub-object in the Lead Form Response that indicates Union of sponsoredAccountInfo and organizationInfo that represents details of the LeadGenFormResponse's owner entity.

sponsoredAccountInfo represents the below SponsoredAccount information as the owner of the Lead.

Field	Type	Description
sponsoredAccount	sponsoredAccountUrn	Identifier for the advertising account
name	string	Name of the advertising account, useful for labeling an account
localizedOrganizationName	(Optional) string	The locale-specific name of the organization associated with this ad account

organizationInfo represents the organizationUrn as the owner of the Lead.

SponsoredLeadMetadataInfo Sub-Object

SponsoredLeadMetadataInfo is a sub-object in the Lead Form Response that indicates metadata entity reference details for a lead with campaign field. These fields hold some optional fields, that may or may not used for different cases.

campaign represents the below SponsoredCampaign information as the metadata.

Field	Type	Description
id	SponsoredCampaignUrn	Identifier for the ad campaign
name	string	Name of the ad campaign
type	string	The type of ad campaign (TEXT_AD, SPONSORED_UPDATES, SPONSORED_INMAILS, DYNAMIC)

FormResponse Sub-Object

FormResponse is a sub-object in the Lead Form Response that represents 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 Sub-Object

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 Sub-Object

TextQuestionAnswer is a sub-object in the Answer that represents 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 Sub-Object

MultipleChoiceAnswer is a sub-object in the Answer that represents 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 Sub-Object

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're consenting to.	Yes
accepted	boolean	Consent answer provided by a submitter. True if the submitter chooses to opt-in.	Yes

Lead Notification Subscriptions

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	LeadType	Lead type for which the subscription is created. LeadType can be sponsored or organic.	No	Yes
versionedFormUrn	(optional) 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 is only 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 sends payloads to both subscriptions if the webhooks are different. Otherwise, this is null.	No	No
associatedEntity	(optional) Union of SponsoredCreativeUrn, OrganizationUrn, EventUrn, StandardizedProductUrn, and OrganizationLandingPageUrn	URN identifying the entity to which the Lead Form is attached. Leads are collected via the Lead Form attached to this entity. Example: This could be a sponsored creative/ad (urn:li:sponsoredCreative:123456) with an attached Lead Form. This is an optional field. Include it only if the subscription is for an associated entity to which the Lead Form is attached. In this case, only actions such as lead submissions made on this particular form will trigger notifications. If a separate subscription exists for only an owner or for an owner and form, the same trigger sends payloads to both subscriptions if the webhooks are different. Otherwise, this is null.	No	No