Form Filling

Fresh Source: docs.airtop.ai

The fillForm method uses AI to analyze form fields on a page and fill them with your provided data. It works with any form — contact forms, registration, checkout, surveys.

How It Works

fillForm uses a two-phase process:

1. Analysis phase — AI scans the page to identify all form fields, their types (text, email, dropdown, checkbox, radio), labels, and validation rules
2. Filling phase — AI maps your customData keys to the identified fields and fills them intelligently

Basic Usage

TypeScript

const result = await client.windows.fillForm(sessionId, windowId, {
  customData: {
    firstName: 'Jane',
    lastName: 'Smith',
    email: 'jane.smith@example.com',
    phone: '555-0199',
    message: 'I am interested in your enterprise plan.',
  },
});
console.log('Fill result:', result.data);

Python

result = client.windows.fill_form(session_id, window_id, custom_data={
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "555-0199",
    "message": "I am interested in your enterprise plan.",
})
print(f"Fill result: {result.data}")

customData Formatting

Text Inputs

{
  "firstName": "Jane",
  "lastName": "Smith",
  "streetAddress": "123 Main St, Apt 4B"
}

Dropdowns

Use the visible option text:

{
  "country": "United States",
  "state": "California",
  "preferredContact": "Email"
}

Checkboxes and Radios

{
  "agreeToTerms": "yes",
  "newsletter": "no",
  "planType": "Enterprise"
}

Dates

{
  "birthDate": "1990-03-15",
  "preferredDate": "March 15, 2025"
}

Complete Workflow Example

TypeScript

import Airtop from '@airtop/sdk';

const client = new Airtop({ apiKey: process.env.AIRTOP_API_KEY });

async function fillContactForm() {
  const session = await client.sessions.create({
    configuration: { timeoutMinutes: 10 },
  });
  const sessionId = session.data.id;

  try {
    const window = await client.windows.create(sessionId, {
      url: 'https://example.com/contact',
    });
    const windowId = window.data.windowId;

    // Fill the form
    await client.windows.fillForm(sessionId, windowId, {
      customData: {
        fullName: 'Jane Smith',
        email: 'jane@company.com',
        subject: 'Partnership Inquiry',
        message: 'We would like to discuss a partnership opportunity.',
      },
    });

    // Verify the form was filled correctly
    const check = await client.windows.pageQuery(sessionId, windowId, {
      prompt: 'Check if all visible form fields are filled. List any empty required fields.',
    });
    console.log('Verification:', check.data.modelResponse);

    // Submit
    await client.windows.click(sessionId, windowId, {
      elementDescription: 'the submit or send button',
    });

    // Confirm submission
    const confirm = await client.windows.pageQuery(sessionId, windowId, {
      prompt: 'Was the form submitted successfully? Look for confirmation messages.',
    });
    console.log('Result:', confirm.data.modelResponse);
  } finally {
    await client.sessions.terminate(sessionId);
  }
}

Python

from airtop import Airtop

client = Airtop(api_key="your-api-key")

def fill_contact_form():
    session = client.sessions.create(
        configuration={"timeoutMinutes": 10}
    )
    session_id = session.data.id

    try:
        window = client.windows.create(
            session_id, url="https://example.com/contact"
        )
        window_id = window.data.window_id

        # Fill the form
        client.windows.fill_form(session_id, window_id, custom_data={
            "fullName": "Jane Smith",
            "email": "jane@company.com",
            "subject": "Partnership Inquiry",
            "message": "We would like to discuss a partnership opportunity.",
        })

        # Verify
        check = client.windows.page_query(
            session_id, window_id,
            prompt="Check if all visible form fields are filled. List any empty required fields."
        )
        print(f"Verification: {check.data.model_response}")

        # Submit
        client.windows.click(
            session_id, window_id,
            element_description="the submit or send button"
        )

        # Confirm
        confirm = client.windows.page_query(
            session_id, window_id,
            prompt="Was the form submitted successfully? Look for confirmation messages."
        )
        print(f"Result: {confirm.data.model_response}")
    finally:
        client.sessions.terminate(session_id)

Key Matching Logic

The AI matches customData keys to form fields intelligently:

customData Key	Matches Fields Labeled
firstName	"First Name", "Given Name", "first_name"
email	"Email", "Email Address", "E-mail"
phoneNumber	"Phone", "Phone Number", "Tel", "Mobile"
streetAddress	"Address", "Street Address", "Address Line 1"

Best Practices

1. Use descriptive keys — companyName > company > co
2. Match visible text for dropdowns — use "United States" not "US"
3. Verify after filling — use pageQuery to check fields
4. Handle multi-step forms — fill one page, click next, fill the next
5. Provide all required fields — the AI will skip fields without matching data