API Reference

Complete reference for the Kynode API.

Base URL

https://kynode-api.kynode.workers.dev/v1

Authentication

Kynode uses API keys to authenticate requests. Include your API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Tip: Keep your API keys secure. Don't commit them to version control.

Verify Business

POST /verify

Verify a Korean business registration number and retrieve company information.

Language Options (lang body field)

Value	Description
en	English output with DART-verified company names
ko	Korean output (default)
both	Both Korean and English in one response
code	Minimal response with status codes only

Request Body

Parameter	Type	Required	Description
business_number	string	Yes	10-digit Korean business registration number (no hyphens)
startDate	string	Yes	Business start date (YYYYMMDD or YYYY-MM-DD)
ownerName	string	Yes	Representative name (must match NTS records exactly)
companyName	string	No	Korean company name. When provided, used to look up the official English company name from the DART database (117,078 companies). Strongly recommended when `lang` is `"en"` or `"both"` for accurate English company names, since NTS does not return company names in their API response. Alias: `company_name`.
lang	string	No	Output language: en / ko / both / code (default: ko)

Example Request

Include companyName when requesting English output — NTS validation does not return the trade name (b_nm).

{
  "business_number": "1248100998",
  "startDate": "19691201",
  "ownerName": "전영현",
  "companyName": "삼성전자",
  "lang": "en"
}

curl -X POST "https://kynode-api.kynode.workers.dev/v1/verify" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "business_number": "1248100998",
    "startDate": "19691201",
    "ownerName": "전영현",
    "companyName": "삼성전자",
    "lang": "en"
  }'

Response

Success Response200 OK

{
  "isValid": true,
  "businessInfo": {
    "businessNumber": "8090903407",
    "companyName": "Nodemetrics",
    "companyNameOriginal": "노드메트릭스",
    "companyNameSource": "dart",
    "representative": "강민구",
    "status": "Active",
    "statusCode": "01",
    "taxType": "General VAT Taxpayer",
    "taxTypeCode": "01",
    "verifiedAt": 1747123456789
  }
}

Batch Verification API

Process multiple business numbers in a single request. Available on Pro tier and above.

POST `/v1/batch/verify`JSON Array

curl -X POST "https://kynode-api.kynode.workers.dev/v1/batch/verify" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "business_numbers": ["8090903407", "1234567890"],
    "start_date": "20260513",
    "owner_name": "강민구",
    "language": "en"
  }'

POST `/v1/batch/upload`CSV Upload

Upload a CSV file with multiple businesses. Required columns: business_number, start_date, owner_name. Optional: company_name.

# CSV format
business_number,start_date,owner_name,company_name
8090903407,20260513,강민구,노드메트릭스
1234567890,20200101,홍길동,

# Upload
curl -X POST "https://kynode-api.kynode.workers.dev/v1/batch/upload" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: text/csv" \
  --data-binary "@companies.csv"

GET /v1/batch/status/:job_id

Check processing status of a batch job.

GET /v1/batch/download/:job_id

Download results as CSV (UTF-8 with BOM for Excel).

Plan	Batch Access	Max per Request
Free	✗	-
Starter	✗	-
Pro	✓	100
Premium	✓	1,000
Enterprise	✓	10,000

Errors

Kynode uses conventional HTTP response codes to indicate success or failure.

Code	Description
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — feature not available on current plan
404	Not found — endpoint or resource does not exist
429	Rate limit or monthly quota exceeded
500	Internal server error — try again later

{
  "error": {
    "code": "invalid_business_number",
    "message": "The business number format is invalid"
  }
}

Rate Limits

Kynode enforces rate limits to ensure service quality for all users.

Plan	Monthly Verifications	Price
Free	100	$0
Starter	5,000	$29/mo
Pro	25,000	$99/mo
Premium	100,000	$299/mo
Enterprise	500,000+	$999/mo