Ads · Lead Gen
Creates a lead form. Works with Meta Ads and LinkedIn Ads.
POST
https://api.pozy.ai/v1/ads/lead-formsFacebook and Instagram and LinkedIncreateLeadForm
Guide: Lead forms
Request
Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the ads resource group disabled get 403 resource_group_disabled. Authentication
Request body
application/json, required
accountIdstringrequirednamestringrequiredUp to 200 characters.
questionsarray of objectdeprecatedAt least 1 item.
typestringrequiredkeystringlabelstringoptionsarray of object2 child fields
keystringvaluestring
inline_contextstring
privacyPolicyUrlstring (URL)requiredprivacyPolicyLinkTextstringdeprecatedUp to 70 characters.
followUpActionUrlstring (URL)deprecatedlocalestringdeprecatedthankYouTitlestringdeprecatedthankYouBodystringdeprecatedthankYouButtonTextstringdeprecatedthankYouButtonTypestringdeprecatedthankYouWebsiteUrlstring (URL)deprecatedisOptimizedForQualitybooleandeprecatedplatformSpecificDataobjectOne of:
MetaLeadFormPlatformData (18 fields)
questionsarray of objectrequiredAt least 1 item.
5 child fields
typestringrequiredkeystringlabelstringoptionsarray of object2 child fields
keystringvaluestring
inline_contextstring
privacyPolicyLinkTextstringUp to 70 characters.
followUpActionUrlstring (URL)localestringthankYouTitlestringthankYouBodystringthankYouButtonTextstringthankYouButtonTypestringbusinessPhoneNumberstringcountryCodestringMatches
^[A-Za-z]{2}$.thankYouWebsiteUrlstring (URL)thankYouEnableMessengerbooleanDefault
false.isOptimizedForQualitybooleanisPhoneSmsVerifyEnabledbooleanDefault
false.blockDisplayForNonTargetedViewerbooleanquestionPageCustomHeadlinestringcontextCardobject5 child fields
titlestringcontentarray of stringstylestringOne of
LIST_STYLE,PARAGRAPH_STYLE.buttonTextstringcoverPhotostring (URL)
customDisclaimerobject3 child fields
titlestringrequiredbodystringrequiredcheckboxesarray of objectrequiredAt least 1 item.
4 child fields
keystringrequiredtextstringrequiredisRequiredbooleanDefault
false.isCheckedByDefaultbooleanDefault
false.
LinkedInLeadFormPlatformData (7 fields)
adAccountIdstringrequiredheadlinestringrequiredUp to 255 characters.
descriptionstringrequiredUp to 1500 characters.
statestringOne of
DRAFT,PUBLISHED.localeobject2 child fields
countrystringlanguagestring
consentsarray of object2 child fields
descriptionstringrequiredrequiredbooleanDefault
false.
questionsarray of objectrequiredAt least 1 item.
One of:
Option 1 (6 fields)
kindstringrequiredOne of
text.namestringrequiredquestionstringrequiredrequiredbooleanresponseEditablebooleanmaxResponseLengthinteger
Option 2 (6 fields)
kindstringrequiredOne of
multipleChoice.namestringrequiredquestionstringrequiredrequiredbooleanresponseEditablebooleanchoicesarray of objectrequiredAt least 1 item.
2 child fields
idintegerrequiredtextstringrequired
Example
curl -X POST "https://api.pozy.ai/v1/ads/lead-forms" \
-H "Authorization: Bearer $POZY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "696e0b682d0a31188e7a2ba9",
"name": "Acme",
"privacyPolicyUrl": "https://pozy.ai/media/example-1.jpg"
}'const res = await fetch("https://api.pozy.ai/v1/ads/lead-forms", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.POZY_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
accountId: "696e0b682d0a31188e7a2ba9",
name: "Acme",
privacyPolicyUrl: "https://pozy.ai/media/example-1.jpg"
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);import os
import requests
resp = requests.post(
"https://api.pozy.ai/v1/ads/lead-forms",
headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
json={
"accountId": "696e0b682d0a31188e7a2ba9",
"name": "Acme",
"privacyPolicyUrl": "https://pozy.ai/media/example-1.jpg",
},
timeout=30,
)
resp.raise_for_status()
print(resp.json())Response
200 on success
statusstringformobjectidstringnamestring
200 response
{
"status": "active",
"form": {
"id": "6bfebd43ddc270f6d2c56fc5",
"name": "Acme"
}
}Errors
Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:
| 400 | invalid_request_error | A parameter or body field is missing or invalid. param names it. |
| 401 | authentication_error | The API key is missing, revoked or expired. |
| 403 | permission_error | The key is read-only, scoped to other profiles, or has this resource group disabled. |
| 429 | rate_limit_error | Too many requests this minute. Wait for Retry-After seconds. |
Every code is listed in Errors.