> ## 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. # 쿼리 스트링 및 토큰 가이드 > 라이브폼의 쿼리 스트링 및 토큰 ID 옵션에 대한 종합 가이드입니다. 추가 정보 전송, 중복 제출 방지, 사용자 식별 등의 기능을 제공합니다. ID Check 프로세스 최적화를 위한 필수 도구들을 알아보세요. ## 1. 커스터마이즈 가능한 쿼리 스트링 옵션 라이브폼과 API에서 사용 가능한 쿼리 스트링 옵션을 통해 추가 정보를 전송하고 KYC 프로세스를 커스터마이즈할 수 있습니다. ## 2. 기본 URL 구조 * **기본 폼 URL**: `https://form.argosidentity.com?pid={project_Id}` * **쿼리 스트링 포함 URL**: `https://form.argosidentity.com?pid={project_Id}&blacklistCountries=false` 아래 쿼리 스트링 파라미터들은 대시보드의 [쿼리스트링 암복호화 툴](/dashboard/ko/project-management/project-settings/project-info#쿼리스트링-암복호화-툴)을 사용하여 암호화된 URL을 직접 생성하고 테스트할 수 있습니다. ## 3. 주요 쿼리 스트링 파라미터 ### 3-0. 어떤 상황에 어떤 파라미터를 쓰나요? 목적별 빠른 조견표입니다. 각 파라미터의 정확한 동작·제약·암호화 여부는 아래 상세 표와 Accordion에서 확인하세요. | 하고 싶은 일 | 사용할 파라미터 | | --------------------------------------- | ---------------------------------------------------------------------------------------- | | 사용자·제출 식별 + 추가 메타데이터 전달 | `email`, `userid`, `sid`, `cf1`, `cf2`, `cf3` | | 받을 ID 문서 종류 제한 | `allowedIdTypes`, `allowedCountries` | | 표시·확정할 OCR 필드 제한 | `allowedDocumentFields` | | 단계 건너뛰기 — 국가 선택 | `selectedIssuingCountry`, `allowedCountries`(단일 국가 지정 시) | | 단계 건너뛰기 — ID 타입 선택 | `selectedIdType` | | 단계 건너뛰기 — Knowledge-Based 사용자 정보 입력 | `knowledgeField: 'skip'` | | Knowledge-Based 단계에서 입력받을 항목 선택 | `knowledgeField` | | Knowledge-Based 입력값 사전 채움 | `knowledgePrefill` | | ID + 셀피 외 추가 신원 검증 (예: 전화번호 SMS) | `auxidField` | | 중복 제출 / 연령 / 블랙리스트 정책을 특정 제출에만 예외 처리 | `rejectDuplicateUser`, `approvePeriod`, `rejectPeriod`, `ageLimit`, `blacklistCountries` | | 응답에서 특정 필드 제외 (projection 적용) | `projectionId`, `projectionName` | | 라이브폼 색상 브랜딩 | `mainColor`, `innerColor` | | 링크 진입 시각 만료 강제 (예: 보호자 인증 등 시간 제한 시나리오) | `startValidUntil` | | 1회성 링크 — URL 공유·재사용 방지 | `tokenId` (자세한 동작은 [섹션 4. 토큰 ID 옵션](#4-토큰-id-옵션) 참고) | | 파라미터 | ID Document | Knowledge-Based | 설명 | | ------------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `blacklistCountries` | Yes | Yes | 특정 submission에 대해 블랙리스트 국가 제한을 해제합니다 (`false`만 가능). | | `approvePeriod` | Yes | No | 승인된 중복 제출 방지 기간을 해제합니다 (`false`만 가능). | | `rejectPeriod` | Yes | No | 거부된 중복 제출 방지 기간을 해제합니다 (`false`만 가능). | | `ageLimit` | Yes | Yes | 특정 submission에 대해 연령 제한을 해제합니다 (`false`만 가능). | | `rejectDuplicateUser` | Yes | Yes | 중복 제출 방지를 활성화/비활성화합니다 (`true` 또는 `false` 허용). - Knowledge-Based Submission에서는 이름, 성별, 생년월일, 국적 정보를 포함하여 작동합니다. | | `email` | Yes | Yes | 사용자의 이메일 주소. | | `userid` | Yes | Yes | 사용자의 커스텀 고유 식별자. | | `pid` | Yes | Yes | 각 프로젝트의 고유 식별자. | | `sid` | Yes | Yes | 각 submission의 고유 식별자. | | `cf1` | Yes | Yes | 커스텀 옵션 필드 #1. | | `cf2` | Yes | Yes | 커스텀 옵션 필드 #2. | | `cf3` | Yes | Yes | 커스텀 옵션 필드 #3. | | `auxidField` | Yes | No | 반드시 암호화해야 합니다. ID 문서와 셀피 사진 외에 추가 신원 정보 검증이 필요한 경우 사용됩니다. 현재 phoneNumber가 구현되어 있으며, 자세한 내용은 아래를 참조하세요. selectedIssuingCountry 및 selectedIdType과 동시에 사용할 수 없습니다. 향후 업데이트를 통해 변경될 예정입니다. | | `allowedCountries` | Yes | Yes | 반드시 암호화해야 합니다. `allowedCountries`는 암호화 옵션을 사용해서만 설정할 수 있으며 직접 지정할 수 없습니다. 예: 암호화된 값 `{'allowedCountries': 'USA,KOR'}`가 제공되면 미국(USA)과 한국(KOR)만 허용됩니다. | | `allowedIdTypes` | Yes | No | 반드시 암호화해야 합니다. ID 카드 타입을 표시하도록 설정할 수 있습니다. 각 파라미터 아래의 값을 참조하세요. | | `allowedDocumentFields` | Yes | No | 반드시 암호화해야 합니다. 사용 가능한 필드를 표시하도록 설정할 수 있습니다. 각 파라미터 아래의 값을 참조하세요. | | `projectionId` | Yes | Yes | 반드시 암호화해야 합니다. 필드를 제외하는 projection을 적용할 수 있습니다. ProjectionName과 함께 사용할 수 없습니다. | | `projectionName` | Yes | Yes | 반드시 암호화해야 합니다. 필드를 제외하는 projection을 적용할 수 있습니다. ProjectionId와 함께 사용할 수 없습니다. | | `selectedIssuingCountry ` | Yes | Yes | 반드시 암호화해야 합니다. 선택하면 사용자가 국가 선택 페이지를 건너뛸 수 있습니다. `allowedCountries` 및 `selectedIdType`과 함께 사용할 수 있습니다. 또한 `allowedCountries`가 선택된 경우, `allowedCountries`에 포함되지 않은 국가는 사용할 수 없습니다. `blacklistCountries`와 동일한 국가는 함께 사용할 수 없습니다. | | `selectedIdType` | Yes | No | 반드시 암호화해야 합니다. 선택하면 사용자가 ID 타입 선택 페이지를 건너뛸 수 있습니다. `selectedIssuingCountry`와 함께 사용해야 합니다. `selectedIdType`을 단독으로 사용하면 오류가 발생합니다. 또한 **Universal mode**와 `selectedIdType`을 함께 사용하면 오류가 발생합니다; 예외 케이스: `issuingCountry`가 KOR이고 **Universal mode**가 활성화된 경우, 사용자에게 IdType 선택 페이지가 표시됩니다. | | `mainColor` | Yes | Yes | 반드시 암호화해야 합니다. CTA 버튼 및 positive 액션 UI 요소의 기본 색상을 설정합니다. `#`을 포함한 6자리 hex 컬러 코드를 입력합니다 (예: `#AEFF00`). [Custom Theme](/ko/idcheck/notices/2026-03-update#custom-theme) 및 [라이브폼 커스터마이징](/dashboard/ko/project-management/user-experience/liveform-customization#custom-theme-쿼리-스트링)을 참고하세요. | | `innerColor` | Yes | Yes | 반드시 암호화해야 합니다. CTA 버튼 및 액션 요소 내부의 텍스트/아이콘 색상을 설정합니다. `#`을 포함한 6자리 hex 컬러 코드를 입력합니다 (예: `#FFFFFF`). [Custom Theme](/ko/idcheck/notices/2026-03-update#custom-theme) 및 [라이브폼 커스터마이징](/dashboard/ko/project-management/user-experience/liveform-customization#custom-theme-쿼리-스트링)을 참고하세요. | | `startValidUntil` | Yes | Yes | 반드시 암호화해야 합니다. **인증 시작 전** 만료 시각을 UTC+0 ISO 8601 형식으로 지정합니다(예: `2026-04-30T15:00:00Z`). 사용자가 링크에 진입할 때 시각이 이미 지났으면 인증 진행 자체를 차단하고 PV-40018 오류 페이지로 이동합니다. 미성년자 보호자 인증처럼 "링크 발송 후 일정 시간 내에 진입"을 강제해야 할 때 사용합니다. | **`startValidUntil` 동작 방식 (2026-04)** * **검증 우선순위**: 토큰 ID 검증 등 다른 모든 검증보다 **먼저** 평가됩니다. 시작 만료가 확인되면 그 이후 검증은 수행되지 않습니다. * **암호화 필수**: 평문으로는 사용할 수 없으며, 다른 암호화 옵션과 함께 `encrypted` 파라미터에 포함하여 전달합니다. * **시간대**: 항상 UTC+0 기준으로 해석합니다. 예: `{"startValidUntil":"2026-04-30T15:00:00Z"}`. * **지원 파이프라인**: ID Document, Knowledge-based. * **만료 시 동작**: 오류 페이지 `/error-page/expired-start-valid-until` (에러 코드 `PV-40018`) 로 이동하며, 사용자에게 "The verification link has expired. Please try again with a new link." 메시지가 노출됩니다. | 파라미터 | ID Document | Knowledge-Based | 설명 | | ------------------ | ----------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeField` | No | Yes | 반드시 암호화해야 합니다. 지원되는 필드에서 표시할 필드를 설정합니다. 각 파라미터 아래의 값을 참조하세요. | | `knowledgePrefill` | No | Yes | 반드시 암호화해야 합니다. 값을 미리 입력합니다. 각 파라미터 아래의 값을 참조하세요. | | `skip` | No | Yes | 반드시 암호화해야 합니다. 선택하면 사용자가 Knowledge-Based의 사용자 정보 수집 과정을 건너뛰고 대시보드에서 구성된 대로 셀피 사진을 찍는 다음 단계로 진행할 수 있습니다. 다른 knowledgeField 옵션과 함께 사용할 수 없습니다. | ### 3 - 공통 * 아래는 이메일 쿼리 파라미터를 사용한 경우와 사용하지 않은 경우의 ID Check 예시입니다.
* **예시:** * `https://form.argosidentity.com?pid={project_Id}&email={type_your_email_address}` dashboard * API 호출 시 KYC 제출자 식별을 위한 고유 사용자 ID를 생성합니다. * 추가 정보 전송을 위해 최대 3개의 커스텀 필드(`cf1`, `cf2`, `cf3`)를 추가합니다.
* **예시:** * `https://form.argosidentity.com?pid={project_Id}&userid={type_userid}&cf1={type_cf1}&cf2={type_cf2}&cf3={type_cf3}` 이는 ID Document와 Knowledge-Based 모두에 적용 가능합니다. ### 3 - ID check 수락할 ID 문서 종류를 제한할 때 사용합니다. 아래 값 중 필요한 것만 골라 쉼표로 조합하세요. * `passport` — 여권 * `drivers_license` — 운전면허증 * `government_id` — 정부 발급 신분증 * `residence_permit` — 거주 허가증 * `vehicle_registration_certificate` — 차량 등록증 * `visa` — 비자 * `pancard` — 인도 PAN 카드 * `aadhaar` — 인도 Aadhaar 카드 * `foreign_registrator` — 외국인 등록증 * `identification_card` — 일반 신분증 카드 * e.g. `{'allowedIdTypes': 'passport,government_id,drivers_license'}` OCR로 추출하여 사용자에게 표시·확정할 필드를 제한할 때 사용합니다. * `gender` — 성별 * `nationality` — 국적 * `expiry_date` — 만료일 * `number` — 문서 번호 (여권의 경우 여권 번호와 동일한 필드) * `issue_date` — 발급일 * `id_number` — 신분증 고유 번호 * `serial_number` — 시리얼 번호 * `name` — 이름 * `date_of_birth` — 생년월일 * `curp_number` — CURP 번호 (멕시코 ID 카드에서만 사용 가능) * `version` — 카드 버전 (뉴질랜드 운전면허증에서만 사용 가능) * `type_of_permit` — 체류 자격 (한국 외국인 등록증에서만 사용 가능) * e.g. `{'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}` 사용자가 ID 타입 선택 단계를 건너뛰도록, 미리 한 가지 문서 종류를 지정합니다. * `passport` — 여권 * `drivers_license` — 운전면허증 * `government_id` — 정부 발급 신분증 * `residence_permit` — 거주 허가증 * `vehicle_registration_certificate` — 차량 등록증 * `visa` — 비자 * `pancard` — 인도 PAN 카드 * `aadhaar` — 인도 Aadhaar 카드 * `identification_card` — 일반 신분증 카드 * e.g. `{'selectedIdType': 'passport'}` * **allowedIdTypes:** * `https://form.argosidentity.com?pid={project_Id}&encrypted={'allowedIdTypes': 'passport,government_id,drivers_license'}` * **allowedDocumentFields:** * `https://form.argosidentity.com?pid={project_Id}&encrypted={'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}` * **selectedIdType:** * `https://form.argosidentity.com?pid={project_Id}&encrypted={'selectedIdType': 'passport'}` * encrypted 내부의 내용은 암호화되어야 합니다; 위 쿼리는 예시용입니다 \| - 모든 **필드 이름은 대소문자를 구분**합니다. \| - 모든 파라미터 값에는 **공백이 포함되어서는 안 됩니다**. \| - ❌ 잘못된 예시:
`{'allowedDocumentFields': 'gender, name,date_of_birth, issue_date'}` \| - 올바른 옵션은 다음과 같이 쉼표 다음에 공백이 없어야 합니다: `{'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}` ID 문서와 셀피 정보 외에 추가 검증이 필요한 신원 정보(예: 전화번호)의 경우, auxidField 옵션을 사용하여 수집 및 검증할 수 있습니다.
ID 문서·셀피 외에 추가로 수집·검증할 신원 정보를 지정합니다. * `phoneNumber` — SMS 기반 전화번호 검증 e.g. `{'auxidField': 'phoneNumber'}` **예시:** * `https://form.argosidentity.com?pid={project_Id}&encrypted={'auxidField': 'phoneNumber'}` * encrypted 내부의 내용은 암호화되어야 합니다; 위 쿼리는 예시용입니다 **주의사항**: * 사용하려면 반드시 암호화해야 합니다. * 위의 파라미터 값들은 대소문자를 구분합니다. 예를 들어, phonenumber로 작성하면 작동하지 않습니다. 위에 표시된 대로 phoneNumber로 작성해야 합니다. * selectedIssuingCountry 및 selectedIdType과 동시에 사용할 수 없습니다. 향후 업데이트를 통해 변경될 예정입니다. * **현재 91개 국가에서 SMS 검증을 지원하지 않습니다.** **지원되지 않는 국가 확인** auxidField phoneNumber 기능에서 SMS 검증을 지원하지 않는 91개 국가의 전체 목록을 보려면 아래 링크를 참조하세요. 📋 [**SMS 검증 미지원 국가 목록 보기**](/ko/idcheck/getting-started/liveform-url/auxidfield-unsupported-countries) ### 3 - Knowledge-Based Knowledge-Based 단계에서 사용자에게 입력받을 항목을 지정합니다. * `name` — 이름 * `gender` — 성별 * `birthDate` — 생년월일 * `nationality` — 국적 * `SSN` — 사회보장번호 (미국에서만 지원) * `address` — 주소 * `phoneNumber` — 전화번호 * `skip` — 사용자 정보 수집 단계 전체를 건너뛰기 (단독으로만 사용, 다른 knowledgeField 값과 조합 불가) e.g. `{'knowledgeField': 'gender,nationality,name'}`
e.g. `{'knowledgeField': 'skip'}`
위의 파라미터 값들은 대소문자를 구분합니다. 예를 들어, birthdate는 작동하지 않습니다. 위에 표시된 대로 birthDate로 작성해야 합니다. Knowledge-Based 입력 필드에 값을 미리 채워 넣을 때 사용합니다. * `name` — 미리 채울 사용자 이름 * `birthDate` — 생년월일 (`YYYY-MM-DD` 형식 필수) * `gender` — 성별 (`male` 또는 `female`) * `nationality` — 국적 (ISO Alpha-3 국가 코드) * `SSN` — 사회보장번호 (하이픈 `-` 포함) * `address` — 주소 (Google Maps에서 검색 가능한 키워드) * `phoneNumber` — 전화번호 (국가 코드 포함, 하이픈 `-` 없이 입력) e.g. `{'knowledgePrefill': 'gender=male,birthdate=1990-01-01,SSN=123-12-0001,address=Washington D.C.,phoneNumber=+15555551234'}` `address`의 경우 Google Maps에서 검색할 수 있는 키워드를 사용하세요. 미리 입력된 값이 주소 검색 필드에 나타납니다. * `https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'knowledgeField': 'gender,nationality,name'}` * `https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'knowledgePrefill': 'gender=male,birthdate=1990-01-01,SSN=123-12-0001,address=Washington D.C.,phoneNumber=+15555551234'}` * encrypted 내부의 내용은 암호화되어야 합니다; 위 쿼리는 예시용입니다 * 모든 필드 이름은 대소문자를 구분합니다. * 모든 파라미터 값에는 공백이 포함되어서는 안 됩니다. * ❌ 잘못된 예시:
`{'knowledgeField': 'gender, nationality, name'}` * 올바른 옵션은 다음과 같이 쉼표 다음에 공백이 없어야 합니다:
`{'knowledgeField': 'gender,nationality,name'}`
`Knowledge-Based`에서 `skip`을 입력하면, 사용자가 사용자 정보 수집 과정을 건너뛰고 다음 단계로 진행할 수 있습니다.
**구성되면 국가 선택 및 사용자 정보 입력 수집 화면이 건너뛰어집니다.**
e.g. `{'knowledgeField': 'skip'}` 사용 사례: 추가 정보 수집 없이 Face 기반 인증만 수행하려는 경우, 대시보드에서 Selfie 프로세스 옵션을 활성화하고 'knowledgeField'에 'skip'을 설정하여 구현할 수 있습니다. **주의사항:** * skip 외의 다른 knowledgeField 옵션과 함께 사용할 수 없습니다. * 단, 관리자가 전달하는, email, userid, cf1, cf2, cf3와 병행해서 사용 가능합니다. * 사용하려면 반드시 암호화해야 합니다. **예시:** * `https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'knowledgeField': 'skip'}` * `https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'email': 'example@example.com','userid': 'userid', 'cf1': 'cf1','knowledgeField': 'skip'}` * encrypted 내부의 내용은 암호화되어야 합니다; 위 쿼리는 예시용입니다 Knowledge-Based에서 `allowedCountries`를 하나의 국적으로 설정하면.\ e.g. `{'allowedCountries': 'USA'}` 폼이 국가 선택 페이지를 건너뜁니다.
**예시:** * `https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'allowedCountries': 'USA'}` * encrypted 내부의 내용은 암호화되어야 합니다; 위 쿼리는 예시용입니다 모든 쿼리 스트링 값은 URL 인코딩되어야 합니다. ## 4. 토큰 ID 옵션 `tokenId`는 Private Mode에서 Liveform 제출 시 사용되는 문자열입니다. **목적**: 동일한 URL의 공유 또는 중복 사용을 방지합니다. 다음 조건에서 검증이 실패(오류 발생)합니다: 1. **시간 만료**: 최초 사용으로부터 3분이 경과한 경우. 2. **기존 유효한 제출**: 결정된 KYC 상태(승인, 거부, 보류)를 가진 기존 제출이 있는 경우. **주의사항**: * 위 조건을 충족하지 않으면 여러 사용자가 동시에 동일한 토큰 ID로 진행할 수 있습니다. * [Webhook](/ko/idcheck/webhooks/overview) * **GET Submission API** (`submission_id`를 사용한 단일 검색) * 대시보드에서 Submission CSV 다운로드 * **기본 폼 URL**: `https://form.argosidentity.com?pid={project_Id}` * **토큰 ID 포함 URL**: `https://form.argosidentity.com?pid={project_Id}&token={tokenId}` * **암호화 활성화**: `https://form.argosidentity.com?pid={project_Id}&encrypted={token={tokenId}}` ## 5. 암호화 전용 대시보드에서 암호화 전용 옵션을 활성화할 수 있습니다. 활성화 후에는 URL 쿼리 파라미터로 `pid`(프로젝트 id), `encrypted`, `lang`(언어)만 허용되며, 다른 파라미터는 허용되지 않습니다. Encrypted Only Kr Pn * `https://form.argosidentity.com?pid={project_Id}&encrypted={encrypted_option}&lang=en`(O) * `https://form.argosidentity.com?pid={project_Id}&encrypted={encrypted_option}&email=your_email_address@argosidentity.com`(X) email은 허용되지 않는 파라미터이므로 접근이 거부됩니다. 이 가이드를 사용하여 ID check의 쿼리 스트링 및 토큰 ID 옵션을 효과적으로 활용하여 KYC 프로세스를 최적화하고 사용자 경험을 향상시킬 수 있습니다.