API 연동

◼ 기능 제공 요금제 : 엔터프라이즈

나인하이어 API

나인하이어 API는 채용과 관련된 정보를 제공하는 REST API입니다. 나인하이어 API를 통해 나인하이어에 등록한 채용 공고와 관련 정보를 외부 애플리케이션에서 연동해 보세요. 자사 채용 홈페이지나 사이트 위젯 등에서 실시간으로 채용 공고 정보를 제공하거나, 지원자 정보를 수집하고자 할 때, 나인하이어 API를 사용하실 수 있습니다.

API 인증하기

나인하이어 API를 사용하시기 위해서는 인증이 반드시 포함되어야 합니다. 나인하이어의 워크스페이스별로 발급되는 고유한 API 키를 사용하여 인증합니다.

API 키 발급받기

나인하이어에 접속하여 서비스 연동 > 데이터 > API 탭에서 [API 키 발급받기] 버튼을 클릭하여 인증 키를 발급받으실 수 있습니다. 발급받으신 API 키는 외부에 노출이 되지 않도록 주의하시기를 바랍니다. API 키를 새로 발급받으시는 경우 이전에 발급받은 키는 더이상 사용이 불가능합니다.

API 인증 방식

API 요청 시 발급받은 API 키를 Authorization 헤더에 포함하여 인증해 주세요. API 키는 소스코드에 배포되거나 외부에 노출되지 않도록 주의하여 주시기 바랍니다.

Authorization: Bearer {API_KEY}

API 응답

API의 응답 성공 여부는 HTTP 상태 코드로 전달되어 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구현하실 수 있습니다. 모든 API 응답, 요청 본문(body)은 JSON 포맷, 헤더는 Content-Type: application/json 으로 전달합니다.

HTTP 상태 코드

코드	에러 메시지	설명
401	authentication expired	인증키가 만료되었습니다.
404	resource is not founded	요청한 리소스를 찾을 수 없습니다.
403	not authorized	인증이 올바르지 않습니다.
500	Internal Server Error	서버 에러가 발생하였습니다.

채용 API

채용 공고 목록 조회 API

GET https://api.ninehire.com/api/v1/jobs

[예시]
curl --request GET \
     --url 'https://api.ninehire.com/api/v1/jobs?countPerPage=10&page=1' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer hOmYWFFSwjefmEIwdWeWdQaldEid'

요청 파라미터

필드	타입	필수여부	설명
page	int	optional	페이지 번호입니다. 기본값은 1입니다.	Query
countPerPage	int	optional	페이지당 반환되는 아이템의 갯수입니다. 기본값은 10이며 최대 100개로 제한됩니다.	Query
title	string	optional	검색하고자 하는 공고의 제목입니다.	Query
tags	string[]	optional	검색하고자 하는 공고의 태그명입니다. 복수 개인 경우 or 조건으로 검색합니다.	Query
jobGroup	string	optional	검색하고자 하는 공고의 직군명입니다.	Query
employmentType	string	optional	검색하고자 하는 공고의 고용 형태입니다. full_time : 정규직 contractor : 계약직 intern : 인턴 part_time : 아르바이트 freelancer : 프리랜서 dispatched : 파견직 day_labor : 일용직 trainee : 교육생	Query
affiliation	string	optional	검색하고자 하는 공고의 소속명입니다.	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: 마감 또는 모집 중단 상태의 채용 공고를 포함하여 조회합니다. false : 지원자가 열람 가능한 공고만 조회합니다. (모집 가능 상태의 채용 공고 또는 상시노출 채용의 공고) 기본값은 false 입니다.	Query
includePrivate	boolean	optional	비공개 공고를 포함하여 조회합니다. true: 비공개 공고를 포함하여 조회합니다. false : 비공개 공고를 제외하고 조회합니다. 기본값은 false 입니다.	Query

적절한 쿼리를 사용하여 주세요. 채용 공고 목록 조회 시 쿼리를 이용하여 원하는 결과만 조회하시기를 권장드립니다.

응답 예시

{
  "count": 1,
  "results": [
    {
      "id": "2a2b0410-9b94-11ec-8ede-03ca65ff806e",
      "title": "React 웹 프론트엔드 개발자",
      "deadline": "2023-02-28T00:00:00.905Z",
			"url": "https://career.ninehire.com/job_posting/3ETue9oP/apply",
      "tags": ["프론트엔드"],
      "career": "irrelevant",
      "employmentTypes": ["full_time"],
      "jobLocations": [
        {
          "x": 129.124507082939,
          "y": 35.175163705055,
          "name": "부산지사",
          "address": "부산 해운대구 센텀중앙로 97",
        }
      ],
      "jobGroup": "개발팀",
      "jobTask": "프론트엔드",
      "affiliation": "나인하이어"
    }
  ]
}

응답 객체(result)

키	타입	비고	설명
id	string		공고별 고유한 ID 값입니다.
title	string		공고명 입니다.
title_english	string	nullable	공고명(영문) 입니다.
applyUrl	string		지원하기 페이지 URL 입니다.
deadline	string(datetime)	nullable	마감 기한 입니다. 상시 채용인 경우 null 입니다.
tags	string[]		공고의 태그 정보입니다.
career	string	nullable	공고의 경력 사항 정보입니다. irrelevant : 경력 무관 experienced : 경력 newcomer : 신입
employmentTypes	string[]		공고의 고용 형태 정보입니다. full_time : 정규직 contractor : 계약직 intern : 인턴 part_time : 아르바이트 freelancer : 프리랜서 dispatched : 파견직 day_labor : 일용직 trainee : 교육생
jobLocations	object[]		공고의 근무지 정보입니다. (JobLocation Array)
jobGroup	string	nullable	공고의 직군 정보입니다.
jobTask	string	nullable	공고의 직무 정보입니다.
affiliation	string	nullable	공고의 소속 정보입니다.
createdAt	string(datetime)		공고의 생성일 입니다.
isPrivate	boolean		공고의 공개/비공개 여부입니다.
status	string		공고의 상태입니다. in_progress: 모집 중, 채용 진행중 disabled: 모집 중단, 채용 진행중 closed: 모집 중단, 채용 마감됨 archived: 모집 중단, 채용 보관됨

채용 공고 상세 조회 API

GET https://api.ninehire.com/api/v1/jobs/{jobId}

[예시]
curl --request GET \
     --url 'https://api.ninehire.com/api/v1/jobs/2a2b0410-9b94-11ec-8ede-03ca65ff806e' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer hOmYWFFSwjefmEIwdWeWdQaldEid'

필드	타입	필수여부	설명
jobId	string	required	공고 ID 값입니다.	Path
language	string	optional	언어 설정입니다. 기본값은 한국어 입니다. korean : 한국어 english : 영어	Query

응답 예시

{
  "id": "2a2b0410-9b94-11ec-8ede-03ca65ff806e",
  "title": "React 웹 프론트엔드 개발자",
  "coverImageUrl": "https://cdn.ninehire.com/dev/ninehire_logo.png",
  "content": "<p><strong>프론트엔드 개발자 채용</strong></p>",
	"isActive": true,
	"applyUrl": "https://career.ninehire.com/job_posting/3ETue9oP/apply",
  "deadline": "2023-02-28T05:09:14.905Z",
  "tags": ["프론트엔드"],
  "career": "irrelevant",
  "employmentType": ["full_time"],
  "jobLocations": [
    {
      "x": 129.124507082939,
      "y": 35.175163705055,
      "name": "부산지사",
      "address": "부산 해운대구 센텀중앙로 97",
    }
  ],
  "jobGroup": "개발팀",
  "jobTask": "프론트엔드",
  "affiliation": "나인하이어"
}

응답 객체

키	타입	비고	설명
id	string		공고별 고유한 ID 값입니다.
title	string		공고명 입니다.
title_english	string	nullable	공고명(영문) 입니다.
cover	string	nullable	공고의 커버 이미지 URL 입니다.
cover_english	string	nullable	공고의 커버 이미지(영문) URL 입니다.
content	string	nullable	공고의 상세 내용 입니다.
content_english	string	nullable	공고의 상세 내용(영문) 입니다.
applyUrl	string		지원하기 페이지 URL 입니다.
isActive	boolean		공고 활성화 여부입니다.
deadline	string(datetime)	nullable	마감 기한 입니다.
tags	string[]		공고의 태그 정보입니다.
career	string	nullable	공고의 경력 사항 정보입니다. irrelevant : 경력 무관 experienced : 경력 newcomer : 신입
employmentTypes	string[]		공고의 고용 형태 정보입니다. full_time : 정규직 contractor : 계약직 intern : 인턴 part_time : 아르바이트 freelancer : 프리랜서 dispatched : 파견직 day_labor : 일용직 trainee : 교육생
jobLocations	object[]		공고의 근무지 정보입니다. (JobLocation Array)
jobGroup	string	nullable	공고의 직군 정보입니다.
jobTask	string	nullable	공고의 직무 정보입니다.
affiliation	string	nullable	공고의 소속 정보입니다.
createdAt	string(datetime)		공고의 생성일 입니다.
isPrivate	boolean		공고의 공개/비공개 여부입니다.
status	string		공고의 상태입니다. in_progress: 모집 중, 채용 진행중 disabled: 모집 중단, 채용 진행중 closed: 모집 중단, 채용 마감됨 archived: 모집 중단, 채용 보관됨

JobLocation

키	타입	비고	설명
x	double	nullable	근무지 주소의 x 좌표입니다.
y	double	nullable	근무지 주소의 y 좌표입니다.
name	string		근무지명 입니다.
address	string		근무지 주소 입니다.