> ## 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. # Global ID Recognition API > Process and verify identification documents by analyzing both front and back images, along with the issuing country and ID 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**: 뉴질랜드 각 국가별로 지원되는 모든 신분증 유형 목록은 [용어집/지원되는 신분증 유형](/ko/verify/glossary/supported_id_types)에서 확인하세요. ### ID 유형 * **government\_id**: 정부에서 발급한 공식 신분증으로, 개인의 신원을 확인하는 데 사용됩니다 * **passport**: 정부에서 발급한 공식 여행 문서로, 소지자의 신원과 국적을 인증하며 주로 국제 여행에 사용됩니다 * **drivers\_license**: 특정 개인이 오토바이, 자동차, 트럭 또는 버스와 같은 모터화된 차량을 운전할 수 있도록 허가하는 공식 문서입니다 * **residence\_permit**: 외국인이 특정 기간 동안 국가에 거주할 수 있도록 허용하는 공식 문서로, 주로 이민 당국에서 발급합니다 * **vehicle\_registration\_certificate**: 차량 등록 증명을 제공하는 공식 문서로, 차량 및 소유자에 대한 세부 정보를 포함합니다 * **visa**: 여권에 배치된 공식 승인으로, 소지자가 특정 기간 동안 국가에 입국, 출국 또는 체류할 수 있음을 나타냅니다 * **aadhaar**: 인도 정부가 인도 거주자에게 발급한 고유한 12자리 식별 번호로, 생체 인식 및 인구 통계 데이터를 기반으로 합니다 * **pancard**: 인도 정부가 개인 및 법인에게 발급한 영구 계정 번호(PAN) 카드로, 주로 세금 목적으로 사용됩니다 각 국가별로 지원되는 모든 신분증 유형 목록은 [용어집/지원되는 신분증 유형](/ko/verify/glossary/supported_id_types)에서 확인하세요. ## 사용 사례 * **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 | 잘못된 입력: 누락된 필드가 존재 | ## OpenAPI ````yaml POST /recognition openapi: 3.1.0 info: title: Global ID Recognition API description: >- API for processing and verifying identification documents worldwide using OCR technology version: 1.0.0 servers: - url: https://idverify-api.argosidentity.com/modules description: Production server security: - apiKeyAuth: [] paths: /recognition: post: tags: - Global ID Recognition summary: Recognize and verify ID document description: >- Process and verify identification documents by analyzing both front and back images, along with the issuing country and ID type operationId: recognizeIdDocument requestBody: required: true content: application/json: schema: type: object required: - idImage - issuingCountry - idType properties: idImage: type: string description: >- 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...". example: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg== idBackImage: type: string description: Image of the back side of the ID document in base64 format. example: >- iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg== issuingCountry: type: string description: >- The ISO 3 Alpha Country Code of the issuing country for the ID document. example: USA idType: type: string description: The type of the ID document enum: - government_id - passport - drivers_license - residence_permit - vehicle_registration_certificate - visa - aadhaar - pancard example: government_id callbackUrl: type: string description: >- 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. format: uri example: https://your-domain.com/callback responses: '200': description: Successful ID recognition content: application/json: schema: type: object properties: apiType: type: string description: API type identifier example: id_recognition transactionId: type: string description: Unique identifier for each request example: txn_123456789 result: type: object description: Object containing the processing result properties: data: type: object description: Extracted data from document properties: raw: type: object description: Raw extracted data with coordinates and scores properties: address: type: object properties: value: type: string example: '{{value}}' score: type: number example: 34 coordinates: type: object properties: first: type: object properties: x: type: number example: 410 'y': type: number example: 1237 second: type: object properties: x: type: number example: 560 'y': type: number example: 1237 third: type: object properties: x: type: number example: 564 'y': type: number example: 1362 fourth: type: object properties: x: type: number example: 415 'y': type: number example: 1362 original_coordinates: type: object description: >- Original image coordinates for the field (optional) properties: first: type: object properties: x: type: number example: 211 'y': type: number example: 714 second: type: object properties: x: type: number example: 553 'y': type: number example: 713 third: type: object properties: x: type: number example: 554 'y': type: number example: 751 fourth: type: object properties: x: type: number example: 213 'y': type: number example: 752 authority: type: object properties: value: type: string example: '{{value}}' score: type: number example: 4 coordinates: type: object properties: first: type: object properties: x: type: number example: 796 'y': type: number example: 1460 second: type: object properties: x: type: number example: 1931 'y': type: number example: 1461 third: type: object properties: x: type: number example: 1925 'y': type: number example: 1641 fourth: type: object properties: x: type: number example: 799 'y': type: number example: 1637 name: type: object properties: value: type: string example: '{{value}}' score: type: number example: 61 coordinates: type: object properties: first: type: object properties: x: type: number example: 367 'y': type: number example: 462 second: type: object properties: x: type: number example: 1379 'y': type: number example: 454 third: type: object properties: x: type: number example: 1378 'y': type: number example: 663 fourth: type: object properties: x: type: number example: 375 'y': type: number example: 669 name_chn: type: object properties: value: type: string example: '{{value}}' score: type: number example: 61 coordinates: type: object properties: first: type: object properties: x: type: number example: 367 'y': type: number example: 462 second: type: object properties: x: type: number example: 1379 'y': type: number example: 454 third: type: object properties: x: type: number example: 1378 'y': type: number example: 663 fourth: type: object properties: x: type: number example: 375 'y': type: number example: 669 number: type: object properties: value: type: string example: '{{value}}' score: type: number example: 95 accepted: type: boolean example: true coordinates: type: object properties: first: type: object properties: x: type: number example: 248 'y': type: number example: 698 second: type: object properties: x: type: number example: 1423 'y': type: number example: 691 third: type: object properties: x: type: number example: 1421 'y': type: number example: 861 fourth: type: object properties: x: type: number example: 256 'y': type: number example: 867 rotate: type: object properties: value: type: string example: '0' ocr: type: object description: OCR extracted data properties: ocr_fullName: type: string example: '{{ocr_fullName}}' ocr_firstName: type: string example: '{{ocr_firstName}}' ocr_middleName: type: string example: '{{ocr_middleName}}' ocr_lastName: type: string example: '{{ocr_lastName}}' ocr_gender: type: string example: '{{ocr_gender}}' ocr_nationality: type: string example: '{{ocr_nationality}}' ocr_birthDate: type: string example: '{{ocr_birthDate}}' ocr_identityNumber: type: string example: '{{ocr_identityNumber}}' ocr_issueDate: type: string example: '{{ocr_issueDate}}' ocr_expireDate: type: string example: '{{ocr_expireDate}}' ocr_version: type: string example: '{{ocr_version}}' ocr_number: type: string example: '{{ocr_number}}' full_mrz: type: string example: '{{full_mrz}}' mrz_line1: type: string example: '{{mrz_line1}}' mrz_line2: type: string example: '{{mrz_line2}}' review_front: type: boolean example: true review_back: type: boolean example: false document_type: type: string example: '{{document_type}}' examples: successful-recognition: summary: Successful ID recognition with complete data value: 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}}' async-processing: summary: Async processing request accepted value: transactionId: async_txn_789123 message: >- request has been successfully received. The response will be sent to https://your-domain.com/callback '400': description: Bad request - Invalid input parameters content: application/json: schema: type: object properties: statusCode: type: number example: 400 apiType: type: string example: id_recognition transactionId: type: string example: '{{transactionId}}' errorCode: type: string example: '1011' message: type: string example: Fail to recognize idCard components: securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key ````