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
NORMAL - Standard quality lead
SKIP - 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 easier integration with automatic PII hashing:

<!-- Include SDK -->
<script src="https://backnova.xyz/cdn/sdk.js"></script>

<script>
// Initialize
BackNova.init('bknv_your_api_key', { debug: true });

// Make decision (email is hashed automatically)
const result = await BackNova.decide({
  email: 'user@example.com',  // Hashed client-side!
  name: 'John Doe',
  country: 'US'
}, 'contact_form');

console.log(result.decision);  // HIGH, NORMAL, or SKIP
</script>

For full SDK documentation, see our SDK Guide.

Need Help?