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

POSThttps://recv.karnakreative.com/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 https://recv.karnakreative.com/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.

File Uploads & Attachments

Recv provides a secure and integrated file upload API that uploads attachments (like resumes, images, or PDFs) directly to your Cloudflare R2 bucket (`revc`), keeping them neatly organized inside folders named after each client.

How it works

Upload to Recv: In your form submission handler, send a `POST` request (`multipart/form-data`) containing your `apiKey` and the file payload to /api/upload.
Get File URL: The API verifies your key, groups the file in your client-specific folder (e.g. Client_Name/171928929-resume.pdf), uploads it securely to Cloudflare R2, and returns a public URL.
Submit Inquiry: Include this public URL string as a custom field (e.g. resume, screenshot) in your JSON body payload to /api/inquiries. Recv automatically renders it with a styled Download Attachment button in your dashboard.

Implementation Example

javascript

// 1. Upload file directly to Recv's secure storage API
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

const uploadData = new FormData();
uploadData.append('apiKey', 'YOUR_GLOBAL_API_KEY');
uploadData.append('file', file);

const uploadResponse = await fetch('https://recv.karnakreative.com/api/upload', {
  method: 'POST',
  body: uploadData
});
const { url: fileUrl } = await uploadResponse.json(); // e.g. "https://pub-...r2.dev/client-name/12345-resume.pdf"

// 2. Submit form payload (including the file URL) to Recv
const response = await fetch('https://recv.karnakreative.com/api/inquiries', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apiKey: 'YOUR_GLOBAL_API_KEY',
    formId: 'contact-form',
    name: 'Jane Doe',
    email: 'jane@example.com',
    resume: fileUrl // <-- Recv will auto-detect this URL and render a download link!
  })
});
const result = await response.json();

AI Integration Support

If you are building your form using an AI assistant, our copyable AI Integration Prompt below is pre-configured to instruct your assistant to generate file upload handlers and pass attachment URLs to the API.

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="https://recv.karnakreative.com/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:
1. File Upload Endpoint (Only if file input is present):
   - Endpoint URL: https://recv.karnakreative.com/api/upload
   - Method: POST
   - Content-Type: multipart/form-data
   - Payload Fields:
     - apiKey (string, required): "YOUR_GLOBAL_API_KEY"
     - file (File, required): The binary file to upload.
   - Response: JSON containing { success: true, url: "https://pub-...r2.dev/client/filename" }

2. Inquiry Capture Endpoint:
   - Endpoint URL: https://recv.karnakreative.com/api/inquiries
   - Method: POST
   - Content-Type: application/json
   - Payload Fields:
     - apiKey (string, required): "YOUR_GLOBAL_API_KEY"
     - formId (string, required): "YOUR_FORM_ID_OR_NAME"
     - company (string, optional honeypot): MUST remain empty to pass anti-spam checks.
     - Any other custom fields (e.g. name, email, phone, message, or the uploaded file/attachment URLs) which will be stored dynamically.

---
Requirements:
1. Render a clean contact form. Support basic fields (name, email, message) and optional fields (e.g. phone, file upload/attachments).
2. If file uploads are requested/needed:
   - Handle the file input selection.
   - When submitting, first upload the selected file to the File Upload Endpoint using FormData.
   - Show a loading/uploading status state while the file is uploading.
   - Retrieve the uploaded file's URL from the JSON response ('url' property).
   - Pass this file URL under a descriptive key (e.g. "resumeUrl", "screenshot", "attachment") in the main JSON payload sent to the Inquiry Capture Endpoint.
   - Ensure the user is notified of any upload failures.
3. Intercept the submission, disable the submit button, and show a loading spinner/state.
4. Include the hidden honeypot input (named "company") styled via CSS display: none.
5. Send the form payload as a JSON POST request to the Inquiry Capture Endpoint URL.
6. 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:
https://recv.karnakreative.com/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