Global ID Recognition API - ARGOS Identity

POST

recognition

Recognize and verify ID document

curl --request POST \
  --url https://idverify-api.argosidentity.com/modules/recognition \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "idImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "issuingCountry": "USA",
  "idType": "government_id",
  "idBackImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "callbackUrl": "https://your-domain.com/callback"
}
'

{
  "apiType": "id_recognition",
  "transactionId": "e0nvom3caiis7",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADDRESS 110, SOMEWHERE STREET",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  }
}

Global ID Recognition API는 ID의 앞면과 뒷면 이미지, 발급 국가 및 ID 유형을 분석하여 신분증을 처리하고 검증합니다. 이 API는 상세한 OCR(광학 문자 인식)을 통해 제공된 ID의 진위성과 유효성을 보장하며 포괄적인 결과를 제공합니다.

API 개요

Global ID Recognition API는 전 세계 ID 문서 처리를 위한 강력한 도구로 다음과 같은 기능을 제공합니다:

전 세계 지원: 여러 국가의 ID 문서 처리
자동 인식: ID 유형과 발급 국가를 자동으로 감지
OCR 기술: 텍스트 추출을 위한 고급 광학 문자 인식
데이터 추출: ID 문서에서 구조화된 데이터 추출
검증: 문서의 진위성과 유효성 검증
다중 형식 지원: 다양한 ID 문서 형식 처리

요청 매개변수

필수 매개변수

idImage: base64 형식의 ID 문서 앞면 이미지
issuingCountry: ID 문서 발급 국가의 ISO 3 Alpha 국가 코드
idType: ID 문서의 유형

선택적 매개변수

idBackImage: base64 형식의 ID 문서 뒷면 이미지
callbackUrl: 인식 결과가 완료 시 전송될 URL

인증

x-api-key: 인증 및 접근 제어를 위한 필수 API 키

응답 형식

API는 다음과 같은 상세한 인식 결과를 반환합니다:

apiType: API 유형 식별자
transactionId: 각 요청에 대한 고유 식별자
result: 처리 결과를 포함하는 객체
- documentInfo: 추출된 문서 정보
- personalInfo: 추출된 개인 정보
- verificationStatus: 문서 검증 상태
- data: 추출된 데이터 객체
  - raw: 원본 OCR 데이터 및 좌표 정보
    - 각 필드(address, name, number, authority 등)는 다음을 포함할 수 있습니다:
      - value: 추출된 필드 값 (string)
      - score: 인식 신뢰도 점수 (number)
      - accepted: 필드 수락 여부 (boolean, 일부 필드에만 존재)
      - coordinates: 처리된 이미지 기준의 좌표 정보 (object)
        
        first, second, third, fourth: 사각형의 네 모서리 좌표점 (x, y)
      - original_coordinates: 신분증 사진 촬영 시 원본 이미지 기준의 좌표 정보 (object, 선택적)
        
        first, second, third, fourth: 원본 이미지 기준의 네 모서리 좌표점 (x, y)
        
        뒷면에 원본 좌표 정보가 있는 경우 해당 필드에 추가로 제공됩니다
  - ocr: 아르고스가 정의해둔 구조화된 OCR 데이터

지원되는 국가 및 ID 유형

주요 국가들

USA: 미국
CAN: 캐나다
MEX: 멕시코
BRA: 브라질
ARG: 아르헨티나
GBR: 영국
DEU: 독일
FRA: 프랑스
ESP: 스페인
ITA: 이탈리아
KOR: 대한민국
JPN: 일본
CHN: 중국
AUS: 호주
NZL: 뉴질랜드

각 국가별로 지원되는 모든 신분증 유형 목록은 용어집/지원되는 신분증 유형에서 확인하세요.

ID 유형

government_id: 정부에서 발급한 공식 신분증으로, 개인의 신원을 확인하는 데 사용됩니다
passport: 정부에서 발급한 공식 여행 문서로, 소지자의 신원과 국적을 인증하며 주로 국제 여행에 사용됩니다
drivers_license: 특정 개인이 오토바이, 자동차, 트럭 또는 버스와 같은 모터화된 차량을 운전할 수 있도록 허가하는 공식 문서입니다
residence_permit: 외국인이 특정 기간 동안 국가에 거주할 수 있도록 허용하는 공식 문서로, 주로 이민 당국에서 발급합니다
vehicle_registration_certificate: 차량 등록 증명을 제공하는 공식 문서로, 차량 및 소유자에 대한 세부 정보를 포함합니다
visa: 여권에 배치된 공식 승인으로, 소지자가 특정 기간 동안 국가에 입국, 출국 또는 체류할 수 있음을 나타냅니다
aadhaar: 인도 정부가 인도 거주자에게 발급한 고유한 12자리 식별 번호로, 생체 인식 및 인구 통계 데이터를 기반으로 합니다
pancard: 인도 정부가 개인 및 법인에게 발급한 영구 계정 번호(PAN) 카드로, 주로 세금 목적으로 사용됩니다

각 국가별로 지원되는 모든 신분증 유형 목록은 용어집/지원되는 신분증 유형에서 확인하세요.

사용 사례

KYC 프로세스: 고객 신원 확인 간소화
은행: 계좌 개설을 위한 고객 신원 확인
여행: 여행 문서 및 비자 처리
고용: 직원 신원 및 작업 허가증 확인
정부 서비스: 공식 신분증 처리

처리 모드

동기 처리

인식 결과와 함께 즉시 응답
실시간 애플리케이션에 최적
직접 API 응답

비동기 처리

지연된 결과를 위해 콜백 URL 사용
배치 처리에 더 적합
상세한 콜백 응답 형식

이미지 요구사항

파일 크기

권장: 10MB 미만
최대: 50MB

이미지 품질

해상도: 최소 300 DPI 권장
형식: 고대비, 밝게 조명된 이미지가 가장 좋습니다
방향: 문서가 올바르게 방향을 맞춰야 합니다

지원되는 형식

JPEG (.jpg, .jpeg)
PNG (.png)

오류 처리

400 상태 코드는 필수 매개변수 누락 등으로 인해 요청이 허용되지 않음을 나타냅니다. callbackUrl이 제공되는 비동기 작업에서는 요청 검증 중에 오류가 감지됩니다.

errorCode 유형

다음 표는 API에서 반환되는 구체적인 errorCode를 보여줍니다:

상태 코드	errorCode	설명	발생 유형
400	1001	Workspace is unavailable	워크스페이스를 현재 사용할 수 없음
400	1003	Fail to process data	서버상의 이슈로 인해 데이터 처리 실패 및 재시도 권장
400	1005	idImage is required	idImage가 필요함
400	1006	issuingCountry is required	issuingCountry가 필요함
400	1009	Fail to analyze data	신분증 이미지 분석 실패 및 재시도 권장
400	1010	callbackUrl is required	callbackUrl이 필요함
400	1011	Fail to recognize idCard	ID 카드 인식 실패: 통상적으로 유저가 제출한 신분증이 앞서 지정한 신분증(idType, issuingCountry)과 다른 경우 발생
400	1012	Fail to recognize back of an idCard	ID 카드 뒷면 인식 실패: 통상적으로 유저가 제출한 신분증이 앞서 지정한 신분증(idType, issuingCountry)과 다른 경우 발생
400	1013	Invalid image format	잘못된 이미지 형식 (base64 가 아닐 때)
400	1014	idType is required	idType이 필요함
400	1015	invalid inputs : missing fields	잘못된 입력: 누락된 필드가 존재

인증

x-api-key

string

header

필수

본문

application/json

idImage

string

필수

Image of the front side of the ID document in base64 format. Base64 encoded characters in the payload must not include the MIME type. For example, if the encoded base64 characters are "image/png;base64,/9j/2wBDABQODxIP...", then remove "image/png;base64," and send only the encoded data "/9j/2wBDABQODxIP...".

예시:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

issuingCountry

string

필수

The ISO 3 Alpha Country Code of the issuing country for the ID document.

예시:

"USA"

idType

enum<string>

필수

The type of the ID document

사용 가능한 옵션:

government_id,

passport,

drivers_license,

residence_permit,

vehicle_registration_certificate,

visa,

aadhaar,

pancard

예시:

"government_id"

idBackImage

string

Image of the back side of the ID document in base64 format.

예시:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

callbackUrl

string<uri>

The URL where the recognition results will be sent upon completion. If a callbackUrl is provided, the process works asynchronously. If no callbackUrl is provided, the process operates synchronously.

예시:

"https://your-domain.com/callback"

응답

Successful ID recognition

apiType

string

API type identifier

예시:

"id_recognition"

transactionId

string

Unique identifier for each request

예시:

"txn_123456789"

result

object

Object containing the processing result

Show child attributes

ID Image Best Practice

⌘I

Recognize and verify ID document

curl --request POST \
  --url https://idverify-api.argosidentity.com/modules/recognition \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "idImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "issuingCountry": "USA",
  "idType": "government_id",
  "idBackImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "callbackUrl": "https://your-domain.com/callback"
}
'

{
  "apiType": "id_recognition",
  "transactionId": "e0nvom3caiis7",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADDRESS 110, SOMEWHERE STREET",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  }
}

ID Liveness

Global ID Recognition

Documentation Index

​API 개요

​요청 매개변수

​필수 매개변수

​선택적 매개변수

​인증

​응답 형식

​지원되는 국가 및 ID 유형

​주요 국가들

​ID 유형

​사용 사례

​처리 모드

​동기 처리

​비동기 처리

​이미지 요구사항

​파일 크기

​이미지 품질

​지원되는 형식

​오류 처리

​errorCode 유형

인증

본문

응답

API 개요

요청 매개변수

필수 매개변수

선택적 매개변수

인증

응답 형식

지원되는 국가 및 ID 유형

주요 국가들

ID 유형

사용 사례

처리 모드

동기 처리

비동기 처리

이미지 요구사항

파일 크기

이미지 품질

지원되는 형식

오류 처리

errorCode 유형