Agent Integration

What You Need

An API key with a frk_ prefix (Bearer token). Sign up at forms.rizzness.com to create an account and generate an API key from your dashboard. API keys can be scoped with permissions: can_create_forms, can_read_submissions, and can_read_spam_submissions.

Step 1: Discover the API

The RizzForms API is HATEOAS-driven. Start at the root and follow the links it returns. Do not hardcode URLs beyond the root endpoint.

curl -H "Authorization: Bearer frk_YOUR_KEY" \ https://www.rizzness.com/api/  

The response includes hypermedia links to all available resources (forms, submissions, etc.). Follow these links to navigate the API.

Step 2: Create a Form

curl -X POST https://www.rizzness.com/api/forms \ -H "Authorization: Bearer frk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Contact Form"}'  

The response includes everything you need to integrate:

• endpoint_token — unique identifier for the form
• submission_url — HTML form action URL (/f/:token)
• json_url — JSON submission URL (/json/:token)
• embed_html — ready-to-use HTML form snippet
• examples — curl examples for testing

Step 3: Build the HTML Form

Use a standard HTML form pointing to the submission URL. HTML form POST works cross-origin with no CORS configuration needed.

<form action="https://forms.rizzness.com/f/YOUR_TOKEN" method="POST"> <!-- Honeypot field: must be hidden and empty --> <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off"> <label for="name">Name</label> <input type="text" id="name" name="name" required> <label for="email">Email</label> <input type="email" id="email" name="email" required> <label for="message">Message</label> <textarea id="message" name="message"></textarea> <button type="submit">Send</button> </form>  

The _hp honeypot field is critical for spam filtering. It must be hidden from users and left empty. Bots that fill it automatically will have their submissions flagged as spam.

Step 4: Test

Submit a test entry using the JSON endpoint. Append ?test=true to flag it as a test submission.

curl -X POST "https://forms.rizzness.com/json/YOUR_TOKEN?test=true" \ -H "Content-Type: application/json" \ -d '{"email": "[email protected]", "message": "Hello from agent"}'  

The response includes a deliveries array showing the result of each configured plugin (email, webhook, Slack, etc.), so you can confirm that the full pipeline works.

Step 5: Add Webhook (Optional)

Forward submissions to your own server by adding a webhook plugin:

curl -X POST https://www.rizzness.com/api/forms/YOUR_TOKEN/plugins \ -H "Authorization: Bearer frk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"plugin_type": "webhook", "config": {"url": "https://yoursite.com/webhook"}}'  

Webhook payloads include the form token, submission ID, timestamp, and all submitted fields. Verify authenticity with the X-RizzForms-Signature header. See the Webhooks guide for payload format and retry behavior.

Step 6: Add Address Autocomplete

Add Google Places address autocomplete to your form with one script tag. RizzForms handles the Google API key, session tokens, and billing. Your form token doubles as the autocomplete token.

Add the script tag and mark up your inputs with data-rizzforms-autocomplete attributes:

<form action="https://forms.rizzness.com/f/YOUR_TOKEN" method="POST"> <input type="text" name="_hp" style="display:none" tabindex="-1" autocomplete="off"> <input name="address" data-rizzforms-autocomplete="address" placeholder="Start typing an address..." /> <input name="city" data-rizzforms-autocomplete="city" /> <input name="state" data-rizzforms-autocomplete="state" /> <input name="zip" data-rizzforms-autocomplete="zip" /> <input type="email" name="email" required /> <textarea name="message"></textarea> <button type="submit">Submit</button> </form> <script src="https://forms.rizzness.com/autocomplete.js?token=YOUR_TOKEN"></script>  

When a user types in the address field, a dropdown of suggestions appears. Selecting one auto-fills city, state, and zip. The SDK finds related fields by matching data-rizzforms-autocomplete attributes within the same <form>.

For programmatic control (e.g. reading lat/lng coordinates), use the JavaScript SDK:

<script> var input = document.querySelector('[data-rizzforms-autocomplete="address"]'); var ac = new Places.Autocomplete(input, { country: "us" }); ac.on("select", function(place) { console.log(place.lat, place.lng); console.log(place.components); // { street, city, state, postalCode, country } }); </script>  

See the full Address Autocomplete reference for all events, options, and framework examples.

Step 7: Authorize Domains

The autocomplete proxy validates the Origin header on every request. If your form is embedded on a domain other than *.rizzness.com, you must add it to the allow list.

curl -X PATCH https://www.rizzness.com/api/forms/YOUR_TOKEN \ -H "Authorization: Bearer frk_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"allowed_domains": ["mysite.com", "www.mysite.com"]}'  

The allowed_domains array is returned in all form API responses. Pass the complete list on each update — it replaces the existing list.

Without this step, autocomplete requests from your domain will receive a 403 response. Form submissions (HTML POST) are unaffected — they work cross-origin without domain authorization.

Step 8: Custom Domain (Optional)

If you’re using a RizzForms-hosted page and want it served from your own domain (e.g. contact.mysite.com), set up a custom domain through the dashboard:

1. Open your page in the dashboard and click Custom Domain.
2. Enter your hostname (e.g. contact.mysite.com).
3. Add the DNS records at your registrar:
   • TXT record — for ownership verification (name and value shown in dashboard)
   • CNAME — point to sites.rizzness.com
4. SSL is provisioned automatically. The status page refreshes every 30 seconds.

Once active, your page with autocomplete is live at your custom domain. Form submissions and autocomplete both work on the custom domain — just make sure the domain is in your allowed domains list.

Special Fields

RizzForms recognizes certain field names and processes them automatically. See the full reference at Special Fields. Key fields:

• _hp — honeypot field (must be hidden and empty)
• email — sender email, used for notifications and deduplication
• firstName, lastName — contact name fields
• tags — comma-separated tags for categorization
• priority — submission priority level

All other fields are captured as-is. RizzForms accepts any field names you send.

Agent Feedback

After completing the integration, produce a structured feedback report. This helps the RizzForms team improve the developer and agent experience.

## RizzForms Integration Feedback **Agent:** [Claude / GPT / Codex / Gemini / Other] **Date:** [YYYY-MM-DD] **Project type:** [e.g., Next.js marketing site, Hugo blog, etc.] ### Ratings (1-10) - Ease of setup: [score] - API clarity: [score] - Error message helpfulness: [score] ### What went well - [bullet points] ### What was confusing or difficult - [bullet points] ### Suggestions for improvement - [bullet points]  

Share this feedback by submitting it to a RizzForms form, opening a support ticket, or including it in your project documentation for the human developer to review.