> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # 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. ## 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](https://aisa.one/docs/reference-contracts/aisa-ads.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "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. ## OpenAPI ````yaml reference-contracts/aisa-ads.json POST /apis/v1/ads/lead-forms openapi: 3.1.0 info: description: '' title: AIsa Ads version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: [] x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '27' response_pending: [] document_hash: sha256:ba353f59e89e1ebabe0e301d8ef57d3cbfa6bb406a8c591ee9c3833d64b60520 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: aisa-ads x-aisa-catalogs: aisa-ads: title: AIsa Ads description: '' x-aisa-document: facts_hash: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/ads/lead-forms: post: summary: Create a lead form description: >- 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. operationId: post_aisa_ads_apis_v1_ads_lead_forms 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 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 responses: '200': content: application/json: schema: properties: form: properties: id: type: string name: type: string type: object status: type: string type: object description: Created form. default: content: application/json: schema: properties: error: properties: code: type: - string - 'null' details: additionalProperties: {} type: - object - 'null' message: type: - string - 'null' param: type: - string - 'null' retryHint: type: - string - 'null' retryable: type: - boolean - 'null' type: type: - string - 'null' type: - object - 'null' type: object description: Error. The code field is stable; see the error catalog. components: securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.