버전

메서드

경로

설명

v1

GET

/jobs

포지션 목록 조회

v1

GET

/jobs/{jobId}

포지션 상세 조회

v1

GET

/job-groups

직군 목록 조회

v1

GET

/locations

근무지 목록 조회

v1

GET

/affiliations

소속 목록 조회

v1

GET

/applicants

포지션별 지원자 목록 조회

v1

POST

/applicant

포지션에 지원자 등록

v2

GET

/jobs

포지션 목록 조회 (포지션 상태·접수 상태 분리)

v2

GET

/jobs/{jobId}

포지션 상세 조회 (포지션 상태·접수 상태 분리)

항목

내용

프로토콜

HTTPS

조회(GET) 파라미터

URL 쿼리 문자열. 배열 파라미터는 같은 키를 반복합니다. (예: ?tags=개발&tags=디자인)

등록(POST) 본문

Content-Type: application/json, UTF-8

불리언 쿼리 값

문자열 true일 때만 참으로 처리되며, 그 외 값은 거짓으로 처리됩니다.

정의되지 않은 쿼리 파라미터

무시됩니다.

구분

형식

예시

적용 필드

일시

ISO 8601, UTC, 밀리초 포함

2026-10-20T01:23:45.678Z

createdAt, deadline, appliedAt, updatedAt, 학력·경력 등 지원서의 날짜 필드

날짜

YYYY-MM-DD (한국 시간 기준)

1995-03-15

지원자 생년월일(birthday)

API

page 기본값

countPerPage 기본값

countPerPage 최대값

포지션 목록 조회 (v1·v2)

1

10

100 (초과 값은 100으로 처리)

지원자 목록 조회

1

10

100 (초과 값은 100으로 처리)

직군·근무지·소속 목록 조회

1

20

별도 상한 없음 (100 이하 권장)

코드

의미

발생 조건

400

필수 파라미터 누락

지원자 목록 조회에 jobId가 없음

401

인증 실패

Authorization 헤더가 없거나 Bearer {API 키} 형식이 아님, 유효하지 않은 키, 등록된 키와 일치하지 않는 키

404

등록된 키 없음

삭제되었거나 재발급으로 교체된 키로 호출

404

리소스 없음

조회·등록 대상 포지션이 없거나 삭제됨, 포지션에 전형 단계가 없음, 워크스페이스 개인정보 보호 설정을 찾지 못함, 정의되지 않은 경로로 호출

422

파일명 확장자 없음

지원자 등록 시 documents[].filename이 확장자로 끝나지 않음

429

요청 한도 초과

워크스페이스 또는 IP 기준 요청 한도 초과 (오류 코드 000132)

500

서버 오류

처리 중 예기치 못한 오류 (요청 본문 구조가 명세와 다른 경우 포함)

HTTP 상태

본문 구조

400, 401, 422, 500

{ "message": string }

404(리소스 없음), 429

{ "message": string, "code": string, "detail": string }

404(정의되지 않은 경로)

{ "statusCode": 404, "message": string, "error": "Not Found" }

제한

기준

한도

워크스페이스 한도

API 키로 인증된 워크스페이스

60초에 60회

IP 한도

요청을 보낸 IP

60초에 120회

필드

타입

필수여부

설명

위치

page

int

optional

페이지 번호입니다. 기본값은 1입니다.

Query

countPerPage

int

optional

페이지당 불러올 아이템의 갯수입니다. 기본값은 10이며 최대 100개로 제한됩니다.

Query

title

string

optional

공고 제목 부분 일치로 검색합니다. 국문 제목과 영문 제목 모두에서 검색합니다.

Query

tags

string[]

optional

태그명(국문)과 정확히 일치하는 공고를 검색합니다. 여러 개 지정 시 하나라도 일치하면 포함됩니다. (예: tags=개발&tags=신입)

Query

jobGroup

string

optional

직군명(국문)과 정확히 일치하는 공고를 검색합니다. 직군명은 8. 직군·근무지·소속 조회 API로 확인할 수 있습니다.

Query

employmentType

string

optional

검색하고자 하는 공고의 고용 형태입니다. 1개만 지정할 수 있습니다.
full_time: 정규직
contractor: 계약직
intern: 인턴
part_time: 아르바이트
freelancer: 프리랜서
dispatched: 파견직
day_labor: 일용직
trainee: 교육생

Query

affiliation

string

optional

소속명(국문)과 정확히 일치하는 공고를 검색합니다. 소속명은 8. 직군·근무지·소속 조회 API로 확인할 수 있습니다.

Query

order

string

optional

반환되는 아이템의 정렬 방식입니다. 기본값은 최신순입니다.
created_at_desc: 최신순
created_at_asc: 오래된 순
deadline_asc: 마감일 빠른 순 (마감일이 없는 공고는 뒤로)
title_asc: 국문 공고 제목 오름차순
title_desc: 국문 공고 제목 내림차순

Query

language

string

optional

언어 설정값입니다. 기본값은 한국어입니다.
(선택한 언어별로 등록된 값을 반환합니다. 해당 언어로 등록된 내용이 없는 경우 기본으로 한국어 값을 반환합니다. 필터와 정렬은 언어 설정과 관계없이 국문 값을 기준으로 동작합니다.)
korean: 한국어
english: 영어

Query

includeUnpublished

boolean

optional

보관된 포지션을 포함해 조회합니다.
true: 보관(archived) 포지션을 포함합니다.
false: 보관 포지션을 제외합니다.
기본값은 false입니다.

Query

includePrivate

boolean

optional

채용 홈페이지 목록 노출이 꺼진 포지션을 포함해 조회합니다.
true: 목록 노출이 꺼진 포지션을 포함합니다.
false: 목록 노출이 켜진 포지션만 조회합니다.
기본값은 false입니다.

Query

키

타입

비고

설명

id

string

공고별 고유한 ID 값입니다.

title

string

공고 제목(외부 노출용)입니다. language=english이면 영문 제목을 우선 반환합니다.

applyUrl

string

나인하이어 채용 홈페이지의 공고 페이지 URL입니다. (https://{채용 사이트 주소}.ninehire.site/job_posting/{공고 키})

deadline

string(datetime)

nullable

접수 마감 일시입니다. 접수 중에는 설정된 마감 예정 일시이며, 접수를 마감(수동·예약·마감일 도래)하거나 포지션을 종료하면 처리된 시각이 기록됩니다. 마감 일시가 없으면 null이며, 상시 채용이어도 값이 있을 수 있습니다.

deadlineType

string

마감 방식입니다.
open_ended: 상시 채용
until_filled: 채용 시 마감
custom_deadline: 마감일 지정
접수 기간이 설정되지 않은 포지션도 open_ended로 표시됩니다.

tags

string[]

공고의 태그 정보입니다. language=english이면 영문 태그를 우선 반환합니다.

career

string

nullable

공고의 경력 사항 정보입니다.
irrelevant: 경력 무관
experienced: 경력
newcomer: 신입

careerRange

object

nullable

경력 연차 범위입니다. 경력 구분이 없으면 null입니다.
over: N년 이상
below: N년 이하

employmentTypes

string[]

공고의 고용 형태 정보입니다.
full_time: 정규직
contractor: 계약직
intern: 인턴
part_time: 아르바이트
freelancer: 프리랜서
dispatched: 파견직
day_labor: 일용직
trainee: 교육생

jobLocations

object[]

공고의 근무지 정보입니다.
(JobLocation Array, 6. 포지션 상세 조회 API 하단 참고)

jobGroup

string

nullable

공고의 직군 정보입니다.

jobTask

string

nullable

공고의 직무 정보입니다.

affiliation

string

nullable

공고의 소속 정보입니다.

createdAt

string(datetime)

공고의 생성일 입니다.

isPrivate

boolean

채용 홈페이지 목록 미노출 여부입니다. 목록 노출이 꺼져 있으면 true입니다.

status

string

포지션 상태입니다.
in_progress: 진행 중(접수 열림). 지원서를 받는 상태
disabled: 닫힘(접수 닫힘). 포지션은 진행 중이지만 지원서를 받지 않는 상태(접수 시작 전, 접수 마감, 종료 취소 시)
closed: 종료. 종료하면 채용 홈페이지 목록 노출과 공고 사용이 꺼짐
archived: 보관
임시 저장(draft)·승인 대기(waiting_approval) 포지션은 목록에 포함되지 않습니다.

필드

타입

필수여부

설명

위치

jobId

string

required

포지션 ID입니다. 포지션 목록 조회 응답의 id 또는 나인하이어 → 채용 상세 페이지의 [채용 ID 복사]로 확인할 수 있습니다.

Path

language

string

optional

언어 설정입니다. 기본값은 한국어 입니다.
(선택한 언어별로 등록된 값을 반환합니다. 해당 언어로 등록된 내용이 없는 경우 기본으로 한국어 값을 반환합니다. 영문 우선 적용 항목은 제목·태그·직군·직무·소속·근무지·커버 이미지·본문입니다.)
korean: 한국어
english: 영어

Query

키

타입

비고

설명

layoutType

string

공고 레이아웃 유형입니다.
layout1: 레이아웃 1
layout2: 레이아웃 2

coverImageUrl

string

nullable

공고 커버 이미지 URL입니다. 커버 이미지가 없으면 null이며, 만료되지 않는 이미지 주소입니다.

content

string

nullable

공고 본문입니다. (HTML 문자열)

isActive

boolean

공고 사용(게시) 여부입니다. 포지션을 종료하거나 종료를 취소하면 자동으로 false가 됩니다.

키

타입

비고

설명

x

double

nullable

근무지 좌표 X(경도)입니다.

y

double

nullable

근무지 좌표 Y(위도)입니다.

name

string

근무지명 입니다. language=english이면 영문 이름을 우선 반환합니다.

address

string

국문 응답에서는 근무지 이름(name)과 같은 값입니다. language=english이면 영문 주소가 있을 때 영문 주소를 반환합니다. 실제 근무지 주소가 필요하면 8. 직군·근무지·소속 조회 API의 근무지 목록 조회 응답(address)을 사용해 주세요.

구분

v1

v2

포지션 진행 상태

status

positionStatus

접수 상태

status가 in_progress인지로 판단

receptionStatus, reception.canSubmit

접수 기간

deadline (마감 일시만)

reception.startAt, reception.endAt

마감 방식

deadlineType (기간 미설정도 open_ended)

reception.deadlineType (기간 미설정은 none)

채용 홈페이지 목록 노출

isPrivate (미노출이면 true)

isListExposed (노출이면 true)

목록 노출이 꺼진 포지션 포함 조회

includePrivate

includeHidden

키

타입

비고

설명

status

string

포지션 상태입니다. v1과 같은 값입니다.

positionStatus

string

nullable

포지션 진행 상태입니다.
in_progress: 진행 중 (v1 status가 in_progress 또는 disabled)
closed: 종료
archived: 보관
임시 저장·승인 대기 포지션은 null입니다.

receptionStatus

string

접수 상태입니다.
open: 접수 열림 (v1 status가 in_progress)
closed: 접수 닫힘 (그 외 모든 상태)

reception.startAt

string(datetime)

nullable

접수 시작 일시입니다. 접수를 바로 시작하면 시작한 시각, 시작을 예약하면 예약한 일시이며, 접수를 마감한 뒤에도 유지됩니다.

reception.endAt

string(datetime)

nullable

접수 마감 일시입니다. v1 deadline과 같은 값입니다.

reception.deadlineType

string

마감 방식입니다.
open_ended: 상시 채용
until_filled: 채용 시 마감
custom_deadline: 마감일 지정
none: 기간 미설정

reception.canSubmit

boolean

지원서 제출 가능 여부입니다. status가 in_progress이면 true입니다.

isListExposed

boolean

채용 홈페이지 목록 노출 여부입니다.

필드

타입

필수여부

설명

위치

title

string

optional

직군명 부분 일치로 검색합니다. (국문·영문 모두)

Query

page

int

optional

페이지 번호입니다. 기본값은 1입니다.

Query

countPerPage

int

optional

페이지당 불러올 아이템의 개수입니다. 기본값은 20입니다.

Query

키

타입

비고

설명

title

string

직군명(국문)입니다. 포지션 목록 조회의 jobGroup 필터 값으로 사용합니다.

title_english

string

nullable

직군명(영문)입니다.

필드

타입

필수여부

설명

위치

name

string

optional

근무지 이름 또는 주소 부분 일치로 검색합니다. (국문)

Query

page

int

optional

페이지 번호입니다. 기본값은 1입니다.

Query

countPerPage

int

optional

페이지당 불러올 아이템의 개수입니다. 기본값은 20입니다.

Query

키

타입

비고

설명

x

number

nullable

근무지 좌표 X(경도)입니다.

y

number

nullable

근무지 좌표 Y(위도)입니다.

name

string

근무지 이름(국문)입니다.

name_english

string

nullable

근무지 이름(영문)입니다.

address

string

nullable

근무지 주소(국문)입니다.

필드

타입

필수여부

설명

위치

title

string

optional

소속명 부분 일치로 검색합니다. (국문·영문 모두)

Query

page

int

optional

페이지 번호입니다. 기본값은 1입니다.

Query

countPerPage

int

optional

페이지당 불러올 아이템의 개수입니다. 기본값은 20입니다.

Query

키

타입

비고

설명

title

string

소속명(국문)입니다. 포지션 목록 조회의 affiliation 필터 값으로 사용합니다.

title_english

string

nullable

소속명(영문)입니다.

필드

타입

필수여부

설명

위치

jobId

string

required

지원자의 포지션 ID입니다.
목록 조회에 필요한 jobId는 포지션 목록 조회 API 응답의 id 필드 또는 나인하이어 → 채용 상세 페이지의 [채용 ID 복사]를 통해 확인하실 수 있습니다.

Query

page

int

optional

페이지 번호입니다. 기본값은 1입니다.

Query

countPerPage

int

optional

페이지당 반환되는 아이템의 개수입니다. 기본값은 10이며 최대 100개로 제한됩니다.

Query

status

string[]

optional

지원자의 상태입니다.
복수 개인 경우 or 조건으로 검색합니다. (예: status=passed&status=failed)
progressing: 진행 중. 불합격 처리되지 않았고 현재 최종 합격 단계가 아닌 지원자
passed: 최종 합격. 현재 최종 합격 단계에 있는 지원자
failed: 불합격. 불합격 처리된 지원자

Query

필드

타입

필수여부

설명

파라미터 타입

jobId

string

required

등록할 포지션 ID입니다. (포지션 목록 조회 응답의 id)

Body

applicant

object

required

등록할 지원자 정보입니다. (Applicant Object)

Body

sendNotification

boolean

optional

지원자에게 지원 접수 안내 메시지를 발송할지 여부입니다. 생략하면 false로 처리됩니다.

Body

키

타입

비고

설명

name

string

required

지원자의 이름입니다. (30자 이내 권장)

email

string

권장

지원자의 이메일입니다. (이메일 형식, 200자 이내 권장)

phoneNumber

string

권장

지원자의 연락처입니다. (숫자 형식, 30자 이내 권장) 보낸 문자열 그대로 저장됩니다.

applyPath

string

권장

지원자의 지원 경로입니다. (100자 이내 권장, 예: 헤드헌팅) 지원자 목록 조회 시 source로 반환됩니다.

appliedAt

string

optional

지원자의 접수일입니다. 미입력 시 요청 처리 시각으로 설정됩니다.
(ISO 8601 일시, 예: 2026-10-20T09:00:00+09:00)

documents

object[]

required

지원자 서류 제출 정보입니다. (Document Array)
첨부할 문서가 없으면 빈 배열 []을 보내 주세요.

키

타입

비고

설명

fileUrl

string

required

제출 서류의 URL입니다. 나인하이어 서버가 인증 없이 내려받을 수 있는 URL이어야 합니다.

filename

string

required

제출 서류의 파일명입니다. (확장자 포함, 예: 홍길동_이력서.pdf)

대상

규칙

위반 시

documents[].filename

영문 또는 숫자로 된 확장자(.pdf 등)로 끝나야 합니다. (대소문자 무시)

422, 지원자가 등록되지 않음

documents

배열이어야 합니다. (빈 배열 허용)

누락 시 500

jobId

존재하고 삭제되지 않은 포지션이어야 합니다.

404

HTTP

권장 처리

400, 422

요청 값을 수정한 뒤 다시 요청 (같은 요청으로 재시도하지 않음)

401

API 키 값과 헤더 형식 확인 (재시도하지 않음)

404 (등록된 키 없음)

API 키가 삭제·교체된 상태이므로 새 키로 설정 교체

404 (그 외)

대상 ID 확인

429

대기 후 재시도

500

잠시 후 제한적으로 재시도. 지원자 등록 API는 재시도 전 등록 여부를 먼저 확인