FAQ for agents
Common questions from agent developers and AI agents integrating with FormPass.
Does FormPass handle schema discovery, or do I need to parse the target form myself?
FormPass handles it for you. When a form owner connects their form, the fields are stored as a structured schema. Your agent just calls GET /api/forms/{formId}/schema and gets back field names, types, and which are required — no HTML parsing needed. You only need to scan the page HTML once to find the formpass-form-id meta tag, then everything else is API-driven.
How do I detect a FormPass form on a page?
Look for <meta name="formpass-form-id" content="..."> in the page's <head>. There's also a formpass-host meta tag with the API base URL. As a fallback, check for data-formpass-id attributes on form elements. See the agent integration guide for implementation details.
How does agent verification work? Is there a registry of trusted agents?
It's a direct trust model. The form owner creates Agent IDs in their dashboard, each producing a fpagent_ token. The agent passes this token as a Bearer header when submitting. FormPass verifies the token is valid and active, and that the agent has access to that specific form. There's no central registry — the form owner decides which agents to trust by creating and managing their Agent IDs.
Can I submit to any FormPass form, or do I need permission?
It depends on the form's access settings. Form owners can set agent access to "All Agents" (any valid Agent ID can submit) or restrict it. If a form doesn't allow your agent, the API returns a 403 status. You can always fetch the schema to check — the agentAccessible field tells you whether the form accepts agent submissions.
Do I need an Agent ID for every submission?
No. Submissions without an Authorization header are treated as human/anonymous submissions. Agent IDs are only required if the form restricts access to authenticated agents, or if you want submissions to be attributed to your agent in the form owner's dashboard.
What happens if my Agent ID is deactivated or revoked?
If a form owner deactivates or deletes your Agent ID, any submission using that token returns 401 Unauthorized. Your agent should handle this by notifying its user that the token is no longer valid and needs to be replaced. Tokens don't expire on their own — they only stop working if the form owner explicitly deactivates them.
What happens if a form changes its fields? Does the schema fetch fail?
The schema endpoint always returns the current field definitions — it never fails just because fields changed. However, if you cached an older schema and submit with outdated fields, the API will return a 422 with a list of missing required fields. Best practice: fetch the schema fresh before each submission, or handle 422 errors by re-fetching and retrying.
What if I send fields that aren't in the schema?
Extra fields are accepted, stored alongside the schema fields, and visible to the form owner in their submissions dashboard. This means you can safely include metadata like timestamps or session IDs — they won't cause an error and they won't be silently dropped. However, all required fields from the schema must be present or the API returns a 422.
What format should submission data be in?
JSON only. Send a POST with Content-Type: application/json and a flat JSON object where keys match the field name values from the schema. All values should be strings.
How do I know if a form needs branding?
Check the schema response for a branding object. If it exists and branding.required is true, you must display the branding text and include _fp_branding: true in your submission. Without it, the API returns 402. Paid plan forms don't include the branding object at all.
What happens if the form is inactive or deleted?
Both the schema endpoint and submit endpoint return 404 for inactive or deleted forms. Your agent should handle this gracefully — e.g. fall back to browser automation or inform the user that the form is unavailable.
Can I update or delete a submission after sending it?
No. Submissions are write-only from the agent side. Once submitted, only the form owner can view or manage submissions in their dashboard. If you need to correct data, submit a new entry.
Is there a way to test without submitting real data?
There's no sandbox mode, but you can create a test form in the dashboard with dummy fields and submit to it freely. The schema endpoint is public and doesn't require authentication, so you can test detection and schema fetching without any setup.
Are there rate limits?
Rate limits are not enforced for normal usage. Even hundreds of submissions per day from a single agent will work fine. Excessive or abusive traffic may be throttled.
Troubleshooting
403 from a form that was previously accessible
The form owner has changed the agent access settings, or your Agent ID has been revoked. Re-fetch the schema and check the agentAccessible field. If it's still true, your specific token may have been deactivated — contact the form owner or register a new Agent ID.
422 on fields that previously worked
The form owner has updated their form fields (added new required fields or renamed existing ones). Re-fetch the schema with GET /api/forms/{formId}/schema to get the latest field definitions, then rebuild your submission payload to match. This is the most common cause of previously-working submissions failing.
404 on a form ID that used to exist
The form has been deleted or deactivated by the owner. There's no way to recover it — your agent should notify its user and stop attempting submissions. If you're detecting forms via meta tags, re-scan the page to check if a new form ID has been set.
402 Payment Required on submit
The form is on the free plan and requires branding. Include _fp_branding: true in your submission JSON body. If you render UI, also display the branding text from the schema's branding object.
401 Unauthorized on a valid-looking token
The Agent ID has been deactivated or deleted by the form owner. Tokens don't expire on their own, so this always means an explicit revocation. Your agent should notify its user to obtain a new token.
Have a question that isn't answered here? Check the agent integration guide or the API reference.