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

# Unit API 시작하기

> 신원 인증에 필요한 기능을 하나씩 골라 호출하는 Unit API의 호출 주소, 인증, 공통 요청·응답 규격, 과금 기준을 안내합니다.

Unit API는 신분증 OCR, 얼굴 비교, 기관 진위확인 같은 신원 인증 기능을 **하나씩 골라 호출하는 API**입니다. Liveform 제출 흐름을 거치지 않고, 필요한 확인만 서비스에 바로 붙일 수 있습니다.

* 호출 한 번이 결과 하나입니다. 제출건(submission)을 만들지 않습니다.
* 모든 호출은 **동기**로 처리됩니다. 결과는 응답으로 바로 받고, 웹훅은 없습니다.
* 결과가 나온 호출만 과금합니다. 오류로 결과가 나오지 않은 호출은 과금하지 않습니다.

> [card] [Unit API 레퍼런스](https://client-api.argosidentity.com/docs#ko/description/introduction)
>
> 모든 API의 요청·응답 명세를 확인하고, 언어별 호출 코드를 복사하고, OpenAPI 명세 파일을 내려받을 수 있습니다.

> [!TIP]
>
> 개발 없이 먼저 결과를 보려면 대시보드 **Unit API > API 테스트**에서 실행해 보세요. 실행 전에 호출 주소와 cURL 예시를 볼 수 있어, 그대로 복사해 연동을 시작할 수 있습니다. [대시보드 Unit API 안내](https://developers.argosidentity.com/dashboard/ko/unit-api.md)

***

## 제공 API

### 이미지·텍스트 분석

| API | Tx Code | 하는 일 | 결과 |
| - | - | - | - |
| [ID-OCR](https://developers.argosidentity.com/ko/idcheck/unit-api/id-ocr.md) | `ID_OCR` | 신분증 종류를 인식하고 기재 내용을 읽습니다 | 인식한 항목 |
| [ID-LIVE](https://developers.argosidentity.com/ko/idcheck/unit-api/id-live.md) | `ID_LIVE` | 신분증 이미지가 실물을 찍은 것인지 검사합니다 | 0\~100 점수 |
| [FACE-COM](https://developers.argosidentity.com/ko/idcheck/unit-api/face-com.md) | `FACE_COM` | 두 얼굴이 같은 사람인지 비교합니다 | 0\~1 유사도 |
| [FACE-LIVE-PSV](https://developers.argosidentity.com/ko/idcheck/unit-api/face-live-psv.md) | `FACE_LIVE_PSV` | 셀피 한 장이 실제 사람을 찍은 것인지 검사합니다 | 0\~100 점수 |
| [TXT-FZ-MAT](https://developers.argosidentity.com/ko/idcheck/unit-api/txt-fz-mat.md) | `TXT_FZ_MAT` | 두 이름이 얼마나 비슷한지 비교합니다 | 0\~100 유사도 |

### 외부 기관 조회

| API | Tx Code | 하는 일 | 조회 기관 |
| - | - | - | - |
| [GC-KOR-NID](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-nid.md) | `GC_KOR_NID` | 주민등록증 진위확인 | 행정안전부 |
| [GC-KOR-DRV](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-drv.md) | `GC_KOR_DRV` | 운전면허증 진위확인 | 경찰청 |
| [GC-KOR-PASS](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-pass.md) | `GC_KOR_PASS` | 대한민국 여권 진위확인 | 외교부 |
| [GC-KOR-ARC](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-arc.md) | `GC_KOR_ARC` | 외국인등록증 진위확인 | 법무부 |
| [GC-KOR-FPS](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-fps.md) | `GC_KOR_FPS` | 외국인 체류 확인 | 법무부 |
| [GC-KOR-BRS](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-brs.md) | `GC_KOR_BRS` | 사업자 상태 조회 | 국세청 |
| [GC-KOR-BIV](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-kor-biv.md) | `GC_KOR_BIV` | 사업자 진위확인 | 국세청 |
| [GC-MEX-CURP](https://developers.argosidentity.com/ko/idcheck/unit-api/gc-mex-curp.md) | `GC_MEX_CURP` | 멕시코 CURP 조회 | RENAPO |
| [BANK-KOR-AON](https://developers.argosidentity.com/ko/idcheck/unit-api/bank-kor-aon.md) | `BANK_KOR_AON` | 예금주명 조회 | 은행 |

외부 기관 조회는 기관의 답을 `verdict`(판정)와 `verdictReason`(판정 이유)으로 정리해 돌려줍니다. 판정을 읽는 방법은 [판정 읽기](#판정-읽기)를 참고하세요.

***

## 시작 순서

**1. Unit API 키 복사**

대시보드 **Unit API > Unit API 키**에서 키를 복사합니다. 프로젝트를 만들 때 자동으로 발급되므로 따로 신청할 필요가 없습니다. Member 이상 권한이 필요합니다.

**2. 대시보드에서 실행해 보기**

**API 테스트**에서 API를 골라 값을 넣고 실행합니다. 응답과 TX ID, 호출 주소, cURL 예시를 확인합니다.

**3. 서버에서 호출**

cURL 예시와 같은 요청을 서버에서 보냅니다. 키는 반드시 서버에서만 쓰세요.

**4. 결과와 TX ID 저장**

응답을 받는 즉시 결과와 `txId`를 시스템에 저장합니다. ARGOS는 요청·응답 본문을 저장하지 않습니다.

***

## 호출 주소

모든 Unit API는 `POST` 요청입니다. 프로젝트가 속한 리전의 호스트로 호출합니다.

| 리전 | 호스트 |
| - | - |
| US | `https://client-api.argosidentity.com` |
| KR | `https://kr.client-api.argosidentity.com` |

```text theme={null}
POST https://client-api.argosidentity.com/v1/units/{api}
```

* `{api}`는 각 API 페이지에 있는 경로입니다. 예: `/v1/units/id-ocr`
* 모든 리전에서 14종을 모두 쓸 수 있습니다.
* **키는 프로젝트의 리전에서만 통합니다.** 다른 리전 호스트로 호출하면 `401`이 돌아옵니다. 프로젝트 리전은 [리전 안내](https://developers.argosidentity.com/dashboard/ko/region.md)에서 확인하세요.

***

## 인증

요청 헤더 `x-api-key`에 프로젝트의 **Unit API 키**를 넣습니다.

```bash US theme={null}
curl -X POST "https://client-api.argosidentity.com/v1/units/txt-fz-mat" \
  -H "x-api-key: {yourUnitApiKey}" \
  -H "Content-Type: application/json" \
  -d '{"text1": "Hong Gildong", "text2": "Gildong Hong", "referenceId": "order-20261103-0001"}'
```

```bash KR theme={null}
curl -X POST "https://kr.client-api.argosidentity.com/v1/units/txt-fz-mat" \
  -H "x-api-key: {yourUnitApiKey}" \
  -H "Content-Type: application/json" \
  -d '{"text1": "Hong Gildong", "text2": "Gildong Hong", "referenceId": "order-20261103-0001"}'
```

> [!WARNING]
>
> Unit API 키는 Liveform API 키, 애드온 API 키와 다른 키입니다. 프로젝트마다 하나씩 발급됩니다. 키는 쿼리 스트링이 아니라 헤더로만 보내세요.

### 키 재발급

* 키가 노출됐거나 오남용이 의심되면 **Owner·Leader**가 대시보드에서 키를 재발급합니다.
* 재발급하면 **이전 키는 즉시 폐기**됩니다. 이전 키로 들어온 호출은 `401 INVALID_API_KEY`로 거절되고 과금되지 않습니다.
* 재발급한 사람과 시각은 키 발급 이력과 [이벤트 로그](https://developers.argosidentity.com/dashboard/ko/event.md)에 남습니다.

> [!WARNING]
>
> 프로젝트 설정의 **긴급 정지**는 Unit API 호출에 적용되지 않습니다. Unit API 호출을 막으려면 키를 재발급하세요.

***

## 요청 규칙

* 본문은 JSON으로 보내고 `Content-Type: application/json`을 붙입니다. 다른 타입은 `415 UNSUPPORTED_MEDIA_TYPE`으로 거절됩니다.
* **계약에 없는 필드를 보내면 `400 UNKNOWN_PARAMETER`로 거절됩니다.** 오타가 조용히 무시되어 엉뚱한 결과로 과금되는 일을 막기 위해서입니다.
* 빈 문자열(`""`)과 `null`은 값을 보내지 않은 것으로 보지 않고 `400 INVALID_PARAMETER_FORMAT`으로 거절합니다. 선택 필드는 값이 없으면 키째 빼고 보내세요.
* 날짜는 `YYYY-MM-DD` 형식입니다. 예: `2019-03-14`

### 이미지

* Base64 문자열로 보냅니다. `data:image/jpeg;base64,` 같은 접두어는 붙여도 되고 빼도 됩니다.
* **JPEG와 PNG만 받습니다.** iPhone HEIC, GIF, BMP 등은 JPEG로 변환해서 보내세요.
* 한 장당 원본 약 3 MB(접두어를 뺀 Base64 4,000,064자)까지 받습니다. 넘으면 `400 PARAMETER_OUT_OF_RANGE`입니다. 휴대폰으로 찍은 신분증 사진은 대부분 그대로 보낼 수 있습니다.

### referenceId

모든 API에서 선택 필드 `referenceId`를 받습니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `referenceId` | string, 1\~100자 | 직접 쓰는 식별자(주문번호, 회원번호 등). 응답에 그대로 돌아오고 호출 기록에 저장됩니다. **개인정보를 넣지 마세요.** |

호출마다 다른 값을 보내면, 응답을 받지 못한 호출도 나중에 찾을 수 있습니다. [중복 호출과 재시도](https://developers.argosidentity.com/ko/idcheck/unit-api/errors.md#중복-호출과-재시도)를 참고하세요.

***

## 공통 응답

성공(`200`) 응답은 모든 API가 같은 모양입니다. 호출을 설명하는 필드가 바깥에 있고, API가 만든 결과는 `data` 안에 있습니다.

```json theme={null}
{
  "txId": "01a17c3a-646f-762e-bb38-fe0cae059282",
  "txCode": "FACE_LIVE_PSV",
  "createdAt": "2026-11-03T07:19:24.015Z",
  "latencyMs": 812,
  "billing": {
    "unit": "response",
    "count": 1,
    "unitPrice": 0.08,
    "credit": 0.08,
    "pricingVersion": "v4.0_KOR"
  },
  "referenceId": "order-20261103-0001",
  "data": {
    "livenessScore": 93
  }
}
```

**txId** `string` *required*

이번 호출의 TX ID입니다. 대시보드 호출 내역 검색과 문의에 씁니다. 응답 헤더 `X-Tx-Id`와 같은 값입니다.

**txCode** `string` *required*

호출한 API의 코드입니다. 예: `ID_OCR`, `GC_KOR_NID`

**createdAt** `string` *required*

요청을 받은 시각입니다. 밀리초까지 표기한 UTC(RFC 3339)입니다.

**latencyMs** `integer` *required*

요청을 받아 응답하기까지 걸린 시간(ms)입니다.

**billing** `object` *required*

이번 호출의 과금 내역입니다.

**properties**

**unit** `string` *required*

세는 단위입니다. `recognition`(인식한 면), `pipeline`(검사), `compare`(비교), `response`(응답) 중 하나입니다.

**count** `integer` *required*

이번 호출에서 과금한 개수입니다.

**unitPrice** `number` *required*

개당 크레딧입니다. 소수 셋째 자리까지입니다.

**credit** `number` *required*

이번 호출에 차감한 크레딧입니다. 묶음 가격이 있는 API(ID-LIVE)는 `unitPrice × count`와 다를 수 있습니다.

**pricingVersion** `string` *required*

실제로 적용한 단가 기준입니다. `v3.1_USA`, `v4.0_KOR`, 체험(Trial) 프로젝트는 `Trial`입니다.

**referenceId** `string | null` *required*

요청에 보낸 `referenceId`입니다. 보내지 않았으면 `null`입니다.

**data** `object` *required*

API가 만든 결과입니다. 구조는 각 API 페이지를 참고하세요.

> [!NOTE]
>
> 정의된 응답 필드는 값이 없어도 생략하지 않고 `null`로 옵니다. 반대로 같은 `v1` 안에서도 **응답 필드와 enum 값은 늘어날 수 있으므로**, 모르는 필드나 값을 만나도 실패하지 않게 구현하세요. [버전 정책](https://developers.argosidentity.com/ko/idcheck/unit-api/errors.md#버전-정책)

### 판정 읽기

외부 기관 조회 API는 `data` 안에 아래 필드를 줍니다. GC-MEX-CURP만 예외로, 판정 없이 기관의 등록 상태를 그대로 줍니다.

| 필드 | 설명 |
| - | - |
| `verdict` | 판정. `MATCH`, `MISMATCH`, `REJECTED` 중 하나입니다. API마다 쓰는 값과 뜻이 조금씩 다르니 각 페이지를 확인하세요 |
| `verdictReason` | 판정 이유. `MATCH`면 `null`입니다. 다시 시도해서 결과가 달라질 수 있는지 이 값으로 가릅니다 |
| `agency` | 기관 응답 원문. **계약으로 보장하지 않습니다.** 기관이 필드를 바꾸면 예고 없이 달라지므로, 분기는 `verdict`·`verdictReason`으로 하세요 |

* `MATCH`: 기관 기록과 일치합니다.
* `MISMATCH`: 기관이 불일치로 답했습니다. **조회는 이루어졌으므로 과금됩니다.**
* `REJECTED`: 진본이지만 지금은 효력이 없습니다(효력을 잃은 여권, 휴업·폐업 사업자).

이미지·텍스트 분석 API는 점수와 측정값만 줍니다. **통과 여부를 가르는 기준은 직접 정하시면 됩니다.**

***

## 과금 기준

결과가 나온 호출만 크레딧이 차감됩니다. 차감한 크레딧은 응답의 `billing.credit`과 대시보드 호출 내역에서 확인할 수 있습니다.

* **결과가 나오면 차감됩니다.** 얼굴 유사도가 낮게 나오거나 기관이 불일치(`MISMATCH`)로 답해도 결과가 나온 것이므로 차감됩니다.
* **오류로 결과가 나오지 않으면 차감되지 않습니다.** HTTP 상태가 `200`이 아닌 모든 응답입니다.
* **대시보드 API 테스트로 실행한 호출도 같은 기준으로 차감됩니다.**
* **체험(Trial) 프로젝트는 차감되지 않습니다.** 대신 월 호출 수가 제한됩니다. [프로젝트 상태별 이용 범위](#프로젝트-상태별-이용-범위)
* 같은 요청을 두 번 보내면 두 건으로 처리하고 두 번 차감합니다.

### API별 단가

프로젝트의 요금제가 `v3.1_USA`이면 USA 단가, 그 밖의 요금제는 KOR 단가를 적용합니다. 단위는 크레딧입니다.

| API | 과금 단위 (`count`) | KOR 단가 | USA 단가 |
| - | - | :-: | :-: |
| ID-OCR | 인식한 면 수 (1\~2) | 면당 0.24 | 면당 0.32 · `universal`이고 발급 국가가 KOR이 아니면 면당 0.36 |
| ID-LIVE | 점수가 나온 검사 수 (1\~3) | 1개 0.07 · 2\~3개 0.14 | 1개 0.09 · 2\~3개 0.18 |
| FACE-COM | 1 | 0.01 | 0.06 |
| FACE-LIVE-PSV | 1 | 0.08 | 0.12 |
| TXT-FZ-MAT | 1 | 0.01 | 0.012 |
| GC-KOR-NID | 1 | 0.04 | 0.12 |
| GC-KOR-DRV | 1 | 0.04 | 0.12 |
| GC-KOR-PASS | 1 | 0.04 | 0.12 |
| GC-KOR-ARC | 1 | 0.04 | 0.12 |
| GC-KOR-FPS | 1 | 0.04 | 0.058 |
| GC-KOR-BRS | 1 | 0.01 | 0.012 |
| GC-KOR-BIV | 1 | 0.01 | 0.012 |
| GC-MEX-CURP | 1 | 0.09 | 0.09 |
| BANK-KOR-AON | 1 | 0.04 | 0.10 |

내 프로젝트에 적용되는 단가는 대시보드 **Unit API > API 테스트**에서도 확인할 수 있습니다.

***

## 프로젝트 상태별 이용 범위

| 프로젝트 상태 | 호출 | 한도 | 과금 |
| - | :-: | - | :-: |
| 서비스 (`OPEN`) | 가능 | 제한 없음 | O |
| 테스트 (`TEST`) | 가능 | 제한 없음 | O |
| 체험 (`TRIAL`) | 가능 | 월 10건 | - |
| 종료 (`CLOSE`) | 불가 | `403 ACCESS_FORBIDDEN` | - |

* 체험 한도는 **오류를 포함한 호출 수**로 셉니다. 차감되지 않은 오류 호출과 한도 초과로 거절된 호출도 포함됩니다.
* 한도는 매월 1일 00:00 UTC(한국시간 오전 9시)에 초기화됩니다.
* 한도를 넘기면 `429 TRIAL_LIMIT_EXCEEDED`가 돌아오고, `Retry-After` 헤더에 초기화까지 남은 초가 들어 있습니다.

***

## 데이터 보관과 개인정보

* **요청·응답 본문은 저장되지 않습니다.** 응답을 받는 즉시 결과를 `txId`와 함께 시스템에 저장해 두세요. ARGOS에서 결과를 다시 조회할 수 없습니다.
* **호출 기록은 3년간 보관됩니다.** 호출 시각, API, 결과, 오류 코드, 처리 시간, Count, 크레딧, 소스(라이브·API 테스트), 실행자, `referenceId`가 남습니다.
* 테스트라도 실제 개인정보를 넣으려면 정보주체의 동의 등 처리 근거가 있어야 합니다.

***

## 다음 단계

> [card] [오류 코드와 재시도](https://developers.argosidentity.com/ko/idcheck/unit-api/errors.md)
>
> 오류 응답 형식, 코드별 대응, 재시도 기준

> [card] [대시보드 Unit API](https://developers.argosidentity.com/dashboard/ko/unit-api.md)
>
> API 테스트, 호출 내역, 키 관리


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.