Create a lead form

curl --request POST \
  --url https://api.aisa.one/apis/v1/ads/lead-forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Winter launch",
  "privacyPolicyUrl": "https://example.com/landing"
}
'

import requests

url = "https://api.aisa.one/apis/v1/ads/lead-forms"

payload = {
    "name": "Winter launch",
    "privacyPolicyUrl": "https://example.com/landing"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Winter launch', privacyPolicyUrl: 'https://example.com/landing'})
};

fetch('https://api.aisa.one/apis/v1/ads/lead-forms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/lead-forms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Winter launch',
    'privacyPolicyUrl' => 'https://example.com/landing'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/ads/lead-forms"

	payload := strings.NewReader("{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/lead-forms")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/lead-forms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}"

response = http.request(request)
puts response.read_body

{
  "form": {
    "id": "<string>",
    "name": "<string>"
  },
  "status": "<string>"
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

AIsa Ads

Create a lead form

Lead Gen. Changes the ad account without starting or raising spend; audited. Creates a lead form on a Facebook Page or LinkedIn Company Page to collect contact details from ads. The form content goes inside `platformSpecificData` for both platforms (the shape is selected by the connectionId's platform). Requires the Ads add-on. NOT idempotent: a retry creates a second form. ### Meta Created on the connected Facebook Page (POST /{page-id}/leadgen_forms).  A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.

POST

https://api.aisa.one

apis

ads

lead-forms

Create a lead form

curl --request POST \
  --url https://api.aisa.one/apis/v1/ads/lead-forms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Winter launch",
  "privacyPolicyUrl": "https://example.com/landing"
}
'

import requests

url = "https://api.aisa.one/apis/v1/ads/lead-forms"

payload = {
    "name": "Winter launch",
    "privacyPolicyUrl": "https://example.com/landing"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Winter launch', privacyPolicyUrl: 'https://example.com/landing'})
};

fetch('https://api.aisa.one/apis/v1/ads/lead-forms', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads/lead-forms",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Winter launch',
    'privacyPolicyUrl' => 'https://example.com/landing'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/ads/lead-forms"

	payload := strings.NewReader("{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.aisa.one/apis/v1/ads/lead-forms")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads/lead-forms")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Winter launch\",\n  \"privacyPolicyUrl\": \"https://example.com/landing\"\n}"

response = http.request(request)
puts response.read_body

{
  "form": {
    "id": "<string>",
    "name": "<string>"
  },
  "status": "<string>"
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

Request contract

Method and path: POST /apis/v1/ads/lead-forms
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/ads/lead-forms
connectionId: query; required
Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "post_aisa_ads_apis_v1_ads_lead_forms",
  "method": "POST",
  "path": "/apis/v1/ads/lead-forms",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [
    {
      "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
      "in": "query",
      "name": "connectionId",
      "required": true,
      "schema": {
        "pattern": "^adc_[0-9A-Za-z]+$",
        "type": "string"
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "example": {
          "connectionId": "adc_7f3k2m9q",
          "name": "Winter launch",
          "privacyPolicyUrl": "https://example.com/landing"
        },
        "schema": {
          "additionalProperties": true,
          "properties": {
            "connectionId": {
              "description": "The ads connection (adc_...), when not sent as the connectionId query parameter.",
              "pattern": "^adc_[0-9A-Za-z]+$",
              "type": "string"
            },
            "followUpActionUrl": {
              "description": "Deprecated: use platformSpecificData.followUpActionUrl.",
              "format": "uri",
              "type": "string"
            },
            "isOptimizedForQuality": {
              "description": "Deprecated: use platformSpecificData.isOptimizedForQuality.",
              "type": "boolean"
            },
            "locale": {
              "description": "Deprecated: use platformSpecificData.locale.",
              "type": "string"
            },
            "name": {
              "maxLength": 200,
              "type": "string"
            },
            "platformSpecificData": {
              "description": "Form content; the shape is selected by the connectionId's platform. Unknown fields are a 400 (strict-parsed).",
              "oneOf": [
                {
                  "description": "MetaLeadFormPlatformData",
                  "properties": {
                    "blockDisplayForNonTargetedViewer": {
                      "type": "boolean"
                    },
                    "businessPhoneNumber": {
                      "description": "International E.164 number the CALL_BUSINESS thank-you button dials (Meta thank_you_page.business_phone_number). Must start with + and the country calling code matching countryCode.",
                      "type": "string"
                    },
                    "contextCard": {
                      "properties": {
                        "buttonText": {
                          "type": "string"
                        },
                        "content": {
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "coverPhoto": {
                          "description": "Direct public JPEG or PNG image URL, up to 5 MB. Uploaded as an unpublished Page photo and attached to the form. Redirects, Ad Image hashes and IDs are not supported.",
                          "format": "uri",
                          "type": "string"
                        },
                        "style": {
                          "enum": [
                            "LIST_STYLE",
                            "PARAGRAPH_STYLE"
                          ],
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "countryCode": {
                      "description": "ISO 3166-1 alpha-2 country of businessPhoneNumber (Meta thank_you_page.country_code), sent in uppercase. Required when thankYouButtonType is CALL_BUSINESS and a 400 with any other button type.",
                      "pattern": "^[A-Za-z]{2}$",
                      "type": "string"
                    },
                    "customDisclaimer": {
                      "description": "Consent section with checkboxes (Meta custom_disclaimer). Each lead's answers come back on the lead, and a lead_received workflow only messages leads that ticked its consentCheckboxKey.",
                      "properties": {
                        "body": {
                          "type": "string"
                        },
                        "checkboxes": {
                          "items": {
                            "properties": {
                              "isCheckedByDefault": {
                                "default": false,
                                "type": "boolean"
                              },
                              "isRequired": {
                                "default": false,
                                "type": "boolean"
                              },
                              "key": {
                                "type": "string"
                              },
                              "text": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "key",
                              "text"
                            ],
                            "type": "object"
                          },
                          "minItems": 1,
                          "type": "array"
                        },
                        "title": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "body",
                        "checkboxes",
                        "title"
                      ],
                      "type": "object"
                    },
                    "followUpActionUrl": {
                      "format": "uri",
                      "type": "string"
                    },
                    "isOptimizedForQuality": {
                      "description": "Set true for a higher-intent form (adds a review step before submit).",
                      "type": "boolean"
                    },
                    "isPhoneSmsVerifyEnabled": {
                      "default": false,
                      "description": "Requires the lead to verify their phone number over SMS before the form submits (Meta is_phone_sms_verify_enabled). Only meaningful on a form with a PHONE question. Meta can restrict this parameter to apps holding a capability.",
                      "type": "boolean"
                    },
                    "locale": {
                      "type": "string"
                    },
                    "privacyPolicyLinkText": {
                      "maxLength": 70,
                      "type": "string"
                    },
                    "questionPageCustomHeadline": {
                      "type": "string"
                    },
                    "questions": {
                      "items": {
                        "properties": {
                          "inline_context": {
                            "type": "string"
                          },
                          "key": {
                            "description": "CUSTOM questions only.",
                            "type": "string"
                          },
                          "label": {
                            "description": "CUSTOM questions only.",
                            "type": "string"
                          },
                          "options": {
                            "items": {
                              "properties": {
                                "key": {
                                  "type": "string"
                                },
                                "value": {
                                  "type": "string"
                                }
                              },
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "type": {
                            "description": "EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …",
                            "type": "string"
                          }
                        },
                        "required": [
                          "type"
                        ],
                        "type": "object"
                      },
                      "minItems": 1,
                      "type": "array"
                    },
                    "thankYouBody": {
                      "type": "string"
                    },
                    "thankYouButtonText": {
                      "type": "string"
                    },
                    "thankYouButtonType": {
                      "description": "Meta thank_you_page.button_type. Defaults to VIEW_WEBSITE. Case-insensitive, sent to Meta in uppercase. CALL_BUSINESS requires businessPhoneNumber and countryCode (a 400 otherwise).",
                      "type": "string"
                    },
                    "thankYouEnableMessenger": {
                      "default": false,
                      "description": "Sent as Meta thank_you_page.enable_messenger (boolean). Accepted only inside platformSpecificData: a top-level thankYouEnableMessenger is a 400.",
                      "type": "boolean"
                    },
                    "thankYouTitle": {
                      "type": "string"
                    },
                    "thankYouWebsiteUrl": {
                      "format": "uri",
                      "type": "string"
                    }
                  },
                  "required": [
                    "questions"
                  ],
                  "type": "object"
                },
                {
                  "description": "LinkedInLeadFormPlatformData",
                  "properties": {
                    "adAccountId": {
                      "description": "LinkedIn ad account id (resolves the owning organization).",
                      "type": "string"
                    },
                    "consents": {
                      "items": {
                        "properties": {
                          "description": {
                            "type": "string"
                          },
                          "required": {
                            "default": false,
                            "description": "Whether the viewer must tick this consent to submit. Defaults to false.",
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "description"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "description": {
                      "maxLength": 1500,
                      "type": "string"
                    },
                    "headline": {
                      "maxLength": 255,
                      "type": "string"
                    },
                    "locale": {
                      "properties": {
                        "country": {
                          "type": "string"
                        },
                        "language": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "questions": {
                      "items": {
                        "oneOf": [
                          {
                            "properties": {
                              "kind": {
                                "enum": [
                                  "text"
                                ],
                                "type": "string"
                              },
                              "maxResponseLength": {
                                "description": "Defaults to 300 on LinkedIn's side.",
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "question": {
                                "type": "string"
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "responseEditable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "kind",
                              "name",
                              "question"
                            ],
                            "type": "object"
                          },
                          {
                            "properties": {
                              "choices": {
                                "items": {
                                  "properties": {
                                    "id": {
                                      "type": "integer"
                                    },
                                    "text": {
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "id",
                                    "text"
                                  ],
                                  "type": "object"
                                },
                                "minItems": 1,
                                "type": "array"
                              },
                              "kind": {
                                "enum": [
                                  "multipleChoice"
                                ],
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "question": {
                                "type": "string"
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "responseEditable": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "choices",
                              "kind",
                              "name",
                              "question"
                            ],
                            "type": "object"
                          }
                        ]
                      },
                      "minItems": 1,
                      "type": "array"
                    },
                    "state": {
                      "description": "Defaults to DRAFT.",
                      "enum": [
                        "DRAFT",
                        "PUBLISHED"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "adAccountId",
                    "description",
                    "headline",
                    "questions"
                  ],
                  "type": "object"
                }
              ]
            },
            "privacyPolicyLinkText": {
              "description": "Deprecated: use platformSpecificData.privacyPolicyLinkText.",
              "maxLength": 70,
              "type": "string"
            },
            "privacyPolicyUrl": {
              "format": "uri",
              "type": "string"
            },
            "questions": {
              "description": "Deprecated (Meta legacy shape): use platformSpecificData.questions.",
              "items": {
                "properties": {
                  "inline_context": {
                    "type": "string"
                  },
                  "key": {
                    "description": "CUSTOM questions only.",
                    "type": "string"
                  },
                  "label": {
                    "description": "CUSTOM questions only.",
                    "type": "string"
                  },
                  "options": {
                    "items": {
                      "properties": {
                        "key": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "type": {
                    "description": "EMAIL, PHONE, FULL_NAME, FIRST_NAME, LAST_NAME, CUSTOM, …",
                    "type": "string"
                  }
                },
                "required": [
                  "type"
                ],
                "type": "object"
              },
              "minItems": 1,
              "type": "array"
            },
            "thankYouBody": {
              "description": "Deprecated: use platformSpecificData.thankYouBody.",
              "type": "string"
            },
            "thankYouButtonText": {
              "description": "Deprecated: use platformSpecificData.thankYouButtonText.",
              "type": "string"
            },
            "thankYouButtonType": {
              "description": "Deprecated: use platformSpecificData.thankYouButtonType.",
              "type": "string"
            },
            "thankYouTitle": {
              "description": "Deprecated: use platformSpecificData.thankYouTitle.",
              "type": "string"
            },
            "thankYouWebsiteUrl": {
              "description": "Deprecated: use platformSpecificData.thankYouWebsiteUrl.",
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "name",
            "privacyPolicyUrl"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
    "kind": "no_customer_charge"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

connectionId

string

required

The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.

Pattern: ^adc_[0-9A-Za-z]+$

Body

application/json

name

string

required

Maximum string length: 200

privacyPolicyUrl

string<uri>

required

connectionId

string

The ads connection (adc_...), when not sent as the connectionId query parameter.

Pattern: ^adc_[0-9A-Za-z]+$

followUpActionUrl

string<uri>

Deprecated: use platformSpecificData.followUpActionUrl.

isOptimizedForQuality

boolean

Deprecated: use platformSpecificData.isOptimizedForQuality.

locale

string

Deprecated: use platformSpecificData.locale.

platformSpecificData

object

Form content; the shape is selected by the connectionId's platform. Unknown fields are a 400 (strict-parsed).

Option 1
Option 2

Show child attributes

privacyPolicyLinkText

string

Deprecated: use platformSpecificData.privacyPolicyLinkText.

Maximum string length: 70

questions

object[]

Deprecated (Meta legacy shape): use platformSpecificData.questions.

Minimum array length: 1

Show child attributes

thankYouBody

string

Deprecated: use platformSpecificData.thankYouBody.

thankYouButtonText

string

Deprecated: use platformSpecificData.thankYouButtonText.

thankYouButtonType

string

Deprecated: use platformSpecificData.thankYouButtonType.

thankYouTitle

string

Deprecated: use platformSpecificData.thankYouTitle.

thankYouWebsiteUrl

string<uri>

Deprecated: use platformSpecificData.thankYouWebsiteUrl.

Response

Created form.

form

object

Show child attributes

status

string

​Request contract

​Cost and request rules

Authorizations

Query Parameters

Body

Response

Request contract

Cost and request rules