Heroshhi Pro API Reference

Authentication

To use the API, you first need to log in and get a token. Then include that token in every request you make. Think of it like a session key that proves who you are.

// Login to receive a JWT token
POST https://api.heroshhi.com/api/auth/login
Content-Type: application/json

{
  "email": "admin@yourcompany.com",
  "password": "your_password"
}

// Response
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Rate Limits

To keep things fair and prevent abuse, there's a limit on how many requests you can make in a short time. If you hit the limit, you'll get a 429 Too Many Requests error — just wait a moment and try again.

Authentication Routes /api/auth

Lead Routes /api/leads

Message Routes /api/messages

WhatsApp Routes /api/whatsapp

Drip & Broadcast Routes

Webhook Integration Guide

Lead Ingestion Webhook

You can send leads into Heroshhi Pro from any external system (your website, a form builder, etc.) using this simple webhook. No login required — just send the data and the lead appears in your dashboard.

{
  "name":    "John Doe",
  "phone":   "919876543210",
  "email":   "john.doe@example.com",
  "source":  "Website Form",
  "inquiry": "Product inquiry",
  "userId":  "your_account_id"
}

Data Models

Lead Object

Message Object

Opt-Out Behaviour

All messaging endpoints automatically check whether a lead has opted out before sending. This keeps you compliant with Meta policies — you don't need to check manually.

What happens when you message an opted-out lead?

If you try to send a single message or template to a lead who has opted out, the API will block it and return this response:

{
  "success": false,
  "message": "Cannot send message - contact has opted out",
  "error": "OPT_OUT_BLOCKED"
}

Error Handling

When something goes wrong, the API always responds in the same format so your code can handle errors easily:

{
  "success": false,
  "message": "Error description",
  "error":   "Detailed error (development only)"
}

Security Implementation

Security Headers

The API automatically adds security headers to every response, protecting against common web attacks like cross-site scripting and clickjacking.

Input Validation

Everything you send to the API is automatically checked and cleaned to prevent hacking attempts — including code injection, malicious HTML, and other common attacks.

CORS Configuration

The API only accepts requests from the official Heroshhi Pro frontend. Webhook endpoints are the exception — they're open to receive events from Meta and other integrations.