쿼리 스트링 및 토큰 가이드

​

1. 커스터마이즈 가능한 쿼리 스트링 옵션

라이브폼과 API에서 사용 가능한 쿼리 스트링 옵션을 통해 추가 정보를 전송하고 KYC 프로세스를 커스터마이즈할 수 있습니다.

​

2. 기본 URL 구조

• 기본 폼 URL: https://form.argosidentity.com?pid={project_Id}
• 쿼리 스트링 포함 URL: https://form.argosidentity.com?pid={project_Id}&blacklistCountries=false

​

3. 주요 쿼리 스트링 파라미터

​

3-0. 어떤 상황에 어떤 파라미터를 쓰나요?

목적별 빠른 조견표입니다. 각 파라미터의 정확한 동작·제약·암호화 여부는 아래 상세 표와 Accordion에서 확인하세요.

표시 ID check 및 Knowledge-Based용 QueryString 파라미터 테이블

파라미터	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 및 라이브폼 커스터마이징을 참고하세요.
innerColor	Yes	Yes	반드시 암호화해야 합니다. CTA 버튼 및 액션 요소 내부의 텍스트/아이콘 색상을 설정합니다. #을 포함한 6자리 hex 컬러 코드를 입력합니다 (예: #FFFFFF). Custom Theme 및 라이브폼 커스터마이징을 참고하세요.
startValidUntil	Yes	Yes	반드시 암호화해야 합니다. 인증 시작 전 만료 시각을 UTC+0 ISO 8601 형식으로 지정합니다(예: 2026-04-30T15:00:00Z). 사용자가 링크에 진입할 때 시각이 이미 지났으면 인증 진행 자체를 차단하고 PV-40018 오류 페이지로 이동합니다. 미성년자 보호자 인증처럼 “링크 발송 후 일정 시간 내에 진입”을 강제해야 할 때 사용합니다.

표시 Knowledge-Based 전용 QueryString 파라미터 테이블

파라미터	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}

표시 ID check에서 고유 사용자 ID 및 커스텀 필드

• 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}

​

3 - ID check

표시 ID check의 파라미터 값

[ID document] allowedIdTypes 파라미터 값

수락할 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'}

[ID document] allowedDocumentFields 파라미터 값

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 document] selectedIdType 파라미터 값

사용자가 ID 타입 선택 단계를 건너뛰도록, 미리 한 가지 문서 종류를 지정합니다.

• passport — 여권
• drivers_license — 운전면허증
• government_id — 정부 발급 신분증
• residence_permit — 거주 허가증
• vehicle_registration_certificate — 차량 등록증
• visa — 비자
• pancard — 인도 PAN 카드
• aadhaar — 인도 Aadhaar 카드
• identification_card — 일반 신분증 카드
• e.g. {'selectedIdType': 'passport'}

[ID document] 예시

• 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 check에서 보조 신원 필드

ID 문서와 셀피 정보 외에 추가 검증이 필요한 신원 정보(예: 전화번호)의 경우, auxidField 옵션을 사용하여 수집 및 검증할 수 있습니다.

[ID document] 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 검증 미지원 국가 목록 보기

​

3 - Knowledge-Based

표시 Knowledge-Based의 파라미터 값

[Knowledge-Based] knowledgeField 파라미터 값

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] knowledgePrefill 파라미터 값

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에서 검색할 수 있는 키워드를 사용하세요. 미리 입력된 값이 주소 검색 필드에 나타납니다.

[Knowledge-Based] 예시

• 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에서 Selfie만 허용

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에서 국가 선택 건너뛰기

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로 진행할 수 있습니다.

표시 토큰 ID 확인 방법

• Webhook
• GET Submission API (submission_id를 사용한 단일 검색)
• 대시보드에서 Submission CSV 다운로드

표시 토큰 ID의 URL 구조

• 기본 폼 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(언어)만 허용되며, 다른 파라미터는 허용되지 않습니다.

• 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 프로세스를 최적화하고 사용자 경험을 향상시킬 수 있습니다.