{ "openapi": "3.1.0", "info": { "title": "Jaryo API", "version": "0.1.0", "summary": "Korean public records about companies, resolved to one entity, in an English schema.", "description": "Jaryo means 'data' in Korean — every public record about a Korean company, linked. Jaryo redistributes Korean public records. Each value lists its source and license; show the attribution when you display the data. Free tier: 200 calls/day per key, 30/minute, non-commercial use, attribution required.", "license": { "name": "Per-source licenses — see GET /v1/sources" } }, "servers": [ { "url": "https://api.jaryo.org/v1", "description": "Jaryo API (beta)" } ], "security": [], "paths": { "/verify": { "get": { "operationId": "verifyCompany", "summary": "Verify a Korean corporation — start here (no key needed)", "description": "Name, business registration number (10 digits), corporate registration number (13 digits), DART code (8 digits) or stock code (6 digits, from the DART company overview) → does it exist, National Tax Service status with the time it was checked, official numbers, Korean/English names, address, industry, sources. Corporations only: an individual business number returns supported=false. found is null when the registry could not be checked (never 'not found' by mistake). Up to 10 matches, best-known company first (name match first; then open before closed, listed, headcount, DART filer); more_matches=true when there are more — add the business number or city to narrow. Each match has match_type. No scores. Without a key every keyless route (REST and MCP) shares 60 requests per minute per IP; live National Tax Service checks are limited further.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "Verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/resolve": { "post": { "operationId": "resolveCompany", "summary": "Find the Jaryo company entity for a name or an official identifier", "security": [ { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } } }, "responses": { "200": { "description": "Candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/companies/{id}": { "get": { "operationId": "getCompany", "summary": "Company profile: names, identifiers, current profile records, record counts", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/CompanyId" } ], "responses": { "200": { "description": "Company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/companies/{id}/records": { "get": { "operationId": "listCompanyRecords", "summary": "Public records attached to a company (current versions)", "security": [ { "bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/CompanyId" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "company_profile", "vendor_profile", "award", "contract", "filing", "employment", "status", "sanction", "corp_outline", "corp_code" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Point-in-time view — planned for phase 2; rejected with 400 now." } ], "responses": { "200": { "description": "Records", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordPage" } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "404": { "$ref": "#/components/responses/Problem404" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/search": { "get": { "operationId": "searchCompanies", "summary": "Search companies by Korean or English name (top 20)", "security": [ { "bearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Name or part of it. Case, spaces and legal-form words (주식회사, (주)) are ignored. Queries of 3+ characters match any part of a name; 1-2 characters match names that start with them.", "schema": { "type": "string", "minLength": 2, "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } ], "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "429": { "$ref": "#/components/responses/Problem429" } } } }, "/sources": { "get": { "operationId": "listSources", "summary": "Source catalog with license and redistribution status (no key needed)", "responses": { "200": { "description": "Sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sources" } } } } } } }, "/status": { "get": { "operationId": "getStatus", "summary": "Availability, source freshness and measured resolution accuracy (no key needed)", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Jaryo API key (jry_free_…)" } }, "parameters": { "CompanyId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "description": "Jaryo entity id (ULID)" } }, "responses": { "Problem400": { "description": "RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem401": { "description": "RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem404": { "description": "RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem429": { "description": "RFC 9457 problem", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "VerifyResponse": { "type": "object", "required": [ "query", "query_kind", "supported", "matches", "attribution" ], "properties": { "query": { "type": "string" }, "query_kind": { "type": "string", "enum": [ "biz_no", "corp_reg_no", "dart_corp_code", "stock_code", "name" ] }, "more_matches": { "type": "boolean", "description": "true when more than 10 companies match; matches holds the first 10" }, "more_matches_hint": { "type": "string", "description": "present when more_matches=true" }, "supported": { "type": "boolean", "description": "false for individual (non-corporate) business numbers" }, "reason": { "type": "string" }, "found": { "type": [ "boolean", "null" ], "description": "true found · false not found · null could not be checked" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "match_type": { "type": "string", "enum": [ "exact_id", "exact_name", "former_name", "prefix", "contains" ], "description": "how this company matched: exact_id = by number; exact_name = same name apart from the legal-form word; prefix = name starts with the query; contains = name contains it; former_name is reserved for previous names" }, "name": { "type": "object", "properties": { "ko": { "type": [ "string", "null" ] }, "en": { "type": [ "string", "null" ] } } }, "identifiers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "status": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "active", "suspended", "closed", "unknown" ] }, "closed_on": { "type": [ "string", "null" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_id": { "type": [ "string", "null" ] }, "checked_by": { "type": [ "string", "null" ], "description": "ingest = our daily collection; live = a National Tax Service check (cached for a day)" }, "live": { "type": "boolean", "description": "true only when checked with the National Tax Service during this request" } } }, "address": { "type": [ "object", "null" ] }, "industry": { "type": [ "object", "null" ] }, "sources": { "type": "array", "items": { "type": "string" } } } } }, "registry": { "type": [ "object", "null" ], "description": "For a corporate number not in Jaryo yet: whether the National Tax Service has it registered", "properties": { "checked": { "type": "boolean" }, "reason": { "type": "string", "description": "when checked=false: live_limit, live_unavailable, source_not_approved" }, "registered": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "suspended", "closed", "unknown" ] }, "closed_on": { "type": [ "string", "null" ] }, "checked_at": { "type": "string", "format": "date-time" }, "live": { "type": "boolean" } } }, "attribution": { "type": "array", "items": { "type": "object" } }, "notice": { "type": "string" } } }, "Text": { "type": "object", "properties": { "ko": { "type": "string" }, "en": { "type": [ "string", "null" ] } } }, "Attribution": { "type": "object", "required": [ "source_id", "text", "license_id", "terms_url" ], "properties": { "source_id": { "type": "string" }, "text": { "type": "string" }, "license_id": { "type": "string" }, "terms_url": { "type": "string", "format": "uri" } } }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "description": "https://jaryo.org/problems/" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" } } }, "ResolveRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2 }, "biz_no": { "type": "string", "description": "Business registration number (10 digits)" }, "corp_reg_no": { "type": "string", "description": "Corporate registration number (13 digits)" }, "dart_corp_code": { "type": "string", "description": "DART corp code (8 digits)" }, "g2b_vendor_id": { "type": "string", "description": "KONEPS vendor id (= business registration number)" } } }, "ResolveResponse": { "type": "object", "required": [ "candidates", "attribution" ], "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "confidence": { "type": "number" }, "matched_on": { "type": "array", "items": { "type": "string" } }, "canonical_name_ko": { "type": [ "string", "null" ] }, "canonical_name_en": { "type": [ "string", "null" ] } } } }, "attribution": { "type": "array", "items": { "$ref": "#/components/schemas/Attribution" } } } }, "Record": { "type": "object", "required": [ "record_type", "source_id", "source_record_key", "fetched_at", "license_id", "data" ], "properties": { "id": { "type": "string" }, "record_type": { "type": "string", "enum": [ "company_profile", "vendor_profile", "award", "contract", "filing", "employment", "status", "sanction", "corp_outline", "corp_code" ] }, "source_id": { "type": "string" }, "source_record_key": { "type": "string" }, "fetched_at": { "type": "string", "format": "date-time" }, "license_id": { "type": "string" }, "data": { "type": "object", "description": "Normalized payload — see the field dictionary (jaryo://schema)" } } }, "Company": { "type": "object", "required": [ "id", "names", "identifiers", "attribution" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "object", "description": "From the National Tax Service status record, with its source; 'unknown' when that source is not public", "properties": { "value": { "type": "string", "enum": [ "active", "suspended", "closed", "unknown" ] }, "source_id": { "type": [ "string", "null" ] }, "fetched_at": { "type": [ "string", "null" ] }, "license_id": { "type": [ "string", "null" ] } } }, "names": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "value": { "type": "string" }, "source_id": { "type": "string" } } } }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "source_id": { "type": "string" }, "license_id": { "type": "string" }, "valid_from": { "type": "string" } } } }, "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "record_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "attribution": { "type": "array", "items": { "$ref": "#/components/schemas/Attribution" } } } }, "RecordPage": { "type": "object", "properties": { "company_id": { "type": "string" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "next_cursor": { "type": [ "string", "null" ] }, "attribution": { "type": "array", "items": { "$ref": "#/components/schemas/Attribution" } } } }, "SearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "canonical_name_ko": { "type": [ "string", "null" ] }, "canonical_name_en": { "type": [ "string", "null" ] } } } }, "attribution": { "type": "array", "items": { "$ref": "#/components/schemas/Attribution" } } } }, "Sources": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object" } } } }, "Status": { "type": "object", "properties": { "status": { "type": "string" }, "sources": { "type": "array" }, "quality": { "type": "array" } } } } } }