# Get lead form by ID GET https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/{leadFormId} Retrieve a lead form by id. Pass `isDraft=true` to read an unpublished local draft instead, in which case `leadFormId` accepts either the bare id or the `draft_`-prefixed form the listing endpoint reports. The two branches return different shapes, and neither matches the shape the listing endpoint returns for the same form: the published branch carries the full Meta definition (context card, thank-you page, legal content) but no `status`, `createdTime`, or `pageId`, while the draft branch returns the stored document verbatim under `_id`. ## Authentication Send `Authorization: Bearer ` using: - **Sub-Account token: OAuth access token or Private Integration Token.** Scopes: `adPublishing.readonly` ## Parameters ### Header Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `Version` | string | Yes | API Version | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `leadFormId` | string | Yes | Lead form identifier | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `locationId` | string | Yes | Location identifier | | `isDraft` | boolean | No | Fetch the unpublished draft of this lead form instead of the published form | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "HighLevel API", "version": "v4" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/ad-publishing/facebook/lead-form/{leadFormId}": { "get": { "summary": "Get lead form by ID", "operationId": "getLeadFormById", "description": "Retrieve a lead form by id. Pass `isDraft=true` to read an unpublished local draft instead, in which case `leadFormId` accepts either the bare id or the `draft_`-prefixed form the listing endpoint reports. The two branches return different shapes, and neither matches the shape the listing endpoint returns for the same form: the published branch carries the full Meta definition (context card, thank-you page, legal content) but no `status`, `createdTime`, or `pageId`, while the draft branch returns the stored document verbatim under `_id`.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v4" ] } }, { "name": "leadFormId", "required": true, "in": "path", "description": "Lead form identifier", "schema": { "example": "507f1f77bcf86cd799439011", "type": "string" } }, { "name": "locationId", "required": true, "in": "query", "description": "Location identifier", "schema": { "example": "HChooFuiyPpVYzeJ4HMe", "type": "string" } }, { "name": "isDraft", "required": false, "in": "query", "description": "Fetch the unpublished draft of this lead form instead of the published form", "schema": { "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "The published form from Meta, or the stored draft when `isDraft` is set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLeadFormByIdResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestDTO" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedDTO" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprocessableDTO" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorDTO" } } } } }, "security": [ { "bearer": [ "adPublishing.readonly" ] } ] } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.", "type": "http" }, "Location-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Sub-Account.", "type": "http" }, "Agency-Access": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.", "type": "http" }, "Agency-Access-Only": { "scheme": "bearer", "bearerFormat": "JWT", "name": "Authorization", "in": "header", "description": "Use the Access Token generated with user type as Agency.", "type": "http" } }, "schemas": { "GetLeadFormByIdResponse": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Facebook lead form id", "example": "1731762131493784" }, "name": { "type": "string", "description": "Form name", "example": "Automation Lead Form 2026-07-16 00:22:40" }, "locale": { "type": "string", "description": "Form locale, lower-cased by Meta", "example": "en_US" }, "questions": { "description": "Questions on the form", "example": [ { "id": "1751700749315902", "key": "full_name", "label": "What is your name?", "type": "CUSTOM", "options": [ { "key": "Option 1", "value": "Option 1" } ] } ], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Facebook question id", "example": "1751700749315902" }, "key": { "type": "string", "description": "Field key the answer is delivered under. Prefilled question types use a fixed key (`full_name`, `email`, `phone`); `CUSTOM` questions get a key derived from the label.", "example": "full_name" }, "label": { "type": "string", "description": "Question text shown to the user", "example": "What is your name?" }, "type": { "type": "string", "description": "Question type. `CUSTOM` is a free-text or multiple-choice question authored on the form; every other value is a Facebook prefilled field.", "example": "CUSTOM" }, "options": { "description": "Choices, present only on multiple-choice questions", "example": [ { "key": "Option 1", "value": "Option 1" } ], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Option key", "example": "Option 1" }, "value": { "type": "string", "description": "Option display value", "example": "Option 1" } }, "required": [ "key", "value" ], "title": "FacebookLeadFormQuestionOptionDTO" } } }, "required": [ "id", "key", "label", "type" ], "title": "FacebookPublishedLeadFormQuestionDTO" } }, "contextCard": { "description": "Intro card shown before the questions. The draft representation calls this `greetingCard`.", "example": { "id": "1320904143101881", "title": "Test Lead Form", "content": [ "Automation test lead form" ], "style": "PARAGRAPH_STYLE" }, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Meta id for the card", "example": "1320904143101881" }, "title": { "type": "string", "description": "Card headline", "example": "Test Lead Form" }, "content": { "description": "Body lines, rendered as a paragraph or bullets depending on `style`", "example": [ "Automation test lead form" ], "type": "array", "items": { "type": "string" } }, "style": { "type": "string", "description": "Layout of the body", "enum": [ "LIST_STYLE", "PARAGRAPH_STYLE" ], "example": "PARAGRAPH_STYLE" } }, "required": [ "id", "title", "content", "style" ], "title": "FacebookLeadFormContextCardDTO" } ] }, "questionPageCustomHeadline": { "type": "string", "description": "Headline above the questions. The draft representation calls this `questionPageHeadline`.", "example": "Test Lead Form - Headline" }, "isOptimizedForQuality": { "type": "boolean", "description": "Whether the form uses the higher-intent flow, which adds a review step. Set when the form was created with `type: HIGHER_INTENT`.", "example": false }, "privacyPolicyUrl": { "type": "string", "description": "Privacy policy URL, repeated from `legalContent.privacyPolicy.url`", "example": "https://example.com/privacy" }, "thankYouPage": { "description": "Confirmation screen", "example": { "id": "1778746963315596", "title": "Thank You", "body": "We will contact you shortly.", "buttonText": "View website", "buttonType": "VIEW_WEBSITE", "websiteUrl": "https://example.com/", "enableMessenger": false }, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Meta id for the page", "example": "1778746963315596" }, "title": { "type": "string", "description": "Headline", "example": "Thank You" }, "body": { "type": "string", "description": "Body copy", "example": "We will contact you shortly." }, "buttonText": { "type": "string", "description": "Call-to-action button label", "example": "View website" }, "buttonType": { "type": "string", "description": "Button action", "enum": [ "VIEW_WEBSITE", "CALL_BUSINESS", "DOWNLOAD" ], "example": "VIEW_WEBSITE" }, "websiteUrl": { "type": "string", "description": "Destination URL. The draft representation calls this same value `buttonLink`.", "example": "https://example.com/" }, "enableMessenger": { "type": "boolean", "description": "Whether a Messenger hand-off is offered after submit", "example": false } }, "required": [ "id", "title", "body", "buttonText", "buttonType" ], "title": "FacebookLeadFormThankYouPageDTO" } ] }, "followUpActionUrl": { "type": "string", "description": "URL the follow-up action opens", "example": "https://example.com/" }, "followUpActionText": { "type": "string", "description": "Label for the follow-up action. Omitted by Meta when unset.", "example": "Visit us" }, "legalContent": { "description": "Privacy policy and disclaimer", "example": { "id": "1975017193204256", "privacyPolicy": { "url": "https://example.com/privacy", "linkText": "We respect your privacy" }, "customDisclaimer": { "title": "Terms & Conditions", "body": { "text": "By submitting..." }, "checkboxes": [ { "id": "851816397792714", "key": "terms_and_conditions", "text": "I agree to the terms & conditions", "isRequired": false, "isCheckedByDefault": false } ] } }, "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Meta id for the legal block", "example": "1975017193204256" }, "privacyPolicy": { "description": "Privacy policy link", "example": { "url": "https://example.com/privacy", "linkText": "We respect your privacy" }, "allOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "Privacy policy URL", "example": "https://example.com/privacy" }, "linkText": { "type": "string", "description": "Link text shown to the user", "example": "We respect your privacy" } }, "required": [ "url", "linkText" ], "title": "FacebookLeadFormPrivacyPolicyDTO" } ] }, "customDisclaimer": { "description": "Custom disclaimer block", "example": { "title": "Terms & Conditions", "body": { "text": "By submitting..." }, "checkboxes": [ { "id": "851816397792714", "key": "terms_and_conditions", "text": "I agree to the terms & conditions", "isRequired": false, "isCheckedByDefault": false } ] }, "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "description": "Disclaimer heading", "example": "Terms & Conditions" }, "body": { "type": "object", "description": "Disclaimer copy, wrapped in an object by Meta rather than returned as a plain string", "additionalProperties": { "type": "string" }, "example": { "text": "By submitting..." } }, "checkboxes": { "description": "Consent checkboxes shown under the disclaimer", "example": [ { "id": "851816397792714", "key": "terms_and_conditions", "text": "I agree to the terms & conditions", "isRequired": false, "isCheckedByDefault": false } ], "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta id for the checkbox", "example": "851816397792714" }, "key": { "type": "string", "description": "Field key the answer is delivered under", "example": "terms_and_conditions" }, "text": { "type": "string", "description": "Checkbox label", "example": "I agree to the terms & conditions" }, "isRequired": { "type": "boolean", "description": "Whether the user must tick this to submit", "example": false }, "isCheckedByDefault": { "type": "boolean", "description": "Whether the box starts ticked", "example": false } }, "required": [ "id", "key", "text", "isRequired", "isCheckedByDefault" ], "title": "FacebookLeadFormDisclaimerCheckboxDTO" } } }, "required": [ "title", "body" ], "title": "FacebookLeadFormCustomDisclaimerDTO" } ] } }, "required": [ "id" ], "title": "FacebookLeadFormLegalContentDTO" } ] } }, "required": [ "id", "name", "locale", "questions" ], "title": "FacebookLeadFormDetailDTO" }, { "type": "object", "properties": { "_id": { "type": "string", "description": "Draft id, unprefixed and under `_id`. The listing endpoint reports the same draft as `id: draft_`.", "example": "6a7d9fa9d4e1daea36a9585e" }, "name": { "type": "string", "description": "Form name", "example": "Public API test draft" }, "locationId": { "type": "string", "description": "Owning location", "example": "fRMewNQIxSyZ5R4nQyit" }, "pageId": { "type": "string", "description": "Page the draft will publish to", "example": "196684453527082" }, "type": { "type": "string", "description": "Lead form objective", "enum": [ "MORE_VOLUME", "HIGHER_INTENT" ], "example": "MORE_VOLUME" }, "locale": { "type": "string", "description": "Form locale, upper-cased as stored", "example": "EN_US" }, "greetingCard": { "description": "Intro card", "example": { "title": "Hi there, good to see you here!", "style": "LIST_STYLE", "content": [ "Ready to learn more? Just a few quick details in the form below." ], "_id": "6a7d9fa9d4e1daea36a9585f" }, "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "description": "Greeting headline", "example": "Hi there, good to see you here!" }, "style": { "type": "string", "description": "Layout of the greeting body", "enum": [ "LIST_STYLE", "PARAGRAPH_STYLE" ], "example": "LIST_STYLE" }, "content": { "description": "Body lines. Rendered as a paragraph or as bullets depending on `style`.", "example": [ "Ready to learn more? Just a few quick details in the form below." ], "type": "array", "items": { "type": "string" } }, "_id": { "type": "string", "description": "Mongo subdocument id. Internal — do not depend on it.", "example": "6a7d9fa9d4e1daea36a9585f" } }, "required": [ "title", "style", "content" ], "title": "FacebookDraftLeadFormGreetingCardDTO" } ] }, "questions": { "description": "Questions as stored", "example": [ { "key": "full_name", "type": "FULL_NAME", "label": "What is your name?", "options": [ { "key": "Option 1", "value": "Option 1" } ], "_id": "6a7d9fa9d4e1daea36a95860" } ], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Field key the answer will be delivered under", "example": "full_name" }, "type": { "type": "string", "description": "Question type", "example": "FULL_NAME" }, "label": { "type": "string", "description": "Question text. Absent on prefilled questions that have not been given a custom label.", "example": "What is your name?" }, "options": { "description": "Choices. Always present on a draft, empty for anything that is not multiple choice.", "example": [ { "key": "Option 1", "value": "Option 1" } ], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Option key", "example": "Option 1" }, "value": { "type": "string", "description": "Option display value", "example": "Option 1" } }, "required": [ "key", "value" ], "title": "FacebookLeadFormQuestionOptionDTO" } }, "_id": { "type": "string", "description": "Mongo subdocument id. Internal — do not depend on it.", "example": "6a7d9fa9d4e1daea36a95860" } }, "required": [ "key", "type", "options" ], "title": "FacebookDraftLeadFormQuestionDTO" } }, "questionPageHeadline": { "type": "string", "description": "Headline above the questions", "example": "We'll use your information to send you our weekly newsletters." }, "privacyPolicyLink": { "type": "string", "description": "Privacy policy URL", "example": "" }, "privacyPolicyText": { "type": "string", "description": "Privacy policy link text", "example": "" }, "customDisclaimer": { "description": "Custom disclaimer block", "example": { "title": "Terms and conditions", "body": "By submitting you agree to our terms.", "checkboxes": [ { "key": "consent_marketing", "text": "I agree to receive marketing emails", "isRequired": true } ] }, "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "description": "Disclaimer heading", "example": "Terms and conditions" }, "body": { "type": "string", "description": "Disclaimer body copy", "example": "By submitting you agree to our terms." }, "checkboxes": { "description": "Consent checkboxes shown under the disclaimer", "example": [ { "key": "consent_marketing", "text": "I agree to receive marketing emails", "isRequired": true } ], "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Checkbox key", "example": "consent_marketing" }, "text": { "type": "string", "description": "Checkbox text", "example": "I agree to receive marketing emails" }, "isRequired": { "type": "boolean", "description": "Whether the user must tick this box to submit", "example": true } }, "required": [ "key", "text", "isRequired" ], "title": "FacebookDraftLeadFormDisclaimerCheckboxDTO" } } }, "required": [ "title", "body" ], "title": "FacebookDraftLeadFormDisclaimerDTO" } ] }, "thankYouPage": { "description": "Confirmation screen as stored locally", "example": { "title": "Thank you, you are all set!", "body": "You can visit our website or call us.", "buttonText": "View website", "buttonType": "VIEW_WEBSITE", "buttonLink": "", "businessPhone": "5551234567", "countryCode": "+1" }, "allOf": [ { "type": "object", "properties": { "title": { "type": "string", "description": "Thank-you headline", "example": "Thank you, you are all set!" }, "body": { "type": "string", "description": "Thank-you body copy", "example": "You can visit our website or call us." }, "buttonText": { "type": "string", "description": "Call-to-action button label", "example": "View website" }, "buttonType": { "type": "string", "description": "Button action. `VIEW_WEBSITE` and `DOWNLOAD` use `buttonLink`; `CALL_BUSINESS` uses the phone number.", "enum": [ "VIEW_WEBSITE", "CALL_BUSINESS", "DOWNLOAD" ], "example": "VIEW_WEBSITE" }, "buttonLink": { "type": "string", "description": "Destination URL. Empty string when the button does not link out.", "example": "" }, "businessPhone": { "type": "string", "description": "Phone number dialled by a CALL_BUSINESS button", "example": "5551234567" }, "countryCode": { "type": "string", "description": "Country code for `businessPhone`", "example": "+1" } }, "required": [ "title", "body", "buttonText", "buttonType" ], "title": "FacebookDraftLeadFormThankYouPageDTO" } ] }, "createdAt": { "type": "string", "description": "Creation time, ISO-8601", "example": "2026-08-13T10:42:49.397Z" }, "updatedAt": { "type": "string", "description": "Last modification time, ISO-8601", "example": "2026-08-13T10:42:49.397Z" }, "__v": { "type": "number", "description": "Mongo document version key. Internal — not part of the contract.", "example": 0 } }, "required": [ "_id", "name", "locationId", "pageId" ], "title": "FacebookDraftLeadFormDetailDTO" } ] }, "BadRequestDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Bad Request" } }, "title": "BadRequestDTO" }, "UnauthorizedDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid token: access token is invalid" }, "error": { "type": "string", "example": "Unauthorized" } }, "title": "UnauthorizedDTO" }, "UnprocessableDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 422 }, "message": { "example": [ "Unprocessable Entity" ], "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "example": "Unprocessable Entity" } }, "title": "UnprocessableDTO" }, "InternalServerErrorDTO": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "HTTP status code for an unexpected server error", "example": 500 }, "message": { "type": "string", "description": "Error message describing the server failure", "example": "Internal Server Error" } }, "title": "InternalServerErrorDTO" } } } } ``` ## Code Examples **cURL** ```bash curl -L -X GET 'https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v4' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v4' } }; try { const response = await fetch('https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=', options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` **Python** ```python import requests url = "https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/{leadFormId}" headers = { "Authorization": "Bearer ", "Version": "v4" } params = { "locationId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v4', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=") .header("Authorization", "Bearer ") .header("Version", "v4") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v4") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` **Ruby** ```ruby require 'uri' require 'net/http' url = URI("https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v4" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v4" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/ad-publishing/facebook/lead-form/?locationId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```