Getting started

To get started with custom form integrations, retrieve your client's global API Key and Form ID. Once a client is created, a single global API Key is generated and forms can be created dynamically or registered automatically upon submission.

Find Your API Key & Form ID

Navigate to the Settings panel inside your dashboard to copy your Global API Key. Use the Forms overview section under Forms to manage your Form IDs (UUIDs) or configure new target endpoints.

Authentication

Every submission is authenticated via a client-level global API key. The keys validate the request and map incoming payloads to the correct client account. Submissions are associated with a specific form via the formId body property.

Security Recommendation

Since the API key is passed in browser code (or script elements), we recommend configuring Authorized Websites Whitelisting inside your client settings dashboard. When domain whitelisting is active, our server rejects payloads sent from unauthorized host domains.

Send an inquiry

To log an inquiry directly from your custom form handling scripts without dropping in our embed widget, post a standard JSON payload to our API endpoint.

Endpoint

POSThttp://localhost:3000/api/inquiries

Request Body Parameters

Field	Type	Required	Description
apiKey	string	Required	Your client-level global API key token.
formId	string	Required	The Form ID (UUID) or custom form name identifier.
company	string	Optional	Honeypot field. Must remain empty to pass anti-spam verification checks.
* (custom)	any	Optional	Any additional custom fields (e.g. `name`, `email`, `message`, `phone`) are serialized dynamically into the submission record.

Code Examples

bash

curl -X POST http://localhost:3000/api/inquiries \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_GLOBAL_API_KEY",
    "formId": "contact-form",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "Hello, I am interested in your services."
  }'

Interactive Console

Try it

Test the inquiry API in real-time. This request triggers full validation but will not write to your database or impact your stats.

Response format

Our API returns a standardized JSON payload structure reflecting request outcomes. Correct payloads return a success identifier, whereas rejected requests detail the error message.

Success Response (200 OK)

json

{
  "success": true
}

Error Response (4xx)

json

{
  "error": "Unauthorized: Invalid API Key"
}

Error codes

Below are the standard HTTP status codes returned by the /api/inquiries endpoint during authentication failures or malformed posts:

Status Code	Error Badge	Meaning / Cause
400 Bad Request	Validation Error	Missing required parameters (`apiKey`, `name`, `email`) or the honeypot spam `company` field was triggered.
401 Unauthorized	Authentication Error	The API key supplied does not match any registered client profile, or the site origin fails Authorized Website Whitelist CORS restrictions.
429 Too Many Requests	Rate Limit	The source IP has exceeded the allowed submissions thresholds (5 requests per minute).

Widget embed

If you prefer not to write form handling code manually, you can load our tracking script. When loaded, it hooks into standard submit triggers automatically.

Script Tag

html

<script 
  src="http://localhost:3000/api/embed.js" 
  data-api-key="YOUR_GLOBAL_API_KEY" 
  async
></script>

Simply drop this script tag anywhere on your website page. The script automatically looks for forms targeting standard name/email attributes and intercepts submit callbacks. You can customize the target Form ID by adding a data-form-id attribute to your HTML <form> element (defaults to the form's HTML id attribute, data-form-name attribute, or "default").

AI Integration Prompt

Are you a "vibe coder" or building custom frontends using AI assistants like ChatGPT, Claude, or Gemini? Use our dynamic integration prompt below. Instead of coding from scratch, copy this prompt, paste it into your AI assistant, and specify your desired framework to get a fully working, secure form component immediately.

Quick Instructions for Vibe Coders

Before pasting the prompt into your AI, make sure you configure your credentials:

Get your API Key: Navigate to the Settings tab in your dashboard and copy your secret token.
Get your Form ID: Navigate to the Forms overview, where you can copy the specific Form ID (UUID) for the form you want to route submissions to.
Auto-Inject Credentials: Tip: Enter your API Key and Form ID in the Try It console above, and they will be automatically injected into the copyable prompt below!
Specify your Stack: In your AI assistant chat, change the placeholder [SPECIFY YOUR TARGET FRAMEWORK HERE] in the prompt to match your project (e.g. "React + Tailwind CSS", "HTML + Vanilla JS + CSS", or "Next.js App Router") so the AI knows exactly what to write.

AI System Prompt (Dynamic Credentials)

markdown

You are an expert frontend developer AI. Generate a copy-pasteable form component for my website integrating with Recv's API.

I want you to build this form component.
My desired tech stack/framework is: [SPECIFY YOUR TARGET FRAMEWORK HERE, e.g. React & Tailwind, Next.js, HTML/JS/CSS, Vue, Svelte, etc.]

Please implement the form following the details below:

---
API Specifications:
- Endpoint URL: http://localhost:3000/api/inquiries
- Method: POST
- Content-Type: application/json
- Payload Fields:
  1. apiKey (string, required): "YOUR_GLOBAL_API_KEY"
  2. formId (string, required): "YOUR_FORM_ID_OR_NAME"
  3. company (string, optional honeypot): MUST remain empty to pass anti-spam checks.
  4. Any other custom input fields (e.g. name, email, phone, message) which will be stored dynamically.

---
Requirements:
1. Render a clean contact form with fields for name, email, and message.
2. Intercept the submission, disable the submit button, and show a loading spinner/state.
3. Include the hidden honeypot input (named "company") styled via CSS display: none.
4. Send the form payload as a JSON POST request to the endpoint URL.
5. Display a styled success banner or error banner based on the response success outcome.

---
Additional Context:
For reference, the full API documentation, response formats, and error codes can be accessed at:
http://localhost:3000/docs

Ready to paste directly into ChatGPT, Claude 3.5, or GeminiIncludes API & Documentation Reference Links

Rate limits

Our service implements network boundaries to guard database integrity and secure systems from DDoS attacks.

API Rate Limits Configuration

Enforced system-wide across all incoming widget scripts and client integrations.

API submissions are restricted to 5 requests per minute per IP address. Requests exceeding this threshold receive a 429 Too Many Requests status code and a standard error payload. Limits reset automatically at the end of each minute interval.

API Documentation