Form Automation Workflow

Fresh Source: docs.airtop.ai

Automate form filling using Airtop's AI-powered fillForm method. The AI analyzes form fields and maps your data to the correct inputs.

Architecture

Complete Example

TypeScript

import Airtop from '@airtop/sdk';

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

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

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

    // Fill the form with AI
    const result = await client.windows.fillForm(sessionId, windowId, {
      customData: {
        firstName: 'John',
        lastName: 'Doe',
        email: 'john.doe@example.com',
        phone: '555-0123',
        company: 'Acme Corp',
        message: 'I would like to learn more about your services.',
      },
    });

    console.log('Form filled:', result.data);

    // Verify by querying the page
    const verify = await client.windows.pageQuery(sessionId, windowId, {
      prompt: 'Are all form fields filled in correctly? List any empty or incorrect fields.',
    });
    console.log('Verification:', verify.data.modelResponse);

    // Submit the form
    await client.windows.click(sessionId, windowId, {
      elementDescription: 'submit button',
    });
  } finally {
    await client.sessions.terminate(sessionId);
  }
}

Python

from airtop import Airtop

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

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

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

        # Fill the form with AI
        result = client.windows.fill_form(session_id, window_id, custom_data={
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "phone": "555-0123",
            "company": "Acme Corp",
            "message": "I would like to learn more about your services.",
        })
        print(f"Form filled: {result.data}")

        # Verify by querying the page
        verify = client.windows.page_query(
            session_id, window_id,
            prompt="Are all form fields filled in correctly? List any empty fields."
        )
        print(f"Verification: {verify.data.model_response}")

        # Submit the form
        client.windows.click(
            session_id, window_id,
            element_description="submit button"
        )
    finally:
        client.sessions.terminate(session_id)

How fillForm Works

The fillForm method uses a two-phase process:

1. Analysis phase — AI examines the page to identify all form fields, their types, labels, and validation requirements
2. Filling phase — AI maps your customData keys to the identified fields and fills them in

The AI is smart about matching — firstName in your data maps to a field labeled "First Name", "first_name", or even "Given Name".

customData Format

The customData object uses key-value pairs. Keys should be descriptive — the AI uses them to match fields.

{
  // Personal info
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',

  // Address
  streetAddress: '123 Main St',
  city: 'New York',
  state: 'NY',
  zipCode: '10001',

  // Dropdowns — use the option text
  country: 'United States',
  preferredContact: 'Email',
}

Best Practices

1. Use descriptive keys — phoneNumber is better than phone for matching
2. Match dropdown values to visible option text, not internal values
3. Verify after filling — use pageQuery to confirm fields were filled correctly
4. Handle multi-step forms — fill one section, click next, fill the next section
5. Increase timeout — complex forms with many fields may take longer