Fill and submit a form

Automate form interactions: typing into fields, selecting options, solving CAPTCHAs, and clicking submit.

Prerequisites

• A Browserless API token from your account dashboard

Steps

AI Agent

Use the Browserless MCP server to fill and submit a form from any MCP-compatible AI agent (Claude Desktop, Cursor, Windsurf, ChatGPT, etc.).

One prompt that installs the Browserless MCP server and runs this example. Paste it into your AI agent.

1. Connect the MCP server

Send this prompt to your AI agent to install the Browserless MCP server:

Go to https://github.com/browserless/browserless-mcp/blob/main/install.md
and follow the instructions to install the Browserless MCP server
for my client.

2. Fill and submit a form

Use browserless_agent. The task requires interaction: filling fields and clicking submit.

Use the browserless_agent tool to go to https://example.com/contact,
fill in the name field with "Jane Doe", the email field with
"jane@example.com", the message with "Hello!", and submit the form

REST API

Use the REST API to fill and submit a form without opening a persistent browser connection.

cURL

View Full Code on GitHub

1. Build the BrowserQL mutation

Use the BrowserQL endpoint to navigate, fill fields, and submit the form in a single request:

https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE

2. Send the request

curl -X POST \
  "https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation FormExample { goto(url: \"https://www.browserless.io/practice-form\") { status } typeEmail: type(text: \"user@example.com\", selector: \"#Email\") { time } typeMessage: type(selector: \"#Message\", text: \"Hello from Browserless!\") { time } subject: select(selector: \"select#Subject\", value: \"Support\") { selector } solve { time solved } }",
    "variables": {},
    "operationName": "FormExample"
  }'

The complete mutation including submitForm is shown in the BQL tab.

3. Check the output

The response is JSON confirming each mutation completed, including whether the CAPTCHA was solved:

{
  "data": {
    "goto": { "status": 200 },
    "typeEmail": { "time": 120 },
    "solve": { "time": 4200, "solved": true }
  }
}

JavaScript

View Full Code on GitHub

1. Send the request

const response = await fetch(
  'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `mutation FormExample {
        goto(url: "https://www.browserless.io/practice-form") {
          status
        }
        typeEmail: type(text: "user@example.com", selector: "#Email") {
          time
        }
        typeMessage: type(selector: "#Message", text: "Hello from Browserless!") {
          time
        }
        subject: select(selector: "select#Subject", value: "Support") {
          selector
        }
        solve {
          time
          solved
        }
        submitForm: click(selector: "button[type='submit']") {
          time
        }
      }`,
      variables: {},
      operationName: 'FormExample',
    }),
  }
);

const result = await response.json();
console.log(result);

2. Check the output

Run the script with node form.mjs. The response confirms each mutation completed and whether the CAPTCHA was solved.

Python

View Full Code on GitHub

1. Install dependencies

pip install requests

2. Send the request

import requests

endpoint = 'https://production-sfo.browserless.io/chromium/bql'
query_string = {'token': 'YOUR_API_TOKEN_HERE'}
headers = {'Content-Type': 'application/json'}
payload = {
    'query': """
mutation FormExample {
  goto(url: "https://www.browserless.io/practice-form") {
    status
  }
  typeEmail: type(text: "user@example.com", selector: "#Email") {
    time
  }
  typeMessage: type(selector: "#Message", text: "Hello from Browserless!") {
    time
  }
  subject: select(selector: "select#Subject", value: "Support") {
    selector
  }
  solve {
    time
    solved
  }
  submitForm: click(selector: "button[type='submit']") {
    time
  }
}
""",
    'variables': {},
    'operationName': 'FormExample',
}

response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())

3. Check the output

Run the script with python form.py. The response confirms each mutation completed, including CAPTCHA solving status.

Java

View Full Code on GitHub

1. Add dependencies

<!-- https://kong.github.io/unirest-java/ -->
<dependency>
  <groupId>com.konghq</groupId>
  <artifactId>unirest-java</artifactId>
  <version>3.14.5</version>
</dependency>

2. Send the request

import kong.unirest.HttpResponse;
import kong.unirest.Unirest;

String url = "https://production-sfo.browserless.io/chromium/bql";
String token = "YOUR_API_TOKEN_HERE";
String endpoint = String.format("%s?token=%s", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body("{\"query\":\"mutation FormExample {\\n  goto(url: \\\"https://www.browserless.io/practice-form\\\") {\\n    status\\n  }\\n\\n  typeEmail: type(text: \\\"user@example.com\\\", selector: \\\"#Email\\\") {\\n    time\\n  }\\n\\n  typeMessage: type(selector: \\\"#Message\\\", text: \\\"Hello from Browserless!\\\") {\\n    time\\n  }\\n\\n  subject: select(selector: \\\"select#Subject\\\", value: \\\"Support\\\") {\\n    selector\\n  }\\n\\n  solve {\\n    time\\n    solved\\n  }\\n\\n  submitForm: click(selector: \\\"button[type='submit']\\\") {\\n    time\\n  }\\n}\",\"variables\":\"\",\"operationName\":\"FormExample\"}")
    .asString();

System.out.println(response.getBody());

3. Check the output

Run the class. The response JSON confirms each mutation completed, including CAPTCHA solving status.

C#

View Full Code on GitHub

1. Send the request

using System.Net.Http;
using System.Text;
using System.Text.Json;

string url = "https://production-sfo.browserless.io/chromium/bql";
string token = "YOUR_API_TOKEN_HERE";
string endpoint = $"{url}?token={token}";

var payload = new
{
    query = @"mutation FormExample {
  goto(url: ""https://www.browserless.io/practice-form"") {
    status
  }

  typeEmail: type(text: ""user@example.com"", selector: ""#Email"") {
    time
  }

  typeMessage: type(selector: ""#Message"", text: ""Hello from Browserless!"") {
    time
  }

  subject: select(selector: ""select#Subject"", value: ""Support"") {
    selector
  }

  solve {
    time
    solved
  }

  submitForm: click(selector: ""button[type='submit']"") {
    time
  }
}",
    variables = "",
    operationName = "FormExample",
};

using (HttpClient httpClient = new HttpClient())
{
    var jsonPayload = JsonSerializer.Serialize(payload);
    var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");
    var response = await httpClient.PostAsync(endpoint, content);
    string responseBody = await response.Content.ReadAsStringAsync();
    Console.WriteLine(responseBody);
}

2. Check the output

Run the program. The response JSON confirms each mutation completed, including CAPTCHA solving status.

Frameworks

Use a browser connection to interact with the form: click, type, and wait for navigation.

Puppeteer

View Full Code on GitHub

1. Install dependencies

npm install puppeteer-core

2. Connect and interact

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io?token=YOUR_API_TOKEN_HERE',
});

try {
  const page = await browser.newPage();
  await page.goto('https://www.browserless.io/practice-form', {
    waitUntil: 'networkidle2',
  });

  await page.type('#Email', 'user@example.com');
  await page.type('#Message', 'Hello from Browserless!');
  await page.select('select#Subject', 'Support');
  await page.click("button[type='submit']");
  await page.waitForNavigation({ waitUntil: 'networkidle2' });

  console.log('Form submitted, current URL:', page.url());
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

3. Check the output

Run the script with node form.mjs. The script logs the URL after form submission.

Playwright

View Full Code on GitHub

1. Install dependencies

npm install playwright-core

2. Connect and interact

import { chromium } from 'playwright-core';

const browser = await chromium.connect(
  'wss://production-sfo.browserless.io/chromium/playwright?token=YOUR_API_TOKEN_HERE'
);

try {
  const page = await browser.newPage();
  await page.goto('https://www.browserless.io/practice-form', {
    waitUntil: 'networkidle',
  });

  await page.fill('#Email', 'user@example.com');
  await page.fill('#Message', 'Hello from Browserless!');
  await page.selectOption('select#Subject', 'Support');
  await page.click("button[type='submit']");
  await page.waitForLoadState('networkidle');

  console.log('Form submitted, current URL:', page.url());
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

3. Check the output

Run the script with node form.mjs. The script logs the URL after form submission.

BAP

1. Install dependencies

npm install @browserless.io/bap-ts

2. Connect and submit

import Browserless from '@browserless.io/bap-ts';

const browser = Browserless.connect({
  browserWSEndpoint: 'wss://production-sfo.browserless.io/chromium/bql',
  token: 'YOUR_API_TOKEN_HERE',
});

try {
  const page = await browser.newPage();
  await page.goto('https://www.browserless.io/practice-form');

  await page.type('#Email', 'user@example.com');
  await page.type('#Message', 'Hello from Browserless!');
  await page.select('select#Subject', 'Support');

  // Clears the CAPTCHA guarding the form before submitting.
  const { solved } = await page.solve();
  console.log({ solved });

  await page.click("button[type='submit']");
} finally {
  // Always close to release the session even on error.
  await browser.close();
}

3. Check the output

The form posts once the CAPTCHA is cleared, the same sequence the BQL tab runs.

BQL

View Full Code on GitHub

1. Write the mutation

Chain navigation, typing, selection, CAPTCHA solving, and clicking in a single query:

mutation FormExample {
  goto(url: "https://www.browserless.io/practice-form") {
    status
  }

  typeEmail: type(text: "user@example.com", selector: "#Email") {
    time
  }

  typeMessage: type(selector: "#Message", text: "Hello from Browserless!") {
    time
  }

  subject: select(selector: "select#Subject", value: "Support") {
    selector
  }

  solve {
    time
    solved
  }

  submitForm: click(selector: "button[type='submit']") {
    time
  }
}

2. Run it

Paste the mutation into the BQL IDE and click Run, or send via HTTP (see the cURL tab for the full request wrapper).

3. Check the output

The response confirms each step completed, including whether the CAPTCHA was solved:

{
  "data": {
    "goto": { "status": 200 },
    "typeEmail": { "time": 132 },
    "solve": { "time": 4200, "solved": true },
    "submitForm": { "time": 89 }
  }
}

Next steps

Authenticated Sessions

persist login state across requests

Take a Screenshot

capture a screenshot after form submission

Scrape Structured Data

extract data from the resulting page