{ "openapi": "3.1.0", "info": { "title": "Elucidate directory of financial institutions", "version": "1.0.0", "summary": "Every BIC8 in Swift’s ISO 9362 directory and the firms on 22 tracked regulator registers.", "description": "Read-only, no key. Search returns JSON; each institution, branch code, register firm, country and register has a page whose Markdown twin (`.md`) carries the identifiers (BIC, LEI, licence numbers), status, sanctions-list checks on the BIC and the sources with their dates.\n\nIdentifiers resolve: `/directory/COBADEFF.md`, `/directory/COBADEFFXXX.md`, `/directory/.md` or a licence number redirect to the canonical page.\n\nThe same reads are available as tools over the Model Context Protocol at https://elucidate.co/mcp (Streamable HTTP, no auth). Agent guide: https://elucidate.co/for-agents.\n\nPlease cite the page URL and the source date it gives.", "contact": { "name": "Elucidate", "url": "https://elucidate.co/contact", "email": "contact@elucidate.co" } }, "servers": [ { "url": "https://elucidate.co" } ], "externalDocs": { "description": "For agents: Markdown twins, llms.txt, MCP", "url": "https://elucidate.co/for-agents" }, "tags": [ { "name": "search", "description": "Find institutions by name or identifier." }, { "name": "pages", "description": "The directory pages, as Markdown." } ], "paths": { "/api/directory/search": { "get": { "operationId": "searchDirectory", "tags": [ "search" ], "summary": "Search the directory", "description": "Name, BIC (8 or 11 characters, or a 4–6 character prefix), LEI or licence number, with optional filters. Active institutions only unless `status` says otherwise.", "parameters": [ { "name": "q", "in": "query", "description": "Name, BIC, LEI or licence number (2–100 characters). Omit to list by filters alone.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "cc", "in": "query", "description": "Country (ISO 3166-1 alpha-2) of the institution or branch. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "style": "form", "explode": false }, { "name": "hq", "in": "query", "description": "Country of the head office, for branches of foreign institutions. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "style": "form", "explode": false }, { "name": "source", "in": "query", "description": "`bic`: holds a BIC; `nobic`: does not; `register`: on a tracked regulator register; `noregister`: not on one. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "bic", "nobic", "register", "noregister" ] } }, "style": "form", "explode": false }, { "name": "type", "in": "query", "description": "Institution type: `bank` Credit institution; `payments` Payments & e-money; `crypto` Crypto; `msb` Money service business; `financial` Financial institution; `nonfinancial` Non-financial corporate. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "bank", "payments", "crypto", "msb", "financial", "nonfinancial" ] } }, "style": "form", "explode": false }, { "name": "reg", "in": "query", "description": "Highest regulatory status on a tracked register: `prudential` Prudential licence; `registered` Small-firm registration; `aml` AML registration only; `none` Not on a tracked register. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "prudential", "registered", "aml", "none" ] } }, "style": "form", "explode": false }, { "name": "register", "in": "query", "description": "Tracked register code, e.g. `FCA-EMI`, `FINCEN-MSB`, `ESMA-CASP` (list: /directory/register.md). Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$", "maxLength": 20 } }, "style": "form", "explode": false }, { "name": "act", "in": "query", "description": "Licensed activity key, as listed in the search page’s activity filter. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "pattern": "^[a-z_]{2,30}$" } }, "style": "form", "explode": false }, { "name": "flag", "in": "query", "description": "Flags: `sanctioned` On OFAC or EU lists; `gsib` In a G-SIB group; `ssm` ECB-supervised; `gpi` Swift GPI member; `sepa` Reachable in SEPA; `t2` T2 participant; `swift` Its LEI is mapped to a BIC; `licensed` Holds a BIC and register licences; `casp` Crypto-asset service provider (ESMA); `mic` Operates a trading venue (MIC); `bankcode` National bank code; `lei` LEI mapped. Comma-separated, or repeat the parameter.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "sanctioned", "gsib", "ssm", "gpi", "sepa", "t2", "swift", "licensed", "casp", "mic", "bankcode", "lei" ] } }, "style": "form", "explode": false }, { "name": "status", "in": "query", "description": "`A` active (default), `I` inactive, `ALL` both.", "schema": { "type": "string", "enum": [ "A", "I", "ALL" ], "default": "A" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 12 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Matches, best first, with facet counts for the whole matching set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } } } } }, "/directory/{identifier}.md": { "get": { "operationId": "getInstitution", "tags": [ "pages" ], "summary": "An institution, branch code or register firm, as Markdown", "description": "Accepts a BIC8, a BIC11, an LEI, a licence number, a firm ID (12 hex characters) or a page slug; anything but the canonical slug redirects to it. An LEI shared by several institutions returns a page listing them.", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "examples": { "bic8": { "value": "COBADEFF" }, "bic11": { "value": "COBADEFFXXX" }, "lei": { "value": "851WYGNLUQLFZBSYGB56" } } } ], "responses": { "200": { "description": "The page, with YAML front matter (title, description, canonical url).", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "301": { "description": "The identifier resolves to another page (a BIC11, LEI, licence number or name → its canonical page). Follow `Location`.", "headers": { "Location": { "schema": { "type": "string" } } } }, "404": { "description": "Nothing in the directory matches.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/directory/country/{cc}.md": { "get": { "operationId": "getCountry", "tags": [ "pages" ], "summary": "A country: institutions, BIC holders, registers and sanctions context", "parameters": [ { "name": "cc", "in": "path", "required": true, "description": "ISO 3166-1 alpha-2, lower case.", "schema": { "type": "string", "pattern": "^[a-z]{2}$" } } ], "responses": { "200": { "description": "The country page.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Nothing in the directory matches.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/directory/register.md": { "get": { "operationId": "listRegisters", "tags": [ "pages" ], "summary": "The tracked regulator registers", "responses": { "200": { "description": "Every tracked register, with its code, regulator and counts.", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/directory/register/{code}.md": { "get": { "operationId": "getRegister", "tags": [ "pages" ], "summary": "One tracked register: what it publishes and who is on it", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Register code, lower case, e.g. `fincen-msb`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]{2,20}$" } } ], "responses": { "200": { "description": "The register page.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "404": { "description": "Nothing in the directory matches.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "SearchResponse": { "type": "object", "required": [ "query", "total", "offset", "results" ], "properties": { "query": { "type": "string" }, "total": { "type": "integer", "description": "Matches in all (results holds one page of them)." }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "facets": { "type": "object", "description": "Counts per filter value over the matching set.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } }, "profile": { "type": [ "object", "null" ], "description": "Summary counts of the matching set." } } }, "Result": { "type": "object", "required": [ "kind", "key", "name", "cc" ], "properties": { "kind": { "type": "string", "enum": [ "institution", "firm" ], "description": "`institution`: a BIC8 in Swift’s directory; `firm`: a register entry with no BIC of its own." }, "key": { "type": "string", "description": "BIC8, or the firm ID." }, "name": { "type": "string" }, "cc": { "type": "string" }, "country": { "type": "string" }, "url": { "type": [ "string", "null" ], "description": "Page path; append `.md` for Markdown." }, "types": { "type": "array", "items": { "type": "string" } }, "reg": { "type": "string", "description": "Highest regulatory status on a tracked register." }, "status": { "type": "string", "enum": [ "A", "I" ] }, "lei": { "type": [ "string", "null" ] }, "registers": { "type": "array", "items": { "type": "string" } }, "flags": { "type": "array", "items": { "type": "string" } }, "bic8": { "type": "string", "description": "Institutions only." }, "branches": { "type": "integer", "description": "Institutions only: branch codes under the BIC8." }, "connectivity": { "type": [ "string", "null" ], "enum": [ "connected", "passive", "reverse-billing", "test", null ], "description": "Institutions only: what the BIC’s 8th character says about the connection to Swift." }, "sanctions": { "type": "object", "description": "Institutions only: listings matched on the BIC and its LEI (`scope` `bic`), the OFAC list that cites it, whether the EU list cites it, and the country’s sanctions level. Register firms are not screened and carry no `sanctions`. Screen against the official lists before relying on an absence.", "properties": { "scope": { "type": "string" }, "ofac": { "type": [ "string", "null" ], "enum": [ "SDN", "NON-SDN", null ] }, "eu": { "type": "boolean" }, "country": { "type": [ "string", "null" ] } } }, "licences": { "type": "integer" }, "id": { "type": "string", "description": "Firms only: 12-hex firm ID." }, "tradingNames": { "type": "array", "items": { "type": "string" } }, "mainLicence": { "type": [ "object", "null" ], "description": "Firms only.", "properties": { "register": { "type": "string" }, "number": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "regulator": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } } } }