API / VERSION 1.0

API Documentation

Privacy-first lead decisioning API for real-time quality scoring

🔒 Privacy First

All PII (email, phone) is hashed client-side using SHA-256 before transmission. We never receive or store plain text personal information.

Overview

BackNova API provides real-time lead quality decisioning through a simple REST API. Make intelligent routing decisions before leads enter your CRM.

Base URL

https://api.backnova.xyz/api/v1

Key Features

Real-time Decisions: Sub-20ms response times
Privacy-First: Client-side PII hashing
Simple Integration: RESTful API + JavaScript SDK
Outcome Tracking: Close the feedback loop

Authentication

All API requests require authentication using your API key. Include it in the request headers:

X-API-Key: bknv_your_api_key_here

Your API key can be found in your dashboard at backnova.xyz/dashboard

⚠️ Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables in production.

Quick Start

Here's a minimal example to get you started:

// Make a decision request
fetch('https://api.backnova.xyz/api/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'bknv_your_api_key_here'
  },
  body: JSON.stringify({
    event_id: 'lead_' + Date.now(),
    source: 'contact_form',
    signals: {
      fingerprint_email: '031f692d75...', // SHA-256 hash
      time_on_page: 45,
      scroll_depth: 80
    }
  })
})
.then(res => res.json())
.then(data => {
  console.log('Decision:', data.decision);
  console.log('Confidence:', data.confidence);
});

Make Decision

Evaluate lead quality in real-time and get routing recommendations.

POST /events

Request Body

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique identifier for this event
`source`	string	Yes	Traffic source identifier
`signals`	object	Yes	Lead quality signals (see below)

Signals Object

Signal	Type	Description
`fingerprint_email`	string	SHA-256 hash of email (lowercase, trimmed)
`fingerprint_phone`	string	SHA-256 hash of phone (digits only)
`browser_fingerprint`	string	Composite browser fingerprint hash
`time_on_page`	number	Seconds spent on page
`scroll_depth`	number	Scroll depth percentage (0-100)
`utm_source`	string	UTM source parameter
`utm_medium`	string	UTM medium parameter
`utm_campaign`	string	UTM campaign parameter

Response

{
  "event_id": "lead_1734620845123",
  "decision": "HIGH",
  "confidence": 0.87,
  "latency_ms": 12
}

Decision Values

HIGH - High quality lead, prioritize routing
MEDIUM - Standard quality lead
LOW - Low quality lead, consider filtering

Report Outcome

Report the outcome of a lead to improve future decisions.

POST /outcomes

Request Body

Parameter	Type	Required	Description
`event_id`	string	Yes	Original event_id from decision
`outcome`	string	Yes	Final outcome (see values below)
`metadata`	object	No	Additional outcome data

Outcome Values

approved - Lead was approved/accepted
rejected - Lead was rejected
converted - Lead converted to customer
fraud - Lead flagged as fraudulent

Example

fetch('https://api.backnova.xyz/api/v1/outcomes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'bknv_your_api_key_here'
  },
  body: JSON.stringify({
    event_id: 'lead_1734620845123',
    outcome: 'converted',
    metadata: {
      revenue: 99.99,
      product: 'premium'
    }
  })
});

Get Stats

Retrieve your usage statistics and decision metrics.

GET /stats

Response

{
  "period": "current_month",
  "decisions_made": 1247,
  "decisions_remaining": 3753,
  "quota": 5000,
  "accuracy": 0.89,
  "avg_latency_ms": 14
}

Rate Limits

API rate limits vary by plan:

Plan	Decisions/Month	Rate Limit
Solo	5,000	100 requests/minute
Team	25,000	500 requests/minute
Network	Unlimited	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1734621600

Error Codes

BackNova uses standard HTTP response codes:

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error, please retry

Error Response Format

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "status": 401
}

JavaScript SDK

Use our JavaScript SDK for automatic collection of all 47 behavioral signals with built-in PII hashing:

Installation

<!-- Add before </body> -->
<script src="https://backnova.xyz/cdn/sdk.js" data-key="YOUR_API_KEY"></script>

That's it! SDK automatically tracks:

15 behavioral signals (time, scroll, clicks, mouse, form interactions...)
10 technical signals (device, browser, screen, timezone...)
7 traffic signals (UTM params, referrer, click_id...)
3 identity signals (hashed email, phone, browser fingerprint)

Basic Usage

<script>
// Option 1: Attach to form (simplest)
BackNova.attachToForm('#leadForm', 'my_campaign');

// Option 2: Manual decision
document.getElementById('leadForm').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const formData = new FormData(e.target);
  
  // Email/phone are hashed automatically client-side!
  const result = await BackNova.decide({
    email: formData.get('email'),
    phone: formData.get('phone')
  }, 'my_campaign');
  
  console.log(result.decision);  // HIGH, MEDIUM, or LOW
  console.log(result.routeUrl);  // Where to send the lead
  
  if (result.routeUrl) {
    window.location.href = result.routeUrl;
  }
});
</script>

Debug Mode

<script src="https://backnova.xyz/cdn/sdk.js" data-key="YOUR_API_KEY" data-debug></script>

Opens console logs showing all collected signals.

PII-0 Compliance

SDK is fully PII-0 compliant — BackNova never sees your lead data:

Email → SHA-256 hash sent to BackNova (for AI learning)
Phone → SHA-256 hash sent to BackNova (for AI learning)
Name, Email, Phone → Go directly to your PP via routeUrl (not to BackNova)

See Data Transparency for full details.

Need Help?