Public Lead-Capture API

i Before you start

This API lets your landing pages create leads in Green Zone's CRM without any direct database access. Integration takes three things from us and one thing from you.

1 Environments & base URLs

Test against DEV first, then switch the base URL to LIVE. Your credentials are issued per environment.

All paths below are relative to the base URL for your environment, e.g. POST https://staff.greenzonenatureayurveda.co.in/api/public/generateLead.

2 Credentials & access

Green Zone creates a partner record for you and issues your credentials. You cannot self-register — access is granted manually.

• Your api_key maps to a lead source in the CRM, so every lead is attributed to your account.
• Your key carries its own rate limits, de-dup window, allowed mode(s) (browser / server), and optional CAPTCHA — all configurable per partner.
• Keys are environment-specific: a DEV key will not work on LIVE and vice-versa.

3 Domain & IP allowlisting

Before you can send live traffic, we bind your key to the exact places it is allowed to call from. This is the "whitelist" step — tell us these values during onboarding.

A. Domain allowlist — for browser landing pages

Because a landing-page form runs in the visitor's browser (not on your server), the request's source is its web Origin — scheme + host + port. We allowlist the exact origins your form is served from; any other origin is rejected with 403 origin_not_allowed. Send us each one, e.g.:

https://land.example.com
https://www.example.com
https://offers.example.comCopy

B. Server IP allowlist — for server-to-server (HMAC) integrations

If you call us from your own server (server mode), give us the public egress IP address(es) of the machine(s) that host your backend. We bind them to your key and the API enforces it on every server-mode request: a signed call whose real client IP is not on the list is rejected with 403 ip_not_allowed — even before the signature is checked. Provide static IPs or IPv4 CIDR ranges, e.g.:

203.0.113.10
203.0.113.11
198.51.100.0/24Copy

4 Browser integration — recommended for landing pages

Add one script and mark your form. The snippet handles the anti-bot token, device fingerprint, honeypot and POST for you.

<!-- 1. Your form: add data-gzlead + data-key, name the inputs -->
<form data-gzlead data-key="pk_live_xxxxxxxx" data-campaign="fb-ad-thyroid">
  <input name="name"    required>
  <input name="phone"   required>
  <input name="email">
  <input name="pincode">
  <input name="city">
  <textarea name="message"></textarea>
  <button type="submit">Submit</button>
  <div data-gz-status></div>  <!-- success/error text lands here -->
</form>

<!-- 2. The snippet (loads from Green Zone's static host) -->
<script src="https://www.greenzonenatureayurveda.co.in/static/www/js/public/gzlead.js"></script>Copy

The snippet auto-adds a honeypot field, calls GET /formToken, computes a device fingerprint, and POSTs to /generateLead. Your page's exact origin must be on the key's domain allowlist (§3A).

5 Server integration (HMAC) — strongest

Call from your server and sign each request so the body can't be forged or replayed. No Origin, formToken, device id or honeypot needed.

Required headers

The exact string that is signed is: «timestamp»\n«nonce»\n«raw JSON body» — sign the byte-for-byte raw body you actually send.

Node.js example

const crypto = require("crypto");

const body = JSON.stringify({
  name:"Asha R", phone:"9876543210", email:"asha@example.com",
  pincode:"122001", city:"Gurugram", message:"Joint pain", campaign:"newsletter"
});
const ts    = Math.floor(Date.now()/1000).toString();
const nonce = crypto.randomBytes(12).toString("hex");
const sig   = crypto.createHmac("sha256", API_SECRET)
                    .update(ts+"\n"+nonce+"\n"+body).digest("hex");

await fetch("https://staff.greenzonenatureayurveda.co.in/api/public/generateLead", {
  method:"POST",
  headers:{ "Content-Type":"application/json", "X-Api-Key":API_KEY,
            "X-Timestamp":ts, "X-Nonce":nonce, "X-Signature":sig },
  body
});Copy

6 Request fields

JSON body for POST /generateLead. Only name and phone are mandatory.

GET /formToken (browser mode): returns a short-lived signed token enforcing a minimum fill time. Send header X-Api-Key; response is { "status":"SUCCESS", "token":"…" }. Token TTL is 30 minutes.

7 Responses & error codes

Always JSON. Success is HTTP 200; errors carry a stable machine-readable code.

Success — 200

{ "status":"SUCCESS", "code":"ok",
  "message":"Thank you. Your details have been received.",
  "reference":"GZ-1A2B3C4D5E" }Copy

Error shape

{ "status":"FAIL", "code":"origin_not_allowed",
  "message":"This origin is not allowlisted for this API key." }Copy

8 Sample requests / responses

Copy-ready pairs for each call, with sample data. These mirror the Postman collection below.

GET/formToken — browser

# Request
GET /api/public/formToken
X-Api-Key: pk_live_xxxxxxxxCopy

// 200 OK
{ "status":"SUCCESS", "token":"1731000000000.ab12cd34ef567890" }Copy

POST/generateLead — browser mode

# Request headers
Content-Type: application/json
X-Api-Key: pk_live_xxxxxxxx
Origin: https://land.example.com          # browser sends this automatically; must be allowlisted

# Request body
{
  "name":      "Asha R",
  "phone":     "9876543210",
  "email":     "asha@example.com",
  "pincode":   "122001",
  "city":      "Gurugram",
  "state":     "Haryana",
  "message":   "Interested in a consultation for joint pain",
  "campaign":  "fb-ad-thyroid",
  "pageUrl":   "https://land.example.com/thyroid",
  "deviceId":  "fp_9a8b7c6d5e",
  "formToken": "1731000000000.ab12cd34ef567890",
  "website":   ""
}Copy

// 200 OK
{ "status":"SUCCESS", "code":"ok",
  "message":"Thank you. Your details have been received.",
  "reference":"GZ-1A2B3C4D5E" }Copy

POST/generateLead — server mode (HMAC)

# Request headers
Content-Type: application/json
X-Api-Key:    pk_live_xxxxxxxx
X-Timestamp:  1731000000
X-Nonce:      3f9c1a7b2e6d4058
X-Signature:  9d4e...c0a2      # HMAC_SHA256(secret, ts + "\n" + nonce + "\n" + body)

# Request body
{
  "name":     "Ravi K",
  "phone":    "9123456780",
  "email":    "ravi@example.com",
  "city":     "Delhi",
  "message":  "Server-to-server signed lead",
  "campaign": "newsletter"
}Copy

// 200 OK
{ "status":"SUCCESS", "code":"ok",
  "message":"Thank you. Your details have been received.",
  "reference":"GZ-77H8J9K0L1" }Copy

Common error responses

// 401 — invalid API key
{ "status":"FAIL", "code":"invalid_api_key", "message":"Unknown or inactive API key." }

// 403 — origin not allowlisted (browser mode)
{ "status":"FAIL", "code":"origin_not_allowed", "message":"This origin is not allowlisted for this API key." }

// 403 — server IP not allowlisted (server/HMAC mode)
{ "status":"FAIL", "code":"ip_not_allowed", "message":"This IP address is not allowlisted for this API key." }

// 409 — duplicate within the de-dup window
{ "status":"FAIL", "code":"duplicate", "message":"This lead was already submitted recently." }

// 429 — rate limited (honour Retry-After header)
{ "status":"FAIL", "code":"rate_limited", "message":"Too many requests. Please retry later." }Copy

9 Postman collection

A ready-to-run collection with all calls — form token, browser lead, HMAC-signed server lead, and negative tests (bad key, bad origin, duplicate, honeypot). The server-mode request signs itself via a pre-request script.

⬇  Download Postman collection (.json)

1. Import the file into Postman (Import → File).
2. Open the collection's Variables and set: baseUrl (dev or live), apiKey, apiSecret (server mode), and origin (an allowlisted domain).
3. Run “Get form token”, then “Generate lead — BROWSER” or “Generate lead — SERVER (HMAC)”.
4. The negative-test requests confirm your key's guards (401 / 403 / 409) behave as expected.

10 Abuse protection (enforced for you)

• Per-key rate limits — per-minute / hour / day caps (defaults 10 / 100 / 500), tunable per partner.
• Per-IP limits + concurrency cap — bursts from one network are throttled and simultaneous in-flight requests per IP are capped (anti-flood). Shared/NAT IPs are not hard-blocked, so real customers behind one office/mobile IP still get through.
• Per-key server-IP allowlist — for server (HMAC) keys, calls are accepted only from your allowlisted egress IPs / CIDR blocks (§3B), enforced in-app (403 ip_not_allowed). Empty list = no restriction; never applied to browser traffic.
• Global ceiling — a hard cap across all partners protects the platform.
• Hard de-duplication — same phone, email or device within the window (default 24h) returns 409 duplicate; no second lead is created.
• Anti-bot without CAPTCHA — an invisible honeypot field plus a minimum-fill-time token silently stop most bots. CAPTCHA (reCAPTCHA / hCaptcha) can be switched on per key for an extra layer.
• Input sanitisation — all free-text is HTML/script-stripped before storage (no stored XSS).
• PII at rest — IP / phone / email / device are stored only as salted SHA-256 hashes in the audit ledger; raw values live solely on the lead record.

11 Onboarding checklist

1. Green Zone creates your partner record — api_key, api_secret, allowlisted domains & server IPs, limits.
2. Browser: add gzlead.js + data-key to your form; confirm each page's exact origin is on your domain allowlist (§3A).
3. Server: implement the HMAC signature (§5); keep api_secret on your server only; send us your egress IPs (§3B).
4. Test end-to-end against DEV using the Postman collection (§9).
5. Switch baseUrl to LIVE, go live, and watch leads land in the CRM (auto-assigned to an agent).

12 Support

To request access, allowlist changes, higher limits, or secret rotation, contact the Green Zone team.