쿼리 스트링 및 토큰 가이드

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

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

2. 기본 URL 구조

기본 폼 URL: US 리전 https://form.argosidentity.com?pid={project_Id}, KR 리전 https://form-kr.argosidentity.com?pid={project_Id}
쿼리 스트링 포함 URL: https://form.argosidentity.com?pid={project_Id}&blacklistCountries=false

이 페이지의 라이브폼 URL은 US 리전 프로젝트 기준입니다. KR 리전 프로젝트는 호스트가 form-kr.argosidentity.com입니다. 자세한 내용은 리전 안내를 참고하세요.

아래 쿼리 스트링 파라미터들은 대시보드의 쿼리스트링 암복호화 툴을 사용하여 암호화된 URL을 직접 생성하고 테스트할 수 있습니다.

애드온 Face Auth는 별도 URL과 파라미터를 사용합니다.Face Auth는 https://form.argosidentity.com/face-auth?pid={faceAuth_projectId} 형태의 애드온 전용 URL을 사용하며, 파라미터도 sid, authUserId, authCf1~authCf3, token으로 이 문서의 것과 다릅니다. 암호화 키도 FaceAuth 프로젝트의 API 키를 사용합니다.또한 Face Auth는 쿼리 스트링 없이 실행되지 않습니다 — pid만으로는 진입할 수 없고 암호화된 sid가 필수입니다. lang은 라이브폼과 동일하게 평문으로 동작합니다.

파라미터 정의: FaceAuth 시작하기
검증 실패 시 에러 코드와 사용자 노출 문구: Face Auth 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`
라이브폼 표시 언어 지정	`lang`
링크 진입 시각 만료 강제 (예: 보호자 인증 등 시간 제한 시나리오)	`startValidUntil`
1회성 링크 — URL 공유·재사용 방지	`tokenId` (자세한 동작은 섹션 4. 토큰 ID 옵션 참고)

표시 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	각 프로젝트의 고유 식별자.
`lang`	Yes	Yes	라이브폼 표시 언어를 지정합니다. ISO 639-1 소문자 코드를 사용합니다 (예: `en`, `ko`). 암호화 대상이 아니며 평문으로 전달합니다 — 암호화 전용 모드에서도 허용되는 파라미터입니다. 미설정 시 모바일은 기기 설정 언어, PC는 브라우저 언어를 따릅니다. 지원 언어 전체 목록은 라이브폼 지원 언어를 참고하세요.
`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 오류 페이지로 이동합니다. 미성년자 보호자 인증처럼 “링크 발송 후 일정 시간 내에 진입”을 강제해야 할 때 사용합니다.

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.” 메시지가 노출됩니다.

표시 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}

이는 ID Document와 Knowledge-Based 모두에 적용 가능합니다.

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의 공유 또는 중복 사용을 방지합니다.

표시 토큰 검증

다음 조건에서 검증이 실패(오류 발생)합니다:

시간 만료: 최초 사용으로부터 3분이 경과한 경우.
기존 유효한 제출: 결정된 KYC 상태(승인, 거부, 보류)를 가진 기존 제출이 있는 경우.

주의사항:

위 조건을 충족하지 않으면 여러 사용자가 동시에 동일한 토큰 ID로 진행할 수 있습니다.

표시 토큰 ID 확인 방법

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

표시 토큰 ID의 URL 구조

기본 폼 URL: US 리전 https://form.argosidentity.com?pid={project_Id}, KR 리전 https://form-kr.argosidentity.com?pid={project_Id}
토큰 ID 포함 URL: https://form.argosidentity.com?pid={project_Id}&token={tokenId}
암호화 활성화: https://form.argosidentity.com?pid={project_Id}&encrypted={encrypted} — encrypted에는 {"token": "{tokenId}"} JSON을 암호화한 값을 URL 인코딩해서 넣습니다

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

시작하기

라이브폼 URL

보안

개발자 문서 MCP

쿼리 스트링 및 토큰 가이드

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

2. 기본 URL 구조

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

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

3 - 공통

3 - ID check

3 - Knowledge-Based

4. 토큰 ID 옵션

5. 암호화 전용

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

​2. 기본 URL 구조

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

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

​3 - 공통

​3 - ID check

​3 - Knowledge-Based

​4. 토큰 ID 옵션

​5. 암호화 전용

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

2. 기본 URL 구조

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

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

3 - 공통

3 - ID check

3 - Knowledge-Based

4. 토큰 ID 옵션

5. 암호화 전용