사업자 프로필 조회

무엇을 조회하나요

볼타가 공공 데이터를 모아 정리한 사업자 프로필을 검색하고 조회합니다. 거래처 등록 화면에서 사업자를 검색해 고르게 하거나, 사업자등록번호만 아는 거래처의 상호, 주소, 업종을 채울 때 쓰세요.

경로	용도
`GET /v1/businessProfiles:search`	상호, 대표자명, 사업자등록번호로 사업자 검색
`GET /v1/businessProfiles/{businessRegistrationNumber}`	사업자등록번호 한 건의 상세 프로필 조회

검색으로 사업자를 고른 뒤 상세를 조회하세요. 검색 결과에는 사업자를 가려낼 값만 있고, 대표자 실명, 주소, 연락처, 업종은 상세 조회 응답에 있습니다.

이용 조건

발급자 등록, 공동인증서, 요청자 관리번호(Bolta-Client-Reference-Id)가 필요 없고 구독 플랜 제한도 없습니다. Authorization 헤더에 Basic {apiKey}만 넣으면 됩니다. 인증은 인증 가이드를 참고하세요.

요금

경로	요금
검색	돌려준 결과 한 건마다 9포인트
상세 조회	조회 성공마다 90포인트

결과가 없는 검색, 상세 조회의 404, 오류 응답, 테스트 키 호출은 차감하지 않습니다.
다음 결과를 받는 호출도 받은 건수만큼 차감합니다. 한 번에 차감하는 포인트는 최대 limit × 9포인트입니다.
같은 사업자등록번호를 다시 조회하면 다시 차감합니다.
잔액이 받을 결과의 요금보다 적으면 API가 결과를 일부만 돌려주지 않고 402나 409를 반환합니다. 잔액이 적으면 limit을 줄여 호출하세요.
API는 조회 전에 잔액이 한 건 요금(검색 9포인트, 상세 조회 90포인트) 이상인지 확인합니다. 모자라면 결과와 관계없이 402나 409를 반환합니다.

검색

요청

curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3"

파라미터	필수	설명
`keyword`	O	검색어
`limit`	X	한 번에 받을 결과 수. 1 이상 50 이하, 기본값 20
`cursor`	X	이전 응답의 `nextCursor`. 받은 값을 그대로 보내세요
`excludeStatuses`	X	결과에서 뺄 사업자 등록 상태. `SUSPENDED`, `CLOSED`를 쉼표로 구분

keyword로 아래 값을 찾습니다.

상호, 이전 상호, 영문 상호
대표자명
상호 초성 3자 이상(예: ㅌㅅㅌ)
사업자등록번호 10자리. 하이픈을 넣어도 됩니다. 번호로 찾으면 그 사업자 한 건을 돌려줍니다

여러 단어를 띄어 쓰면 모든 단어가 일치하는 사업자를 찾습니다. 지역이나 업종 이름을 함께 넣어 결과를 좁히세요. 예를 들어 다온 강남은 강남구의 다온을 찾습니다. 검색어는 앞뒤 공백을 뺀 100자 이하, 공백과 기호를 뺀 2글자 이상으로 입력하세요. 주식회사처럼 법인 형태만 있는 검색어는 400 INVALID_REQUEST를 반환합니다. excludeStatuses는 휴업이나 폐업으로 확인된 사업자를 결과에서 뺍니다. 볼타가 상태를 확인하지 않은 사업자(registration이 null)와 NOT_REGISTERED, UNKNOWN 사업자는 결과에 남습니다. 거래 전에 상태를 확정하려면 사업자등록 상태 조회로 확인하세요.

입력	결과
생략	상태로 거르지 않음
`CLOSED`	폐업자 제외
`SUSPENDED,CLOSED`	휴업자와 폐업자 제외

빈 값, 같은 값의 중복, ACTIVE 같은 다른 값을 넣으면 API가 400 INVALID_REQUEST를 반환합니다.

응답

{
  "items": [
    {
      "businessRegistrationNumber": "1000000014",
      "organizationName": "테스트상사 주식회사",
      "representativeName": "김*타",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 강남구"
    },
    {
      "businessRegistrationNumber": "1000000028",
      "organizationName": "테스트상사 간이점",
      "representativeName": "이*스",
      "registration": { "status": "ACTIVE" },
      "region": "서울특별시 마포구"
    },
    {
      "businessRegistrationNumber": "1000000106",
      "organizationName": "테스트상사 세금계산서점",
      "representativeName": "박*의",
      "registration": { "status": "ACTIVE" },
      "region": "부산광역시 해운대구"
    }
  ],
  "nextCursor": "djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ",
  "hasMore": true
}

필드	형식	설명
`items`	array	검색 결과. 관련도가 높은 순
`items[].businessRegistrationNumber`	string	하이픈 없는 10자리 사업자등록번호
`items[].organizationName`	string 또는 null	상호
`items[].representativeName`	string 또는 null	가운데를 가린 대표자명
`items[].registration`	object 또는 null	볼타가 마지막으로 확인한 사업자 등록 상태. 확인한 적이 없으면 `null`
`items[].registration.status`	string	사업자 등록 상태
`items[].region`	string 또는 null	시도와 시군구 이름. 시군구를 모르면 시도만
`nextCursor`	string 또는 null	다음 결과를 받을 cursor. 마지막이면 `null`
`hasMore`	boolean	다음 결과가 있으면 `true`

모든 필드를 항상 담습니다. 값이 없으면 null이고, 결과가 없으면 items가 빈 배열입니다.

다음 결과 받기

hasMore가 true이면 nextCursor를 cursor에 넣어 다시 호출하세요. keyword와 excludeStatuses는 첫 요청과 같은 값을 보내고, limit은 바꿔도 됩니다.

curl -G https://xapi.bolta.io/v1/businessProfiles:search \
  -H "Authorization: Basic {apiKey}" \
  --data-urlencode "keyword=테스트상사" \
  -d "limit=3" \
  -d "cursor=djE6MDotOjM6MzFmN2UxZGI0NjJkMzVhMQ"

받은 결과가 limit보다 적어도 hasMore가 true일 수 있습니다. items의 개수가 아니라 hasMore를 보고 이어 호출하세요.

한 검색어로 받을 수 있는 결과는 앞 1,000건까지입니다. 더 필요하면 검색어를 구체적으로 바꾸세요.
cursor는 받을 때의 keyword, excludeStatuses, 키 모드(테스트, 라이브)에 묶입니다. 조건이 다르거나 cursor가 오래되면 API가 400 INVALID_CURSOR를 반환합니다. 이때는 cursor 없이 처음부터 다시 검색하세요.

상세 조회

요청

curl https://xapi.bolta.io/v1/businessProfiles/1000000014 \
  -H "Authorization: Basic {apiKey}"

경로에 사업자등록번호 10자리를 넣으세요. 100-00-00014처럼 하이픈을 넣어도 됩니다. API가 형식과 체크섬을 검증합니다. 10자리가 아니면 400 INVALID_REQUEST, 체크섬이 맞지 않으면 400 INVALID_BUSINESS_REGISTRATION_NUMBER를 반환합니다. 볼타에 프로필이 없는 번호는 404 NOT_FOUND를 반환합니다.

응답

{
  "businessRegistrationNumber": "1000000014",
  "corporateRegistrationNumber": "1101110000006",
  "businessKind": "CORPORATE",
  "commercialSalesNumber": "2021-서울강남-01234",
  "organizationName": "테스트상사 주식회사",
  "organizationNameEnglish": "Test Sangsa Co., Ltd.",
  "formerOrganizationNames": [
    { "name": "주식회사 테스트랩스", "changedOn": "2022-03-01" }
  ],
  "representativeName": "김볼타",
  "address": {
    "roadAddress": "서울특별시 강남구 가상로 1",
    "postalCode": "06236",
    "sidoCode": "11",
    "sigunguCode": "11680"
  },
  "contact": {
    "phone": "02-000-0000",
    "email": "hello@example.com",
    "websites": ["https://example.com"]
  },
  "industry": {
    "businessType": "서비스업",
    "businessItem": "응용 소프트웨어 개발",
    "standardIndustry": { "code": "58222", "name": "응용 소프트웨어 개발 및 공급업" },
    "category": { "code": "J", "name": "정보통신업" }
  },
  "openedOn": "2021-03-02",
  "businessRegisteredOn": "2021-03-02",
  "corporationEstablishedOn": "2021-02-25",
  "registration": {
    "status": "ACTIVE",
    "closedOn": null,
    "checkedAt": "2025-12-31T15:00:00Z"
  },
  "taxation": {
    "type": "GENERAL"
  }
}

모든 필드를 항상 담습니다. 값이 없으면 null이고, 목록은 빈 배열입니다.

식별

필드	형식	설명
`businessRegistrationNumber`	string	하이픈 없는 10자리 사업자등록번호
`corporateRegistrationNumber`	string 또는 null	하이픈 없는 13자리 법인등록번호
`businessKind`	string 또는 null	사업자 구분
`commercialSalesNumber`	string 또는 null	통신판매업 신고번호

상호와 대표자

필드	형식	설명
`organizationName`	string 또는 null	상호
`organizationNameEnglish`	string 또는 null	영문 상호
`formerOrganizationNames`	array	이전 상호. 최근에 바뀐 것부터
`formerOrganizationNames[].name`	string	이전 상호
`formerOrganizationNames[].changedOn`	string 또는 null	새 상호가 공시 자료에 처음 나타난 날. `YYYY-MM-DD` 형식. 변경 등기일과 다를 수 있음
`representativeName`	string 또는 null	대표자명. 원천 자료가 가려서 준 값은 가린 그대로

주소와 연락처

필드	형식	설명
`address`	object 또는 null	주소. 원천 자료에 주소가 없으면 `null`
`address.roadAddress`	string 또는 null	도로명주소
`address.postalCode`	string 또는 null	우편번호 5자리
`address.sidoCode`	string 또는 null	법정동 시도 코드 2자리
`address.sigunguCode`	string 또는 null	법정동 시군구 코드 5자리
`contact`	object	연락처. 항상 객체
`contact.phone`	string 또는 null	대표 전화번호. 하이픈을 넣은 형식
`contact.email`	string 또는 null	대표 이메일
`contact.websites`	array of string	홈페이지 주소

업종

필드	형식	설명
`industry`	object	업종. 항상 객체
`industry.businessType`	string 또는 null	업태. 국세청 등록 기준
`industry.businessItem`	string 또는 null	종목. 국세청 등록 기준
`industry.standardIndustry`	object 또는 null	한국표준산업분류(11차) 세세분류
`industry.standardIndustry.code`	string	세세분류 코드 5자리
`industry.standardIndustry.name`	string	세세분류 이름
`industry.category`	object 또는 null	한국표준산업분류 대분류
`industry.category.code`	string	대분류 코드. `A`부터 `U`까지
`industry.category.name`	string	대분류 이름

날짜

필드	형식	설명
`openedOn`	string 또는 null	개업일. `YYYY-MM-DD` 형식
`businessRegisteredOn`	string 또는 null	사업자등록일. `YYYY-MM-DD` 형식
`corporationEstablishedOn`	string 또는 null	법인설립일. `YYYY-MM-DD` 형식

세 날짜는 출처가 서로 달라 값이 다를 수 있습니다.

사업자 등록 상태

필드	형식	설명
`registration`	object 또는 null	볼타가 마지막으로 확인한 사업자 등록 상태. 확인한 적이 없으면 `null`
`registration.status`	string	사업자 등록 상태
`registration.closedOn`	string 또는 null	폐업일. `YYYY-MM-DD` 형식
`registration.checkedAt`	string	국세청에 확인한 시각. ISO 8601 UTC 형식
`taxation`	object 또는 null	마지막으로 확인한 과세 정보. 모르면 `null`
`taxation.type`	string	과세유형

상태값

사업자 구분

구분(`businessKind`)	뜻
`INDIVIDUAL`	개인사업자
`CORPORATE`	법인사업자

등록 상태와 과세유형

registration.status와 taxation.type의 값과 뜻은 사업자등록 상태 조회의 상태값과 같습니다. 처음 보는 값은 기타로 처리하세요. registration과 taxation은 볼타가 마지막으로 확인해 저장한 값이고, 확인한 시각은 registration.checkedAt에 있습니다. 호출 시점의 상태가 필요하면 사업자등록 상태 조회 API를 쓰세요.

테스트 키

테스트 키는 실제 사업자 데이터를 읽지 않고 고정된 모의 데이터를 돌려줍니다. 응답 구조는 라이브 키와 같고 포인트를 차감하지 않습니다.

상세 조회 테스트 번호

번호	`businessKind`	`registration.status`	`taxation.type`	비고
`1000000014`	`CORPORATE`	`ACTIVE`	`GENERAL`	모든 필드가 채워진 예시
`1000000028`	`INDIVIDUAL`	`ACTIVE`	`SIMPLIFIED_RECEIPT_ISSUER`
`1000000106`	`INDIVIDUAL`	`ACTIVE`	`SIMPLIFIED_TAX_INVOICE_ISSUER`
`1000000033`	`INDIVIDUAL`	`ACTIVE`	`TAX_FREE`
`1000000047`	`CORPORATE`	`ACTIVE`	`NONPROFIT`
`1000000052`	`CORPORATE`	`ACTIVE`	`UNIQUE_NUMBER_ORGANIZATION`
`1000000066`	`INDIVIDUAL`	`SUSPENDED`	`GENERAL`
`1000000071`	`INDIVIDUAL`	`CLOSED`	`GENERAL`	`registration.closedOn`은 2026년 1월 1일(고정)
`1000000085`	`INDIVIDUAL`	`NOT_REGISTERED`	null (`taxation`이 null)
`1000000090`	`INDIVIDUAL`	`UNKNOWN`	null (`taxation`이 null)
`1000000111`	`INDIVIDUAL`	null (`registration`이 null)	null (`taxation`이 null)	상태를 확인한 적 없는 예시. `address`도 `null`
`1000000125`	-	-	-	프로필이 없는 번호. `404 NOT_FOUND`

registration.checkedAt은 모두 2025-12-31T15:00:00Z(고정)입니다.
법인등록번호와 법인설립일은 businessKind가 CORPORATE인 번호에만 있습니다.
연락처, 영문 상호, 이전 상호, 통신판매업 신고번호는 1000000014에만 있습니다.
사업자등록 상태 조회의 테스트 번호와 같은 번호는 두 API가 같은 등록 상태와 과세유형을 돌려줍니다.

검색 테스트 데이터

모의 사업자 25곳이 있고 상호는 모두 테스트상사로 시작합니다. 위 표에서 프로필이 있는 11곳과 테스트상사 01호점부터 테스트상사 14호점까지 14곳입니다. 14곳은 개인 계속사업자이고 taxation.type은 GENERAL입니다. 테스트 키 검색은 상호에 검색어가 들어 있는 사업자와 사업자등록번호가 같은 사업자를 찾습니다. 대표자명, 초성, 지역 이름 검색은 라이브 키로 확인하세요.

keyword=테스트상사는 25곳을 모두 돌려줍니다.
limit=10으로 호출하면 nextCursor로 세 번에 나눠 받는 흐름을 시험할 수 있습니다.
excludeStatuses=SUSPENDED,CLOSED를 넣으면 1000000066과 1000000071이 빠집니다.
맞는 사업자가 없는 검색어는 빈 items를 돌려줍니다.

25곳 모두 상세 조회가 되고, 같은 번호의 검색 결과와 상세 응답은 값이 같습니다. 그 밖의 번호를 테스트 키로 상세 조회하면 API가 400과 INVALID_REQUEST를 반환합니다.

호출 한도

경로	한도
검색	1분에 120회
상세 조회	1분에 300회

한도는 결과 건수가 아니라 호출 횟수로 셉니다. 같은 파트너의 같은 모드 키는 한도를 함께 쓰고, 테스트 키와 라이브 키는 따로 셉니다. 한도를 넘으면 API가 429와 RATE_LIMITED를 반환하고 Retry-After 헤더에 재시도까지 남은 초를 담습니다. 그 시간만큼 기다린 뒤 다시 호출하세요.

오류

상태 코드	에러 코드	발생 조건
`400`	`INVALID_REQUEST`	`keyword` 누락이나 검색어 규칙 위반, 범위를 벗어난 `limit`, `excludeStatuses`의 빈 값, 중복, 받지 않는 값, 10자리가 아닌 사업자등록번호, 테스트 키의 목록 밖 번호 조회
`400`	`INVALID_BUSINESS_REGISTRATION_NUMBER`	상세 조회에서 체크섬이 맞지 않는 번호
`400`	`INVALID_CURSOR`	형식이 틀린 cursor, 받을 때와 검색 조건이나 키 모드가 다른 cursor, 오래된 cursor
`401`	-	API 키 인증 실패. 응답 본문 없음
`402`	`PAYMENT_REQUIRED`	포인트 잔액 부족. 개발자센터에서 충전하세요
`404`	`NOT_FOUND`	상세 조회에서 프로필이 없는 번호
`409`	`AVAILABLE_POINTS_INSUFFICIENT`	진행 중인 다른 요청 때문에 지금 쓸 수 있는 포인트 부족. 충전하거나 그 요청이 끝난 뒤 다시 요청하세요
`429`	`RATE_LIMITED`	호출 한도 초과. `Retry-After` 헤더 동반
`500`	`INTERNAL_SERVER_ERROR`	서버 내부 오류
`503`	`LOOKUP_UNAVAILABLE`	지금은 검색이나 조회를 할 수 없음. 잠시 후 다시 시도하세요
`503`	`SERVICE_UNAVAILABLE`	일시적인 내부 API 통신 오류

전체 에러 코드는 에러 코드를 참고하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

요금

검색

요청

응답

다음 결과 받기

상세 조회

요청

응답

식별

상호와 대표자

주소와 연락처

업종

날짜

사업자 등록 상태

상태값

사업자 구분

등록 상태와 과세유형

테스트 키

상세 조회 테스트 번호

검색 테스트 데이터

호출 한도

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​요금

​검색

​요청

​응답

​다음 결과 받기

​상세 조회

​요청

​응답

​식별

​상호와 대표자

​주소와 연락처

​업종

​날짜

​사업자 등록 상태

​상태값

​사업자 구분

​등록 상태와 과세유형

​테스트 키

​상세 조회 테스트 번호

​검색 테스트 데이터

​호출 한도

​오류

​관련 문서

무엇을 조회하나요

이용 조건

요금

검색

요청

응답

다음 결과 받기

상세 조회

요청

응답

식별

상호와 대표자

주소와 연락처

업종

날짜

사업자 등록 상태

상태값

사업자 구분

등록 상태와 과세유형

테스트 키

상세 조회 테스트 번호

검색 테스트 데이터

호출 한도

오류

관련 문서