Official Pilot Documentation

BBIE Institutional
API Specification

Welcome to the Bharat Business Intelligence Engine (BBIE) Pilot Program API documentation. This specification provides deep architectural, schematic, and cryptographic guidelines for integrating national-scale identity resolution into your institutional workflows.

3072-Dim AI Matching

Advanced vector embeddings resolve fuzzy, fragmented multi-lingual business names instantly.

Sovereignty Buffer

Zero-knowledge matching ensures raw PII is never stored or exposed during verification.

Golden Record Issuance

Generates a permanent, unified Unique Bharat Business ID (UBID) across 15+ registries.

Architectural Vision & Workflow

The BBIE platform operates as an institutional middleware layer sitting between fragmented state/central registries (MCA, GSTN, EPFO, CIN) and consuming entities (Banks, Regulators, Ministries).

The 5-Stage Zero-Trust Resolution Pipeline

STAGE 01

Ingestion & Buffer

Unstructured fragments enter the isolated sovereignty buffer.

STAGE 02

Cryptographic Hash

Identifiers are converted to SHA-256 tokens instantly.

STAGE 03

Vector Search

Semantic matching across 3072-dim AI space.

STAGE 04

Spatial Anchor

Geospatial verification using 6-digit PIN codes.

STAGE 05

Golden Dossier

Issuance of permanent UBID with full audit timeline.

Authentication & Security Enclave

BBIE requires strict mutual authentication for all institutional access. Vetted pilot participants are issued a high-entropy **Service Role API Key** alongside an Institutional Identifier.

Mandatory HTTP Headers

AuthorizationBearer <INSTITUTIONAL_API_KEY>

X-BBIE-CLIENT-IDPILOT_DEPT_CODE (e.g., `PILOT_RBI_01`)

X-SOVEREIGNTY-MODE`FULL_MASK` | `PARTIAL_MASK` | `PLAIN_AUDIT`

X-TIMESTAMPISO-8601 UTC Timestamp (e.g., `2026-05-16T10:30:00Z`)

HMAC Signature Verification (Tier-1 Institutions)

For financial regulators and core banking systems, requests must include an `X-BBIE-SIGNATURE` header containing an HMAC-SHA256 signature of the request body using your institutional private secret.

Rate Limits & Volumetric Tiers

To prevent denial-of-service and guarantee SLA uptime for national infrastructure, volumetric controls are enforced at the API gateway layer using token bucket algorithms.

Tier 1: Standard Pilot

5,000 req/min

Suitable for asynchronous batch verification and departmental onboarding.

Active Pilot

Tier 2: High-Priority Enclave

50,000 req/min

Assigned to active pilot judges, core fintech partners, and real-time loan origination systems.

Tier 3: Sovereign Instance

Unlimited

Dedicated bare-metal deployment for central intelligence and national security agencies.

POST

Identity Resolution Endpoint

POSThttps://api.bbie.gov.in/v1/resolve

Submits unverified, fragmented business data into the BBIE Confidence Engine. The engine evaluates semantic similarity, cross-references historical registry collisions, and returns a high-confidence UBID match.

Request Body Schema (application/json)

Parameter	Type	Requirement	Description
entity_name	string	Required	The legal or trade name of the business entity (e.g., `Mphasis Ltd` or `Mphasis`).
pincode	string	Recommended	6-digit Indian Postal Code. Acts as the primary spatial anchor to prevent name collisions.
pan	string	Optional	10-character alphanumeric Permanent Account Number (e.g., `BLRMP1234F`).
gstin	string	Optional	15-character Goods and Services Tax Identification Number.
address	string	Optional	Unstructured physical address snippet for fuzzy spatial clustering.
cin	string	Optional	21-character Corporate Identification Number (MCA Registry).
fuzzy_threshold	number	Optional	Custom AI matching strictness between `0.0` and `1.0`. Defaults to `0.85`.
sovereignty_mask	boolean	Optional	If `true`, returns fully hashed PII tokens to comply with zero-knowledge policies. Defaults to `true`.

Success Response Payload (200 OK)

{
  "status": "success",
  "code": 200,
  "resolution": {
    "ubid": "KA-UBID-SLIY-54321",
    "confidence_score": 0.982,
    "match_type": "EXACT_AI_CLUSTER",
    "spatial_anchor_verified": true,
    "sovereignty_protected": true
  },
  "entity": {
    "legal_name": "MPHASIS LIMITED",
    "trade_name": "Mphasis",
    "status": "ACTIVE",
    "pincode": "560001",
    "state": "Karnataka",
    "pii_hashes": {
      "pan_sha256": "8f9e2a1c...[REDACTED]",
      "gstin_sha256": "4b3a1f9e...[REDACTED]"
    }
  },
  "forensic_metadata": {
    "engine_version": "v2.4-pilot",
    "latency_ms": 42,
    "timestamp": "2026-05-16T10:30:05Z"
  }
}

GET

Dossier Retrieval Endpoint

GEThttps://api.bbie.gov.in/v1/business/:ubid

Fetches the comprehensive Golden Record and forensic resolution history for a specific Unique Bharat Business ID (UBID). Used for underwriting, regulatory audits, and deep compliance checks.

Query Parameters

Parameter	Type	Requirement	Description
ubid	string	Required	The Unique Bharat Business ID (e.g., `KA-UBID-SLIY-54321`). Passed in URL path.
include_audit	boolean	Optional	If `true`, attaches the full historical timeline of resolution merges and human reviews.
depth	enum	Optional	`SUMMARY` \| `STANDARD` \| `EXHAUSTIVE`. Determines the volume of cross-registry data returned.

Success Response Payload (200 OK)

{
  "status": "success",
  "ubid": "KA-UBID-SLIY-54321",
  "dossier": {
    "golden_record": {
      "company_name": "MPHASIS LIMITED",
      "incorporation_date": "1992-08-10",
      "authorized_capital": 2500000000,
      "activity_intelligence": {
        "status": "HIGH_ACTIVITY",
        "last_epfo_filing": "2026-04-30",
        "last_gst_filing": "2026-05-10"
      },
      "compliance_rating": "A+",
      "risk_flags": []
    },
    "audit_timeline": [
      {
        "event_id": "EVT_99812",
        "action_type": "MERGE_RESOLVED",
        "timestamp": "2026-05-14T18:22:10Z",
        "description": "AI Confidence Engine merged 2 duplicate PAN fragments.",
        "actor": "SYSTEM_ENGINE"
      },
      {
        "event_id": "EVT_99815",
        "action_type": "HUMAN_ARBITRATION",
        "timestamp": "2026-05-15T09:14:00Z",
        "description": "Officer verified spatial anchor match for Bagmane Tech Park.",
        "actor": "PILOT_JUDGE_04"
      }
    ]
  }
}

POST

Human Arbitration Feedback Endpoint

POSThttps://api.bbie.gov.in/v1/arbitration

Allows authorized human reviewers and pilot program judges to submit manual arbitration decisions, overriding AI confidence matches or splitting incorrectly merged clusters.

Request Body Schema (application/json)

Parameter	Type	Requirement	Description
ubid	string	Required	The target UBID being arbitrated.
decision	enum	Required	`APPROVE_MERGE` \| `FORCE_SPLIT` \| `FLAG_ANOMALY`.
justification_notes	string	Required	Mandatory audit reasoning for the override.
officer_id	string	Required	Vetted Pilot Judge or Department Officer ID.

Multi-Language Client SDKs

Integrate BBIE identity resolution directly into your existing tech stack using our official client libraries. Select your preferred language below for fully working pilot snippets.

curl -X POST https://api.bbie.gov.in/v1/resolve \
  -H "Authorization: Bearer PILOT_KEY_7719283" \
  -H "X-BBIE-CLIENT-ID: PILOT_MINISTRY_01" \
  -H "X-SOVEREIGNTY-MODE: FULL_MASK" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "Mphasis Limited",
    "pincode": "560001",
    "sovereignty_mask": true
  }'

Error Codes & Troubleshooting Matrix

BBIE uses standardized HTTP status codes paired with detailed JSON error envelopes to ensure fast programmatic remediation during pilot integrations.

HTTP Code	Error Code	Description	Remediation Action
400 Bad Request	ERR_SCHEMA_INVALID	Missing required `entity_name` or invalid pincode format.	Check request payload against the official OpenAPI specification.
401 Unauthorized	ERR_TOKEN_EXPIRED	Institutional Bearer Token is missing, expired, or revoked.	Request a fresh session token from the Governance Hub.
403 Forbidden	ERR_SOVEREIGNTY_VIOLATION	Attempted unmasked PII pull without high-security clearance.	Ensure `X-SOVEREIGNTY-MODE` matches your departmental SLA tier.
404 Not Found	ERR_UBID_UNKNOWN	Requested UBID does not exist in the Golden Registry.	Verify the UBID string or run a `POST /resolve` first.
409 Conflict	ERR_COLLISION_DETECTED	Multiple active businesses share identical names and pincodes.	Provide secondary identifiers (PAN, GSTIN) to break the tie.
429 Too Many Requests	ERR_RATE_LIMIT_EXCEEDED	Institutional token bucket quota depleted.	Implement exponential backoff or request a Tier-2 Enclave upgrade.
500 Internal Error	ERR_ENGINE_TIMEOUT	Upstream state registry (e.g., MCA/EPFO) failed to respond.	Retry request after 5 seconds; BBIE will serve cached golden record.

Sovereignty Shield Architecture

The BBIE platform is built from the ground up to protect institutional data sovereignty. Raw business signals are scrubbed at the memory boundary.

Zero-Knowledge Matching

When an institution submits a resolution query, PII strings (PAN, GSTIN) are converted into salted SHA-256 hashes inside an ephemeral enclave. Matching occurs strictly between hashes, guaranteeing that BBIE database administrators cannot reverse-engineer client customer lists.

Immutable Audit Ledger

Every resolution merge, dossier retrieval, and human arbitration override is cryptographically signed and stored in a tamper-evident audit ledger. Pilot judges can verify the precise lineage of any Golden Record back to its raw registry origins.

DPDP Act 2023 Compliance Framework

BBIE strictly adheres to the Digital Personal Data Protection (DPDP) Act 2023 guidelines for institutional data fiduciaries.

Purpose Limitation

Data ingested via API is utilized exclusively for identity deduplication and compliance scoring. It is never monetized, shared with third-party advertisers, or stored beyond the necessary arbitration lifecycle.

Data Minimization

Institutions can configure the `sovereignty_mask` parameter to receive only binary validation flags (e.g., `gst_valid: true`) rather than pulling complete, sensitive tax histories.

Right to Grievance Redressal

Business entities flagged with anomalies or incorrect merges can initiate a formal redressal workflow via the Governance Hub, triggering an immediate human-in-the-loop review by a designated pilot officer.

Pilot Program Onboarding Checklist

Follow this step-by-step checklist to complete your institutional onboarding and verify your API integration before the live pilot demonstration.

01 Generate Credentials

Log into the Governance Hub using your departmental credentials to provision a dedicated Tier-2 Service Role API Key.

02 Configure Sovereignty Mode

Set your default `X-SOVEREIGNTY-MODE` header in your API client based on your departmental data-sharing agreement.

03 Execute Sandbox Test

Run a test resolution against the known benchmark entity `Mphasis Limited` (Pincode `560001`) to verify 200 OK connectivity.

04 Verify Audit Propagation

Check the Review Workspace in the UI to ensure your API call successfully logged an immutable forensic audit trail.

Need Direct Pilot Engineering Support?

As a selected pilot participant, you have direct access to the core Deepmind & BBIE architecture team for custom integration debugging.

Contact Pilot Support

BBIE Institutional API Specification

3072-Dim AI Matching

Sovereignty Buffer

Golden Record Issuance

Architectural Vision & Workflow

The 5-Stage Zero-Trust Resolution Pipeline

Ingestion & Buffer

Cryptographic Hash

Vector Search

Spatial Anchor

Golden Dossier

Authentication & Security Enclave

Mandatory HTTP Headers

HMAC Signature Verification (Tier-1 Institutions)

Rate Limits & Volumetric Tiers

Identity Resolution Endpoint

Request Body Schema (application/json)

Success Response Payload (200 OK)

Dossier Retrieval Endpoint

Query Parameters

Success Response Payload (200 OK)

Human Arbitration Feedback Endpoint

Request Body Schema (application/json)

Multi-Language Client SDKs

Error Codes & Troubleshooting Matrix

Sovereignty Shield Architecture

DPDP Act 2023 Compliance Framework

Purpose Limitation

Data Minimization

Right to Grievance Redressal

Pilot Program Onboarding Checklist

Need Direct Pilot Engineering Support?

BBIE Institutional
API Specification