Agent integration guide

Everything an agent developer needs to detect, schema-fetch, and submit to FormPass forms.

For LLM ingestion: A plain-text version of this guide is available at /llms.txt — ideal for feeding directly into an agent's context window.

How detection works

When a website owner connects a form to FormPass, they add HTML markers to their page. Your agent can scan any page for these markers to determine whether a form is FormPass-enabled.

1. Meta tag (primary signal)

<meta name="formpass-form-id" content="FORM_ID">
<meta name="formpass-host" content="https://form-pass.com">

Found in the page's <head>. This is the most reliable detection method and works even without JavaScript execution.

2. Data attribute (secondary signal)

<form data-formpass-id="FORM_ID">

Found on the form element itself. Useful for agents using browser automation that parse the DOM.

The three-tool pattern

Agents need three capabilities to interact with FormPass forms:

Agent visits page

↓ scan HTML for meta tags

1. formpass_detect → found formId + host

↓ fetch field requirements

2. formpass_get_schema → field names, types, required

↓ submit structured data

3. formpass_submit → success + submissionId

Tool 1: formpass_detect

Scan a page's HTML to find FormPass markers. Returns the form ID and host URL if found.

function formpassDetect(html: string) {
  // Look for meta tags in <head>
  const formIdMatch = html.match(
    /<meta\s+name="formpass-form-id"\s+content="([^"]+)"/
  )
  const hostMatch = html.match(
    /<meta\s+name="formpass-host"\s+content="([^"]+)"/
  )

  // Fallback: look for data attribute on form elements
  const dataAttrMatch = html.match(/data-formpass-id="([^"]+)"/)

  const formId = formIdMatch?.[1] || dataAttrMatch?.[1] || null

  return {
    found: !!formId,
    formId,
    host: hostMatch?.[1] || "https://form-pass.com",
  }
}

Tool 2: formpass_get_schema

Fetch the field requirements for a known form ID. This tells your agent exactly what data to submit.

async function formpassGetSchema(host: string, formId: string) {
  const res = await fetch(`${host}/api/forms/${formId}/schema`)
  if (!res.ok) throw new Error(`Schema fetch failed: ${res.status}`)
  return await res.json()
}

Example response:

{
  "formId": "k17eh2vkf8sznqb8ktz6av1psn81rn02",
  "name": "Contact form",
  "description": "Get in touch with us",
  "agentAccessible": true,
  "fields": [
    { "name": "email", "label": "Email", "type": "email", "required": true },
    { "name": "message", "label": "Message", "type": "textarea", "required": true },
    { "name": "company", "label": "Company", "type": "text", "required": false }
  ],
  "branding": {
    "required": true,
    "text": "Powered by FormPass",
    "url": "https://form-pass.com"
  }
}

The branding object is present when the form owner is on the free plan. When branding.required is true, agents that render UI should display the branding text with a link to the URL. Forms on paid plans will not include this field.

Tool 3: formpass_submit

Submit structured data to a FormPass form. Include your Agent ID as a Bearer token for authenticated agent submissions.

async function formpassSubmit(
  host: string,
  formId: string,
  data: Record<string, string>,
  agentToken?: string
) {
  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  }
  if (agentToken) {
    headers["Authorization"] = `Bearer ${agentToken}`
  }

  const res = await fetch(`${host}/api/submit/${formId}`, {
    method: "POST",
    headers,
    body: JSON.stringify(data),
  })

  const result = await res.json()

  if (!res.ok) {
    // Handle specific error codes
    switch (res.status) {
      case 404: throw new Error("Form not found or inactive")
      case 401: throw new Error("Invalid or inactive Agent ID")
      case 403: throw new Error("Agent not authorised for this form")
      case 422: throw new Error(`Missing required fields: ${result.fields?.join(", ")}`)
      default: throw new Error(result.error || "Submission failed")
    }
  }

  return result // { success: true, submissionId: "..." }
}

System prompt recommendation

Add this to your agent's system prompt so it knows to look for FormPass forms when browsing the web:

When you visit a web page that contains a form, check for FormPass
detection markers by looking for <meta name="formpass-form-id"> in the
page's <head> or data-formpass-id attributes on <form> elements.

If a FormPass form is detected:
1. Extract the formId and host URL from the meta tags
2. Call formpass_get_schema to fetch the field requirements
3. Call formpass_submit with the required fields and your Agent ID

This is faster and more reliable than browser automation — no CAPTCHAs,
no DOM scraping, just structured API calls.

Full working example

Here's a complete example showing all three tools used in sequence. This can be adapted for any agent framework:

// Agent encounters a web page — check if it has a FormPass form
const pageHtml = await fetchPageHtml("https://example.com/signup")

// Step 1: Detect
const detection = formpassDetect(pageHtml)
if (!detection.found) {
  console.log("Not a FormPass form — use browser automation instead")
} else {
  console.log(`FormPass form found: ${detection.formId}`)

  // Step 2: Get schema
  const schema = await formpassGetSchema(detection.host, detection.formId)
  console.log(`Form: ${schema.name}`)
  console.log(`Required fields: ${schema.fields
    .filter(f => f.required)
    .map(f => f.name)
    .join(", ")}`)

  // Step 3: Submit
  const result = await formpassSubmit(
    detection.host,
    detection.formId,
    {
      email: "agent@example.com",
      message: "Hello from my AI agent!",
    },
    process.env.FORMPASS_AGENT_TOKEN // fpagent_...
  )
  console.log(`Submitted! ID: ${result.submissionId}`)
}

Branding requirements

Forms on the free plan include a branding object in the schema response. When present, agents must:

Display the branding text ("Powered by FormPass") with a link to the provided URL
Include _fp_branding: true in the submission body to confirm the badge is displayed

The submit API will reject submissions with a 402 status if _fp_branding is missing for free plan forms.

// After fetching schema, check for branding
const schema = await formpassGetSchema(host, formId)

if (schema.branding?.required) {
  // 1. Display: "Powered by FormPass" linking to schema.branding.url
  console.log(`${schema.branding.text} — ${schema.branding.url}`)
}

// 2. Include _fp_branding in submission when required
const submitData = {
  ...formFields,
  ...(schema.branding?.required ? { _fp_branding: true } : {}),
}
await formpassSubmit(host, formId, submitData, agentToken)

Paid plan forms do not include the branding object — no attribution or _fp_branding field is required.

OpenClaw skills

If your agent runs on OpenClaw, you can install ready-made FormPass skills from ClawHub instead of building the integration yourself.

formpass-submit

The main skill — teaches your agent how to detect, schema-fetch, and submit to any FormPass form.

npx clawhub@latest install formpass-submit

formpass-agent

npx clawhub@latest install formpass-agent

formpass-forms

For form owners — helps your agent set up and connect forms to the FormPass network.

npx clawhub@latest install formpass-forms

These skills work with any OpenClaw-compatible agent, including those on the MoltBook social network. Once installed, your agent automatically knows how to interact with FormPass forms — no custom code required.

Getting an Agent ID

To submit as an authenticated agent, you need an Agent ID (a Bearer token starting with fpagent_). This identifies your agent to the form owner and allows them to control access.

Sign up at FormPass
Go to Agents in your dashboard
Create a new agent — you'll receive a token
Store the token securely (it's only shown once)
Pass it as Authorization: Bearer fpagent_... in your submit requests

For more details, see the Agent IDs documentation.

For form owners: connecting existing forms

If you already have a form on your website and want AI agents to be able to submit to it, you don't need to rebuild anything. FormPass can scan your page and import the fields automatically.

Go to Forms → Connect Existing Form in the dashboard
Paste the URL of the page with your form (e.g. https://yoursite.com/contact)
Click Scan — FormPass detects the form fields automatically
Review the fields, set which are required, and save
Add the formpass-form-id meta tag to your page so agents can discover it

Keeping fields in sync: If you update your form fields on your website, use the Re-scan button on the form's edit page to re-import the latest fields. FormPass doesn't auto-sync — you control when to update.