---
title: "ARS API"
slug: "clova-ekyc-ars-api"
updated: 2026-09-17T09:10:00Z
published: 2026-09-17T09:10:00Z
canonical: "api-fin.ncloud-docs.com/clova-ekyc-ars-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-fin.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ARS API

ARS 인증 API 가이드입니다. API는 인증(verify)과 확인(confirm) 2단계로 나뉘어 있으며, 이용 이력 및 통계는 인증에서만 발생합니다.

## 인증 API

인증 단계에서 요청 및 응답을 설명합니다.

### 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| POST | /verify |

#### 요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA eKYC 요청 헤더](/docs/ai-application-service-ekyc#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

#### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | Required | 사용자가 지정한 요청 ID (10분간 재사용 불가) - 확인 API 호출 시 재사용 |
| `caller` | String | Required | 발신자 번호 - 미등록번호 발신 등 부정 이용 시 통신사에 의해 이용이 제한될 수 있음 - 8~11자리 |
| `phone` | String | Required | 수신자 번호 - 존재하지 않는 번호라도, API는 성공함 - Confrim API 로 결과 확인 가능 - 최대 11자 |
| `message` | String | Required | 인사 멘트 - 최대 150자이며, , : \| \n 는 허용하지 않음 |
| `verifyValue` | String | Required | 인증값 - 최대 6자 |
| `retry` | Boolean | Optional | 재시도 여부 - `true` \| `false` (기본값) - `true`: 인증값을 잘못 입력하거나 대기 시간을 초과하는 경우, 인사 멘트 재출력 - `false`: 인사 멘트를 다시 출력하지 않음 |

#### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/ars/verify' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001",
  "caller": "OOOOOOOOOOO",
  "phone": "OOOOOOOOOOO",
  "message": "안녕하세요",
  "verifyValue": "12345"
}'
```

### 응답

응답 형식을 설명합니다.

#### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | - | 사용자가 지정한 요청 ID |
| `uid` | String | - | 시스템에서 생성한 고유 ID |
| `timestamp` | Integer | - | 응답 시간(밀리초) - Unix Timestamp 형식 |
| `inferType` | String | - | 인증 유형 - `ARS` |
| `inferDetailType` | String | - | 상세 인증 유형 - `ARS` |
| `message` | String | - | 호출 결과 메시지 |

#### 응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA eKYC 응답 상태 코드](/docs/ai-application-service-ekyc#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

#### 응답 예시

응답 예시는 다음과 같습니다.

```
{
    "requestId": "request-001",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "message": "Success"
}
```

## 확인 API

확인 단계에서 요청 및 응답을 설명합니다.

### 요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

| 메서드 | URI |
| --- | --- |
| POST | /confirm |

#### 요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 [CLOVA eKYC 요청 헤더](/docs/ai-application-service-ekyc#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)를 참조해 주십시오.

#### 요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | Required | 사용자가 지정한 요청 ID - 인증 API 호출 시 사용했던 `requestId` |

#### 요청 예시

요청 예시는 다음과 같습니다.

```
curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/account/confirm' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001"
}'
```

### 응답

응답 형식을 설명합니다.

#### 응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `requestId` | String | - | 사용자가 지정한 요청 ID |
| `timestamp` | Integer | - | 응답 시간(밀리초) - Unix Timestamp 형식 |
| `uid` | String | - | 시스템에서 생성한 고유 ID |
| `inferType` | String | - | 인증 유형 - `ARS` |
| `inferDetailType` | String | - | 상세 인증 유형 - `ARS` |
| `result` | String | - | 호출 결과 - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: 호출 성공 - `FAILURE`: 호출 실패 (과금 발생) - `ERROR`: 호출 오류 (과금 미발생) |
| `code` | String | - | 4자리 에러 코드 |
| `message` | String | - | 호출 결과 메시지 |

#### 응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 [CLOVA eKYC 응답 상태 코드](/docs/ai-application-service-ekyc#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C)를 참조해 주십시오.

#### 응답 예시

응답 예시는 다음과 같습니다.

**성공**

```
{
    "requestId": "request-001",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "SUCCESS",
    "message": "Success"
}
```

**실패**

```
{
    "requestId": "request-002",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "FAILURE",
    "code": "3012",
    "message": "인증번호불일치 1회"
}
```

**오류**

```
{
    "requestId": "request-003",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "ERROR",
    "code": "3902",
    "message": "ARS 처리중입니다. 잠시후에 다시 조회하여 주십시오."
}
```