# Get page lead forms GET https://services.leadconnectorhq.com/ad-publishing/facebook/page/{pageId}/forms Retrieve lead gen forms for a specific Facebook page (published + drafts), sorted newest-first by `createdTime`. By default each form is returned in full (including its `questions`) as a plain array; pass `projection` (comma-separated) to return only the requested fields — any value outside the known field set is rejected. Pass `limit` (max 100) for a `{ forms, paging }` envelope; use `after` (from `paging.next`) to fetch the next batch. ## 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 | |------|------|----------|-------------| | `pageId` | string | Yes | Facebook page identifier | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `locationId` | string | Yes | Location identifier | | `projection` | array | No | Fields to return on each lead form, comma-separated (e.g. ?projection=name,id,pageId,status,isDraft,createdTime). When set, only the requested fields are returned; any other value is rejected. Omit to receive the full form (including questions) as-is. | | `limit` | string | No | Page size for a paginated fetch (max 100). When set, the response is a { forms, paging } envelope instead of a plain array. | | `after` | string | No | Opaque cursor for the next batch, taken from the previous response paging.next | ## OpenAPI Specification ```json { "openapi": "3.0.0", "info": { "title": "HighLevel API", "version": "v3" }, "servers": [ { "url": "https://services.leadconnectorhq.com" } ], "paths": { "/ad-publishing/facebook/page/{pageId}/forms": { "get": { "summary": "Get page lead forms", "operationId": "getPageLeadForms", "description": "Retrieve lead gen forms for a specific Facebook page (published + drafts), sorted newest-first by `createdTime`. By default each form is returned in full (including its `questions`) as a plain array; pass `projection` (comma-separated) to return only the requested fields — any value outside the known field set is rejected. Pass `limit` (max 100) for a `{ forms, paging }` envelope; use `after` (from `paging.next`) to fetch the next batch.", "parameters": [ { "name": "Version", "in": "header", "description": "API Version", "required": true, "schema": { "type": "string", "enum": [ "v3" ] } }, { "name": "pageId", "required": true, "in": "path", "description": "Facebook page identifier", "schema": { "example": "103456789012345", "type": "string" } }, { "name": "locationId", "required": true, "in": "query", "description": "Location identifier", "schema": { "example": "loc_abc123", "type": "string" } }, { "name": "projection", "required": false, "in": "query", "description": "Fields to return on each lead form, comma-separated (e.g. ?projection=name,id,pageId,status,isDraft,createdTime). When set, only the requested fields are returned; any other value is rejected. Omit to receive the full form (including questions) as-is.", "schema": { "example": [ "name", "id", "pageId", "status", "isDraft", "createdTime" ], "type": "array", "items": { "type": "string", "enum": [ "id", "name", "pageId", "status", "isDraft", "createdTime", "locale", "page", "questions" ] } } }, { "name": "limit", "required": false, "in": "query", "description": "Page size for a paginated fetch (max 100). When set, the response is a { forms, paging } envelope instead of a plain array.", "schema": { "example": "25", "type": "string" } }, { "name": "after", "required": false, "in": "query", "description": "Opaque cursor for the next batch, taken from the previous response paging.next", "schema": { "example": "25", "type": "string" } } ], "responses": { "200": { "description": "A plain array of lead forms (default), or a { forms, paging } envelope when `limit` is provided. Each entry is either a form published to Facebook or an unpublished local draft — the two shapes differ, and `isDraft` tells them apart. Supplying `projection` narrows every entry to the requested fields only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPageLeadFormsResponse" } } } }, "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": { "GetPageLeadFormsResponse": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Facebook lead form id", "example": "925225066711682" }, "name": { "type": "string", "description": "Form name", "example": "Automation Lead Form 2026-08-19 00:32:49" }, "locale": { "type": "string", "description": "Form locale, lower-cased by Facebook. Note drafts report the same locale upper-cased.", "example": "en_US" }, "status": { "type": "string", "description": "Form status. Always `ACTIVE` in this list — the upstream query filters the others out.", "example": "ACTIVE" }, "createdTime": { "type": "string", "description": "Creation time in the Facebook timestamp format (`+0000` offset, no sub-second precision). Drafts use ISO-8601 with milliseconds instead, so a client parsing this field must accept both.", "example": "2026-08-19T00:32:57+0000" }, "page": { "description": "Page the form belongs to", "example": { "name": "Ad Manager primary", "id": "196684453527082" }, "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Page name", "example": "Ad Manager primary" }, "id": { "type": "string", "description": "Page id", "example": "196684453527082" } }, "required": [ "name", "id" ], "title": "FacebookLeadFormPageRefDTO" } ] }, "pageId": { "type": "string", "description": "Page id, repeated from `page.id`", "example": "196684453527082" }, "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" } } }, "title": "FacebookPublishedLeadFormDTO" }, { "type": "object", "properties": { "id": { "type": "string", "description": "Draft id, always prefixed to distinguish it from a Facebook form id", "example": "draft_6a7d9fa9d4e1daea36a9585e" }, "isDraft": { "type": "boolean", "description": "Always true — this is what marks the entry as an unpublished draft", "example": true }, "name": { "type": "string", "description": "Form name", "example": "Public API test draft" }, "locationId": { "type": "string", "description": "Location the draft belongs to", "example": "fRMewNQIxSyZ5R4nQyit" }, "pageId": { "type": "string", "description": "Page the draft will be published 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. Published forms report the same value lower-cased (`en_US`).", "example": "EN_US" }, "createdTime": { "type": "string", "description": "Creation time in ISO-8601 with milliseconds. Published forms use the Facebook timestamp format.", "example": "2026-08-13T10:42:49.397Z" }, "greetingCard": { "description": "Intro card shown before the questions", "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 on the form", "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. Empty string when not set.", "example": "" }, "privacyPolicyText": { "type": "string", "description": "Privacy policy link text. Empty string when not set.", "example": "" }, "customDisclaimer": { "description": "Optional 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 shown after submit", "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" } ] } }, "title": "FacebookDraftLeadFormDTO" } ] } }, { "type": "object", "properties": { "forms": { "type": "array", "description": "Page of Facebook lead forms (sorted by createdTime, newest first). Published forms carry `status`; unsaved drafts carry `isDraft: true` instead, and their `id` is prefixed to distinguish it from a Facebook form id.", "items": { "type": "object", "additionalProperties": true }, "example": [ { "id": "123456789012345", "name": "Spring Promo Lead Form", "status": "ACTIVE", "createdTime": "2024-03-18T10:24:00+0000" }, { "id": "draft_65f1a2b3c4d5e6f7a8b9c0d1", "name": "Untitled form", "isDraft": true, "createdTime": "2024-03-19T08:10:00+0000" } ] }, "paging": { "description": "Pagination cursor", "example": { "next": "QVFIU..." }, "allOf": [ { "type": "object", "properties": { "next": { "type": "string", "description": "Cursor for the next page of results, or null when there are no more pages", "example": "QVFIU...", "nullable": true } }, "required": [ "next" ], "title": "FacebookPagingDTO" } ] } }, "required": [ "forms", "paging" ], "title": "PaginatedFacebookLeadFormsDTO" } ] }, "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/page//forms?locationId=' \ -H 'Authorization: Bearer ' \ -H 'Version: v3' ``` **Node.js** ```javascript const options = { method: 'GET', headers: { Authorization: 'Bearer ', Version: 'v3' } }; try { const response = await fetch('https://services.leadconnectorhq.com/ad-publishing/facebook/page//forms?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/page/{pageId}/forms" headers = { "Authorization": "Bearer ", "Version": "v3" } params = { "locationId": "" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` **PHP** ```php 'https://services.leadconnectorhq.com/ad-publishing/facebook/page//forms?locationId=', CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ', 'Version: v3', ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; ``` **Java** ```java HttpResponse response = Unirest .get("https://services.leadconnectorhq.com/ad-publishing/facebook/page//forms?locationId=") .header("Authorization", "Bearer ") .header("Version", "v3") .asString(); ``` **Go** ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://services.leadconnectorhq.com/ad-publishing/facebook/page//forms?locationId=" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Version", "v3") 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/page//forms?locationId=") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = "Bearer " request["Version"] = "v3" response = http.request(request) puts response.read_body ``` **PowerShell** ```powershell $headers = @{ "Authorization" = "Bearer " "Version" = "v3" } $response = Invoke-RestMethod -Uri 'https://services.leadconnectorhq.com/ad-publishing/facebook/page//forms?locationId=' -Method 'GET' -Headers $headers $response | ConvertTo-Json ```