{
  "openapi": "3.1.0",
  "info": {
    "title": "IFSC & MICR API",
    "version": "1.0.0",
    "description": "Free lookup API for Indian bank branches by IFSC or MICR code. Data: Reserve Bank of India IFSC/MICR master list, synced automatically. Every response carries a `source` object with the dataset version and sync time.",
    "contact": { "url": "https://codein.co.in/ifsc-api/" },
    "license": { "name": "Data: RBI public list; please cite the source" }
  },
  "servers": [{ "url": "https://codein.co.in/api/v1" }],
  "paths": {
    "/ifsc/{ifsc}": {
      "get": {
        "summary": "Branch by IFSC",
        "operationId": "getIfsc",
        "parameters": [{ "name": "ifsc", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{4}0[A-Za-z0-9]{6}$" }, "example": "SBIN0000300" }],
        "responses": {
          "200": { "description": "Branch found", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/Branch" }, { "type": "object", "properties": { "source": { "$ref": "#/components/schemas/Source" } } }] } } } },
          "400": { "description": "Invalid IFSC format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Not in the RBI list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/micr/{micr}": {
      "get": {
        "summary": "Branches by MICR",
        "operationId": "getMicr",
        "parameters": [{ "name": "micr", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{9}$" }, "example": "400002010" }],
        "responses": {
          "200": { "description": "Matching branches", "content": { "application/json": { "schema": { "type": "object", "properties": { "micr": { "type": "string" }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "source": { "$ref": "#/components/schemas/Source" } } } } } },
          "400": { "description": "Invalid MICR format" },
          "404": { "description": "Not in the RBI list" }
        }
      }
    },
    "/banks": {
      "get": {
        "summary": "All banks",
        "operationId": "listBanks",
        "responses": { "200": { "description": "Bank list", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "banks": { "type": "array", "items": { "$ref": "#/components/schemas/Bank" } }, "source": { "$ref": "#/components/schemas/Source" } } } } } } }
      }
    },
    "/banks/{code}": {
      "get": {
        "summary": "One bank by 4-letter code or slug",
        "operationId": "getBank",
        "parameters": [{ "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "example": "HDFC" }],
        "responses": { "200": { "description": "Bank", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bank" } } } }, "404": { "description": "Unknown bank" } }
      }
    },
    "/search": {
      "get": {
        "summary": "Branches of a bank in a state, filtered by text",
        "operationId": "searchBranches",
        "parameters": [
          { "name": "bank", "in": "query", "required": true, "schema": { "type": "string" }, "example": "HDFC" },
          { "name": "state", "in": "query", "required": true, "description": "ISO 3166-2:IN state code without the IN- prefix", "schema": { "type": "string" }, "example": "DL" },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "example": "rohini" }
        ],
        "responses": { "200": { "description": "Up to 100 results", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } } } } } } }, "400": { "description": "Missing bank or state" } }
      }
    },
    "/validate/ifsc/{ifsc}": {
      "get": {
        "summary": "Validate an IFSC (format, bank, branch)",
        "operationId": "validateIfsc",
        "parameters": [{ "name": "ifsc", "in": "path", "required": true, "schema": { "type": "string" }, "example": "SBIN0000300" }],
        "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ifsc": { "type": "string" }, "formatValid": { "type": "boolean" }, "bankExists": { "type": "boolean" }, "exists": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } }, "suggestions": { "type": "array", "items": { "type": "string" } }, "branch": { "oneOf": [{ "$ref": "#/components/schemas/Branch" }, { "type": "null" }] } } } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Branch": {
        "type": "object",
        "properties": {
          "ifsc": { "type": "string" },
          "micr": { "type": ["string", "null"] },
          "bank": { "type": "string" },
          "bankCode": { "type": "string" },
          "branchCode": { "type": "string" },
          "branch": { "type": "string" },
          "address": { "type": "string" },
          "city": { "type": "string" },
          "district": { "type": "string" },
          "state": { "type": "string" },
          "stateCode": { "type": "string" },
          "contact": { "type": ["string", "null"] },
          "swift": { "type": ["string", "null"] },
          "neft": { "type": "boolean" },
          "rtgs": { "type": "boolean" },
          "imps": { "type": "boolean" },
          "upi": { "type": "boolean" },
          "url": { "type": ["string", "null"], "format": "uri" }
        }
      },
      "Bank": {
        "type": "object",
        "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": ["string", "null"] }, "branches": { "type": "integer" }, "upi": { "type": "boolean" }, "url": { "type": "string", "format": "uri" } }
      },
      "Source": {
        "type": "object",
        "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "version": { "type": "string" }, "syncedAt": { "type": "string", "format": "date-time" } }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  }
}