kynode

Official Python SDK for the Kynode Korean Business Verification API.

Verify Korean business registration numbers against NTS data with optional DART-verified English company names.

Requirements

• Python 3.8+
• httpx (installed automatically)

Installation

pip install kynode

Quick start

from kynode import Kynode

client = Kynode(api_key="sk_live_...")

result = client.verify(
    business_number="8090903407",
    start_date="20260513",
    owner_name="강민구",
    company_name="노드메트릭스",
    language="en",
)

print(result["isValid"], result.get("businessInfo", {}).get("companyName"))

Client options

Use as a context manager to close HTTP connections:

with Kynode(api_key="sk_live_...") as client:
    result = client.verify(...)

Single verification (sync)

result = client.verify(
    business_number="1234567890",
    start_date="20240101",
    owner_name="홍길동",
    language="en",  # optional: en | ko | both | code (default: en)
)

Calls POST /v1/verify with Bearer authentication.

Single verification (async)

import asyncio
from kynode import Kynode

async def main():
    client = Kynode(api_key="sk_live_...")
    try:
        result = await client.verify_async(
            business_number="1234567890",
            start_date="20240101",
            owner_name="홍길동",
        )
        print(result)
    finally:
        await client.aclose()

asyncio.run(main())

Batch verification (sync)

batch = client.batch_verify([
    {"business_number": "1234567890", "start_date": "20240101", "owner_name": "홍길동"},
    {"business_number": "9876543210", "start_date": "20240101", "owner_name": "김철수"},
])

print(batch["total"], batch["success"], batch["failed"])
for row in batch["results"]:
    if row["success"]:
        print(row["business_number"], row["data"])
    else:
        print(row["business_number"], row["error"])

• If all items share the same start_date, owner_name, language, and company_name, the client calls POST /v1/batch/verify (Pro tier and above).
• If fields differ per row, the client runs parallel single verifications and returns a batch-shaped response.

Batch verification (async)

batch = await client.batch_verify_async([...])

Error handling

from kynode import (
    Kynode,
    KynodeError,
    KynodeAuthError,
    KynodeQuotaError,
    KynodeValidationError,
    KynodeNotFoundError,
)

try:
    client.verify(...)
except KynodeAuthError:
    # 401 — invalid or missing API key
    pass
except KynodeQuotaError:
    # 429 — monthly quota exceeded
    pass
except KynodeValidationError:
    # 400 — invalid request
    pass
except KynodeNotFoundError:
    # 404 — endpoint not found
    pass
except KynodeError as exc:
    print(exc.status_code, exc.code, exc.message, exc.details)

Timeouts raise KynodeError with code="timeout" and status_code=408.

Development

cd kynode
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest

Build for PyPI

pip install build twine
python -m build
twine check dist/*
# twine upload dist/*

Links

• API documentation
• Get an API key

License

MIT