{ "openapi": "3.1.0", "info": { "title": "SW CPAs API", "version": "1.0.0", "summary": "Public API of 에스더블유 공인회계사 사무소 (SW CPAs), sw-cpas.co.kr.", "description": "Read-only facts about the firm, its services and Korean articles, the free US incorporation finder, and consultation requests sent on a person's behalf. No API key or sign-up. Errors are JSON objects {error:{code,message,hint,status,docs}}. Limits: 60 reads and 10 writes per minute per client; consultation requests 3 per hour per client and 20 per day site-wide. Breaking changes ship under a new path version with Deprecation and Sunset headers on the old one for at least 90 days.", "contact": { "name": "SW CPAs", "email": "swyoun@sw-cpas.com", "url": "https://sw-cpas.co.kr/developers/" } }, "externalDocs": { "description": "Developer docs (API, MCP, WebMCP)", "url": "https://sw-cpas.co.kr/developers/" }, "servers": [ { "url": "https://sw-cpas.co.kr", "description": "Production" }, { "url": "https://sw-cpas.co.kr/sandbox", "description": "Sandbox: same API; consultation requests are validated but never stored or sent (X-Environment: sandbox)." } ], "security": [], "tags": [ { "name": "firm", "description": "Facts about the firm and its services." }, { "name": "content", "description": "Articles and site search." }, { "name": "finder", "description": "Free US incorporation finder." }, { "name": "consultation", "description": "Consultation requests sent on a person's behalf." } ], "paths": { "/api/v1/firm": { "get": { "operationId": "getFirmProfile", "tags": [ "firm" ], "summary": "Get firm profile", "description": "Representative's US and Korean CPA licenses, Seoul and LA offices, phone, email and how fees are quoted.", "responses": { "200": { "description": "Firm profile", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firm" } } } }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/services": { "get": { "operationId": "listServices", "tags": [ "firm" ], "summary": "List services", "description": "Every service page with a short summary, plus free tools.", "responses": { "200": { "description": "Services", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/insights": { "get": { "operationId": "searchInsights", "tags": [ "content" ], "summary": "List or search articles", "description": "Korean articles on US tax and incorporation. Newest first, or best match when q is given. Cursor pagination.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Words to search for.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "category", "in": "query", "required": false, "description": "Exact category, e.g. 세무.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of articles", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightPage" } } } }, "400": { "$ref": "#/components/responses/E400" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/us-incorporation/questions": { "get": { "operationId": "getUsIncorporationQuestions", "tags": [ "finder" ], "summary": "Get finder questions", "description": "Question ids, wording and allowed values for the US incorporation finder.", "responses": { "200": { "description": "Questions", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderQuestions" } } } }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/us-incorporation/evaluate": { "post": { "operationId": "evaluateUsIncorporation", "tags": [ "finder" ], "summary": "Recommend a US state and entity", "description": "Runs the same rules as the website finder. Stores nothing. General guidance, not tax advice.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderRequest" } } } }, "responses": { "200": { "description": "Recommendation", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinderResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/consultation-requests": { "post": { "operationId": "createConsultationRequest", "tags": [ "consultation" ], "summary": "Request a consultation on a person's behalf", "description": "Sends a real email to the firm and stores the request. Confirm every field with the person and get their consent to https://sw-cpas.co.kr/privacy/. Use dry_run: true first (test mode). Send an Idempotency-Key so retries are not submitted twice: a retry with the same key and the same body returns the first 202 (from any IP), the same key with a different body returns 409 idempotency_key_reused, and a retry while the first is still running returns 409 request_in_progress.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key per request; a retry with the same key returns the first response.", "schema": { "type": "string", "maxLength": 100 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultationRequest" } } } }, "responses": { "200": { "description": "Dry run: validated, nothing sent", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultationDryRun" } } } }, "202": { "description": "Accepted. The firm follows up by email or phone; check status at Location.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" }, "Location": { "description": "Status URL of this request.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultationReceived" } } } }, "400": { "$ref": "#/components/responses/E400" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "502": { "$ref": "#/components/responses/E502" }, "503": { "$ref": "#/components/responses/E503" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/api/v1/consultation-requests/{request_id}": { "get": { "operationId": "getConsultationRequestStatus", "tags": [ "consultation" ], "summary": "Check a consultation request", "description": "Status of a request accepted by createConsultationRequest. Returns no personal data.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "request_id from the 202 response.", "schema": { "type": "string", "pattern": "^csr_[0-9a-f-]{36}$" } } ], "responses": { "200": { "description": "Status", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsultationStatus" } } } }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } }, "/ask": { "get": { "operationId": "askSite", "tags": [ "content" ], "summary": "Find pages that answer a question (NLWeb)", "description": "Returns matching sw-cpas.co.kr pages as schema.org items. Does not generate answers.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "The question.", "schema": { "type": "string", "maxLength": 300 } } ], "responses": { "200": { "description": "Matching pages", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } }, "post": { "operationId": "askSitePost", "tags": [ "content" ], "summary": "Find pages that answer a question (NLWeb POST)", "description": "NLWeb v0.55 request body with query.text.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 300 } } } } } } } }, "responses": { "200": { "description": "Matching pages", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResult" } } } }, "400": { "$ref": "#/components/responses/E400" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "default": { "$ref": "#/components/responses/E500" } } } } }, "components": { "headers": { "RateLimit-Limit": { "description": "Requests allowed in the window.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "API-Version": { "description": "API version of this response.", "schema": { "type": "string", "const": "1" } } }, "responses": { "E400": { "description": "Bad request (invalid JSON or parameter)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict. idempotency_key_reused: this Idempotency-Key was used for a different request; send a new key for a new request. request_in_progress: the same request is still being processed; wait and retry with the same key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Validation failed; see details", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Too many requests", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E502": { "description": "Could not store or deliver", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Temporarily unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "type", "title", "status", "detail", "error" ], "description": "RFC 9457 problem details plus an error object with the same facts.", "properties": { "type": { "type": "string", "format": "uri", "description": "https://sw-cpas.co.kr/developers/#error-" }, "title": { "type": "string", "description": "Short summary (same as error.message)." }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "description": "How to fix it (same as error.hint)." }, "instance": { "type": "string", "description": "Request path." }, "error": { "type": "object", "required": [ "code", "message", "hint", "status", "docs" ], "properties": { "code": { "type": "string", "enum": [ "not_found", "method_not_allowed", "invalid_json", "invalid_parameter", "invalid_answers", "invalid_request", "rate_limited", "service_unavailable", "delivery_failed", "internal_error", "missing_query", "request_failed", "idempotency_key_reused", "request_in_progress" ], "description": "Stable machine code." }, "message": { "type": "string" }, "hint": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "docs": { "type": "string", "format": "uri" }, "details": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "Firm": { "type": "object", "required": [ "name", "url", "contact" ], "properties": { "name": { "type": "string", "description": "Legal name." }, "alternate_names": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "description": "Website." }, "description": { "type": "string", "description": "What the firm does." }, "representative": { "type": "object" }, "business_registration_number": { "type": "string", "description": "Korean business registration number." }, "founded": { "type": "string", "description": "Date opened." }, "offices": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "country": { "type": "string" } } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "telephone": { "type": "string" }, "kakao": { "type": "string" }, "contact_form": { "type": "string" }, "consultation_api": { "type": "string" } } }, "languages": { "type": "array", "items": { "type": "string" } }, "fees": { "type": "string", "description": "How fees are quoted." }, "pricing_page": { "type": "string", "description": "Pricing page URL." }, "profiles": { "type": "array", "items": { "type": "string" } } } }, "Service": { "type": "object", "required": [ "id", "name", "url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "category": { "type": "string" }, "url": { "type": "string" } } }, "ServiceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "tools": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } }, "Insight": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "date": { "type": "string" }, "author": { "type": "string" }, "url": { "type": "string" } } }, "InsightPage": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "total": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page; null on the last page." }, "query": { "type": [ "string", "null" ] } } }, "FinderQuestions": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "required": { "type": "boolean" }, "asked_only_if": { "type": [ "object", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } } } } } }, "FinderAnswers": { "type": "object", "properties": { "business_type": { "type": "string", "enum": [ "ecommerce", "saas", "consulting", "trade", "knowledge_export", "real_estate", "offline" ], "description": "어떤 사업으로 미국에 진출하시나요?" }, "platform": { "type": "string", "enum": [ "amazon_fba", "own_mall", "both" ], "description": "주력 판매 채널은 무엇인가요? (Only when {\"business_type\":[\"ecommerce\",\"trade\"]})" }, "presence": { "type": "string", "enum": [ "none", "warehouse_3pl", "employees", "office" ], "description": "미국 내 물리적 사업장 계획이 있나요?" }, "presence_state": { "type": "string", "enum": [ "CA", "NY", "TX", "FL", "WA", "GA", "NJ", "IL", "NC", "AZ", "TN", "other", "undecided" ], "description": "사업장(직원)이 위치할 주는 어디인가요? (Only when {\"presence\":[\"employees\",\"office\"]})" }, "owner": { "type": "string", "enum": [ "korean_corp", "korean_individual", "mixed", "us_person" ], "description": "미국 법인의 소유자(주주)는 누구인가요?" }, "funding": { "type": "string", "enum": [ "yes_12mo", "yes_later", "no" ], "description": "미국 VC·기관투자 유치 계획이 있나요?" }, "visa": { "type": "string", "enum": [ "stay_korea", "e2_l1", "relocate" ], "description": "비자·거주 계획은 어떻게 되나요?" }, "profit": { "type": "string", "enum": [ "reinvest", "remit" ], "description": "미국에서 번 이익은 어떻게 하실 계획인가요?" }, "privacy": { "type": "string", "enum": [ "important", "none" ], "description": "법인 소유자 정보 비공개(익명성)가 중요한가요?" }, "revenue": { "type": "string", "enum": [ "lt_100k", "r100k_700k", "r700k_2650k", "gte_2650k" ], "description": "첫해 미국 매출은 어느 정도로 예상하시나요?" }, "pr_relocate": { "type": "string", "enum": [ "yes", "no" ], "description": "핵심 인력이 푸에르토리코에 실제 이주·상주할 수 있나요? (Only when {\"business_type\":[\"knowledge_export\"]})" } }, "required": [ "business_type", "presence", "owner", "funding", "visa", "profit", "privacy", "revenue" ], "additionalProperties": false }, "FinderRequest": { "type": "object", "required": [ "answers" ], "properties": { "answers": { "$ref": "#/components/schemas/FinderAnswers" } } }, "FinderResult": { "type": "object", "required": [ "entity", "state", "disclaimer" ], "properties": { "engine_version": { "type": "string" }, "fit_score": { "type": "integer" }, "entity": { "type": "object" }, "state": { "type": "object" }, "costs": { "type": "object" }, "tax_summary": { "type": [ "object", "array" ] }, "warnings": { "type": "array" }, "korea_checklist": { "type": "array" }, "roadmap": { "type": "array" }, "share_code": { "type": "string" }, "tool_url": { "type": "string" }, "next_step": { "type": "string" }, "disclaimer": { "type": "string" } } }, "ConsultationRequest": { "type": "object", "required": [ "name", "email", "message", "consent_privacy" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "message": { "type": "string", "minLength": 10, "maxLength": 4000 }, "company": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "topic": { "type": "string", "maxLength": 100 }, "finder_share_code": { "type": "string", "maxLength": 40 }, "agent": { "type": "string", "maxLength": 100, "description": "Name of the AI assistant submitting." }, "consent_privacy": { "type": "boolean", "const": true, "description": "The person agreed to https://sw-cpas.co.kr/privacy/." }, "dry_run": { "type": "boolean", "default": false, "description": "Test mode: validate only, store and send nothing." } } }, "ConsultationDryRun": { "type": "object", "properties": { "dry_run": { "type": "boolean", "const": true }, "valid": { "type": "boolean" }, "would_submit": { "type": "object" }, "note": { "type": "string" } } }, "ConsultationReceived": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "const": "received" }, "request_id": { "type": [ "string", "null" ] }, "status_url": { "type": "string", "format": "uri" }, "message": { "type": "string" } } }, "ConsultationStatus": { "type": "object", "required": [ "request_id", "status" ], "properties": { "request_id": { "type": "string" }, "status": { "type": "string", "const": "received" }, "received_at": { "type": "string" }, "firm_notified": { "type": "boolean" }, "next_step": { "type": "string" } } }, "AskResult": { "type": "object", "properties": { "query_id": { "type": "string" }, "query": { "type": "object" }, "site": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "site": { "type": "string" }, "score": { "type": "number" }, "description": { "type": "string" }, "schema_object": { "type": "object" } } } } } } } } }