BindRabbit Platform v1
API Documentation

BindRabbit Platform
REST API

Programmatically create quote intents via a simple, authenticated REST API.

Live
Version 1.0
JSON · HTTPS
Authentication
Every request must include headers identifying your integration and the merchant.
Authorization
<api_key>
Your integration partner API key. Passed as-is; hashed with SHA-256 server-side.
Merchant-App-Key
<merchant_app_key>
Identifies the merchant application. Used to find or create the merchant account.
Merchant-API-Key
<merchant_api_key>
The merchant's API key. Stored encrypted. Always updated to reflect the latest key.
Example Request Headers
Shell 
curl https://platform.bindrabbit.com/api/v1/quote_intents \
    -H "Authorization: sk_live_abc123..." \
    -H "Merchant-App-Key: app_abc123..." \
    -H "Merchant-API-Key: msk_xyz789..."
Security Note Never expose your API keys client-side. All requests should originate from your server. Keys are non-recoverable once generated.
Endpoints
Click an endpoint to expand request and response details.
POST /api/v1/quote_intents Create a Quote Intent ›

Creates a new quote intent associated with the authenticated integration partner and merchant. Returns a signed ID used in all subsequent requests.

No Request Body Required This endpoint requires only the three authentication headers. No JSON body needed.
Headers
Header Required Description
Authorization Required Your raw integration API key (no prefix)
Merchant-App-Key Required Identifies the merchant app. Used to find or create the merchant account.
Merchant-API-Key Required The merchant's API key. Stored encrypted; always updated to the latest value.
Response
201
Quote intent created. Returns a signed, time-limited ID.
JSON 
{ "quote_intent_id": "eyJfcmFpbHMiOns..." }
Field Type Description
quote_intent_id string Signed ID. Expires in 1 hour. Pass as "quote_intent_id" in JS embed.
401
Invalid or missing API credentials.
cURL Example
Shell 
curl -X POST https://platform.bindrabbit.com/api/v1/quote_intents \
    -H "Authorization: sk_live_abc123" \
    -H "Merchant-App-Key: app_abc123" \
    -H "Merchant-API-Key: msk_xyz789"
Embed Widget
A drop-in iframe widget that lets your users upload documents and receive a processed quote.
Installation
The widget is distributed as @bindrabbit/embed.
Early Access The embed package is not yet published to the public npm registry. Contact us to get access.
Shell 
npm install @bindrabbit/embed
Usage
The typical integration flow has two steps: your server creates a quote_intent_id, then your frontend passes it to the widget.
1
Server creates a Quote Intent
POST to /api/v1/quote_intents using your integration key and the merchant key. Returns a signed quote_intent_id.
2
Send the ID to your frontend
Embed the quote_intent_id in your page — as a data attribute, a JSON payload, or any other mechanism.
3
Initialize the widget
Call initializeDropzone() with the ID and a container element. The widget handles document upload and processing entirely inside an iframe — no API keys on the client.
4
Receive the result
Listen for the PROCESSING_COMPLETE event. The result field contains the processed quote_data object.
JavaScript 
  // Fetch the signed ID from your server
  const { quote_intent_id } = await fetch('/api/create-quote-intent').then(r => r.json());

  import { initializeDropzone } from '@bindrabbit/embed';

  const widget = initializeDropzone({
    quoteIntentId: quote_intent_id,
    container: '#bindrabbit-widget',
    onEvent(event) {
      if (event.type === 'PROCESSING_COMPLETE') {
        console.log('Quote data:', event.result);
      }
    },
  });

  // Clean up when done (e.g. on route change or modal close)
  // widget.destroy();
initializeDropzone() Options
Option Type Required Description
quoteIntentId string Required Signed ID from your server. Expires in 1 hour.
container string | HTMLElement Required CSS selector or DOM element to mount the widget into.
onEvent function Required Callback fired for every widget lifecycle event. See Events below.
theme object Optional { accentColor?: string } — CSS color for the widget's accent (border, button, spinner).
Return value — BindRabbitWidget
Method Description
destroy() Removes the iframe and cleans up all event listeners. Safe to call multiple times. Call on route changes or when the widget is no longer needed.
Events
Every widget lifecycle event is delivered to the onEvent callback. Handle what you need and ignore the rest.
Event type Extra fields Description
READY version: string Widget has mounted and is ready for interaction.
UPLOAD_PROGRESS percent: number Upload progress 0–100. Use to drive a custom progress indicator.
PROCESSING — Upload complete; documents are being analyzed.
PROCESSING_COMPLETE result: object Processing finished. result contains the quote_data object. This is the primary success signal.
PROCESSING_FAILED reason: string Processing could not complete. reason is a human-readable description.
ERROR code: string
message: string		 A widget-level error (e.g. invalid quoteIntentId, network failure).
Full event handler example
JavaScript 
  initializeDropzone({
    quoteIntentId: quote_intent_id,
    container: '#bindrabbit-widget',
    onEvent(event) {
      switch (event.type) {
        case 'READY':
          console.log('Widget ready, version', event.version);
          break;
        case 'UPLOAD_PROGRESS':
          setProgress(event.percent);
          break;
        case 'PROCESSING_COMPLETE':
          handleQuoteData(event.result);  // quote_data object
          break;
        case 'PROCESSING_FAILED':
          showError(event.reason);
          break;
        case 'ERROR':
          console.error(event.code, event.message);
          break;
      }
    },
  });
Error Handling
The API uses standard HTTP status codes. All error responses include a JSON body.
Status Meaning Common Cause
201 Created Resource successfully created.
400 Bad Request Missing required header (e.g. Merchant-API-Key).
401 Unauthorized Missing or invalid Authorization header.
422 Unprocessable Validation failed on the record.
500 Server Error Unexpected error. Contact support.
Error Response Shape
JSON 
{
  "error": "Unauthorized"
}