Query String and Token Guide

Query string options are parameters used in Liveform and the API to send additional information and customize the KYC process.

1. Customizable Query String Options

The query string options available in Liveform and API allow you to send additional information and customize the KYC process.

2. Basic URL Structure

Base Form URL: US region https://form.argosidentity.com?pid={project_Id}, KR region https://form-kr.argosidentity.com?pid={project_Id}
URL with query string: https://form.argosidentity.com?pid={project_Id}&blacklistCountries=false

The Liveform URLs on this page are for US region projects. KR region projects use the host form-kr.argosidentity.com. See Regions for details.

You can use the Query String Encryption/Decryption Tool in the dashboard to generate encrypted URLs and test the query string parameters described below.

Add-on FaceAuth uses a different URL and a different set of parameters.FaceAuth uses its own add-on URL in the form https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}, and its parameters — sid, authUserId, authCf1–authCf3, token — differ from the ones on this page. Encryption also uses the API key of the FaceAuth project.Note also that FaceAuth does not run without a query string — pid alone cannot enter the flow; an encrypted sid is required. lang behaves the same as in Liveform and is passed as plaintext.

Parameter definitions: FaceAuth Getting Started
Error codes and user-facing messages on validation failure: FaceAuth URL Validation and Error Handling

3. Key Query String Parameters

3-0. Which parameter for which situation?

Quick lookup by goal. For exact behavior, constraints, and encryption requirements, refer to the detailed table and Accordions below.

What you want to do	Parameter(s) to use
Identify the user / submission and pass extra metadata	`email`, `userid`, `sid`, `cf1`, `cf2`, `cf3`
Restrict which ID document types are accepted	`allowedIdTypes`, `allowedCountries`
Restrict which user nationalities may verify (e.g. Korean nationals only)	`WhiteListNationality`
Restrict which OCR-extracted fields are shown / confirmed	`allowedDocumentFields`
Skip a step — country selection	`selectedIssuingCountry`, `allowedCountries` (with a single country)
Skip a step — ID type selection	`selectedIdType`
Skip a step — Knowledge-Based user info input	`knowledgeField: 'skip'`
Pick which items the Knowledge-Based step asks for	`knowledgeField`
Pre-fill Knowledge-Based input values	`knowledgePrefill`
Add identity verification beyond ID + selfie (e.g. SMS to phone)	`auxidField`
Override duplicate / age / blacklist policy for a single submission	`rejectDuplicateUser`, `approvePeriod`, `rejectPeriod`, `ageLimit`, `blacklistCountries`
Exclude specific fields from the response (apply a projection)	`projectionId`, `projectionName`
Brand the Liveform UI colors	`mainColor`, `innerColor`
Set the Liveform display language	`lang`
Enforce a link-entry expiry (e.g. time-limited guardian flow)	`startValidUntil`
One-time link — prevent URL sharing / re-use	`tokenId` (see Section 4. Token ID Options for details)

Show Query String Parameter table for ID check and Knowledge-Based

Parameter	ID document	Knowledge-Based	Description
`blacklistCountries`	Yes	Yes	Turns off blacklist country restrictions for the specific submission (`false` only).
`approvePeriod`	Yes	No	Turns off the approved duplicate submission prevention period (`false` only).
`rejectPeriod`	Yes	No	Turns off the rejected duplicate submission prevention period (`false` only).
`ageLimit`	Yes	Yes	Turns off age restriction for the specific submission (`false` only).
`rejectDuplicateUser`	Yes	Yes	Enables/disables duplicate submission prevention (`true` or `false` accepted). - In Knowledge-Based Submission, it works to contain Name, Gender, Birth Date, and Nationality information.
`email`	Yes	Yes	User’s email address.
`userid`	Yes	Yes	Custom unique identifier for the user.
`pid`	Yes	Yes	Unique identifier for each project.
`lang`	Yes	Yes	Sets the display language of Liveform. Use a lowercase ISO 639-1 code (for example, `en`, `ko`). Not subject to encryption — pass it as plaintext; it remains allowed in encrypted-only mode. When omitted, mobile follows the device language and PC follows the browser language. For the full list of supported languages, see Supported Languages.
`sid`	Yes	Yes	Unique identifier for each submission.
`cf1`	Yes	Yes	Custom option field #1.
`cf2`	Yes	Yes	Custom option field #2.
`cf3`	Yes	Yes	Custom option field #3.
`auxidField`	Yes	No	Must be encrypted. Used when auxiliary verification of identity information is required in addition to ID documents and selfie photos. Currently phoneNumber is implemented, see details below. Cannot be used simultaneously with selectedIssuingCountry and selectedIdType. This will be changed through future updates.
`allowedCountries`	Yes	Yes	Must be encrypted. `allowedCountries` can only be set using the encryption option and cannot be specified directly. e.g., If the encrypted value `{'allowedCountries': 'USA,KOR'}` is provided, only the United States (USA) and South Korea (KOR) will be allowed.
`WhiteListNationality`	Yes	Yes	Encryption is strongly recommended. If passed as plaintext, the user can remove the value from the URL and bypass the restriction. Specifies the user nationalities allowed to verify, using ISO Alpha-3 country codes; one or more can be set (e.g., `{'WhiteListNationality': 'KOR'}`). If the nationality entered by the user is not on the list, the submission is rejected at Step 2 with the reason White List Nationality Mismatch. For IDs that do not show nationality, such as the Korean driver’s license, Korean and foreign holders are distinguished by the first digit of the back half of the resident registration number. For details, see the 2026-10 update.
`allowedIdTypes`	Yes	No	Must be encrypted. Can set to show ID card type. Refer to the value below each parameter.
`allowedDocumentFields`	Yes	No	Must be encrypted. Can set to show available field. Refer to the value below each parameter.
`projectionId`	Yes	Yes	Must be encrypted. Can apply a projection to exclude fields. ProjectionName cannot be used together.
`projectionName`	Yes	Yes	Must be encrypted. Can apply a projection to exclude fields. ProjectionId cannot be used together.
`selectedIssuingCountry`	Yes	Yes	Must be encrypted. By selecting, user can skip the selecting country page. `allowedCountries` and `selectedIdType` can be used together. Also, when `allowedCountries` is selected, countreis not in the `allowedCountries` cannot be used. Same countries in `blacklistCountries` cannot be used together.
`selectedIdType`	Yes	No	Must be encrypted. By selecting, user can skip the selecting Id type page. Must be used with `selectedIssuingCountry`. If `selectedIdType` is used alone, it will cause error. Also, using Universal mode and `selectedIdType` together will casue error; exceptional case: note that if the `issuingCountry`is KOR and Universal mode is on, selecting IdType page will be shown to users.
`mainColor`	Yes	Yes	Must be encrypted. Sets the primary color of CTA buttons and positive action UI elements. Value must be a 6-digit hex color code with `#` prefix (e.g., `#AEFF00`). See Custom Theme and Liveform Customization.
`innerColor`	Yes	Yes	Must be encrypted. Sets the inner text/icon color within CTA buttons and action elements. Value must be a 6-digit hex color code with `#` prefix (e.g., `#FFFFFF`). See Custom Theme and Liveform Customization.
`startValidUntil`	Yes	Yes	Must be encrypted. Specifies the expiration time before authentication begins in UTC+0 ISO 8601 format (e.g., `2026-04-30T15:00:00Z`). If the user accesses the link after the specified time has passed, authentication is blocked and they are directed to the PV-40018 error page. Use this when you need to enforce “link entry within a set time period” such as guardian authentication for minors.

startValidUntil Behavior (2026-04)

Validation Priority: Evaluated before all other validations such as token ID validation. If start expiration is confirmed, subsequent validations are not performed.
Encryption Required: Cannot be used as plain text. Must be included in the encrypted parameter alongside other encryption options.
Timezone: Always interpreted as UTC+0. Example: {"startValidUntil":"2026-04-30T15:00:00Z"}.
Supported Pipelines: ID document, Knowledge-based.
Expiration Behavior: Redirects to error page /error-page/expired-start-valid-until (error code PV-40018), displaying the message “The verification link has expired. Please try again with a new link.” to the user.

Show Query String Parameter table for Knowledge-Based only

Parameter	ID document	Knowledge-Based	Description
`knowledgeField`	No	Yes	Must be encrypted. Set visible fields from the supported fields. Refer to the value below each parameter.
`knowledgePrefill`	No	Yes	Must be encrypted. Fill out the value in advance. Refer to the value below each parameter.
`skip`	No	Yes	Must be encrypted. When selected, users can skip the user information collection process in Knowledge-Based and proceed to the next step where they take a selfie photo as configured in the dashboard. Cannot be used with other knowledgeField options.

3 - Common

Show Skipping typing Email in the Processes

Below is an example of ID check with and without an email query parameter.
Example:
- https://form.argosidentity.com?pid={project_Id}&email={type_your_email_address}

Show Unique User ID and Custom Fields in ID check

Generate a unique user ID for KYC submitter identification during API calls.
Add up to three custom fields (cf1, cf2, cf3) to transmit additional information.
Example:
- https://form.argosidentity.com?pid={project_Id}&userid={type_userid}&cf1={type_cf1}&cf2={type_cf2}&cf3={type_cf3}

Note that this is appliable both in ID Documnet and Knolwedge-Based

3 - ID check

Show Parameter Values in ID check

[ID document] allowedIdTypes Parameter Values

Restrict which ID document types are accepted. Pick the values you need and combine them with commas.

passport — Passport
drivers_license — Driver’s license
government_id — Government-issued ID
residence_permit — Residence permit
vehicle_registration_certificate — Vehicle registration certificate
visa — Visa
pancard — India PAN card
aadhaar — India Aadhaar card
foreign_registrator — Foreign resident registration card
identification_card — General identification card
e.g. {'allowedIdTypes': 'passport,government_id,drivers_license'}

[ID document] allowedDocumentFields Parameter Values

Restrict which OCR-extracted fields are shown and confirmed by the user.

gender — Gender
nationality — Nationality
expiry_date — Expiry date
number — Document number (same field as passport number for passports)
issue_date — Issue date
id_number — ID number unique to the document
serial_number — Serial number
name — Name
date_of_birth — Date of birth
curp_number — CURP number (only available for Mexican ID card)
version — Card version (only available for New Zealand driver’s license)
type_of_permit — Type of permit (only available for Alien Registration Card in South Korea)
e.g. {'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}

[ID document] selectedIdType Parameter Values

Pre-select a single document type so the user skips the ID type selection step.

passport — Passport
drivers_license — Driver’s license
government_id — Government-issued ID
residence_permit — Residence permit
vehicle_registration_certificate — Vehicle registration certificate
visa — Visa
pancard — India PAN card
aadhaar — India Aadhaar card
identification_card — General identification card
e.g. {'selectedIdType': 'passport'}

[ID document] Examples

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'}
note that inside of encrypted should be encrypted; the above query is only for example

Every field name is case-sensitive.
Every parameter value must not contain a space.
❌ Non-compliant Example:
{'allowedDocumentFields': 'gender, name,date_of_birth, issue_date'}
The correct option should not have spaces after commas, like {'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}

Show Auxiliary ID Field in ID check

For identity information that requires verification in addition to ID documents and selfie information (e.g., phone numbers), you can collect and verify using the auxidField option.

[ID document] auxidField Parameter Values

Specify auxiliary identity information to collect and verify in addition to the ID document and selfie.

phoneNumber — SMS-based phone number verification e.g. {'auxidField': 'phoneNumber'}

Example:

https://form.argosidentity.com?pid={project_Id}&encrypted={'auxidField': 'phoneNumber'}
note that inside of encrypted should be encrypted; the above query is only for example

Caution:

Must be encrypted for use.
The parameter values above are case-sensitive. For example, if you write phonenumber, it will not work. You must write phoneNumber as shown above.
Cannot be used simultaneously with selectedIssuingCountry and selectedIdType. This will be changed through future updates.
Currently 91 countries do not support SMS verification.

Check Unsupported CountriesTo view the complete list of 91 countries where SMS verification for auxidField phoneNumber feature is not supported, please refer to the link below.📋 View SMS Verification Unsupported Countries List

3 - Knowledge-Based

Show Parameter Values in Knowledge-Based

[Knowledge-Based] knowledgeField Parameter Values

Pick which items the user must input during the Knowledge-Based step.

name — Full name
gender — Gender
birthDate — Date of birth
nationality — Nationality
SSN — Social Security Number (only the USA is supported)
address — Address
phoneNumber — Phone number
skip — Skip the entire user information collection step (must be used alone; cannot be combined with other knowledgeField values) e.g. {'knowledgeField': 'gender,nationality,name'}
e.g. {'knowledgeField': 'skip'}
The parameter values above are case-sensitive. For example, birthdate will not work. You must write birthDate as shown above.

[Knowledge-Based] knowledgePrefill Parameter Values

Pre-populate the Knowledge-Based input fields.

name — Name to prefill
birthDate — Date of birth (YYYY-MM-DD format required)
gender — Gender (male or female)
nationality — Nationality (ISO Alpha-3 country code)
SSN — Social Security Number (with hyphens -)
address — Address (keyword that can be searched on Google Maps)
phoneNumber — Phone number (country code included, no hyphens) e.g. {'knowledgePrefill': 'gender=male,birthDate=1990-01-01,SSN=123-12-0001,address=Washington D.C.,phoneNumber=+15555551234'} For address, use keywords that can be searched in Google Maps. The prefilled value will appear in the address search field.

[Knowledge-Based] Examples

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'}
note that inside of encrypted should be encrypted; the above query is only for example

Every field name is case-sensitive.
Every parameter value must not contain a space.
❌ Non-compliant Example:
{'knowledgeField': 'gender, nationality, name'}
The correct option should not have spaces after commas, like:
{'knowledgeField': 'gender,nationality,name'}

Show Only Selfie in Knowledge-Based

In Knowledge-Based, when you enter skip, users can skip the user information collection process and proceed to the next step.
When configured, the country selection and user information input collection screens will be skipped.
e.g. {'knowledgeField': 'skip'}

USECASE: when you want to perform Face-based authentication without collecting additional information, you can implement this by enabling the Selfie process option in the dashboard and setting ‘skip’ in the ‘knowledgeField’.

Caution:

Cannot be used with other knowledgeField options besides skip.
However, it can be used together with the administrator-provided email, userid, cf1, cf2, and cf3.
Must be encrypted for use.

Example:

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'}
note that inside of encrypted should be encrypted; the above query is only for example

Show Skip to Select Country in Knowledge-Based

In Knowledge-Based, if allowedCountries set one nationality.
e.g. {'allowedCountries': 'USA'} The form skips to the select country page.
Example:

https://form.argosidentity.comknowledge?pid={project_Id}&encrypted={'allowedCountries': 'USA'}
note that inside of encrypted should be encrypted; the above query is only for example

All query string values must be URL-encoded.

4. Token ID Options

The tokenId is a string used for Liveform submissions in Private Mode. Purpose: Prevent shared or duplicate use of the same URL.

Show 4-1. Token Validation

Validation fails (error occurs) under the following conditions:

Time Expiry: More than 3 minutes have elapsed since the first use.
Existing Valid Submission: There is an existing submission with a determined KYC status (approved, rejected, pending).

Caution:

If the above conditions are not met, multiple users may proceed with the same Token ID simultaneously.

Show 4-2. Methods to Check Token ID

Webhook
GET Submission API (single retrieval using submission_id)
Download Submission CSV from the dashboard

Show 4-3. URL Structure for Token ID

Base Form URL: US region https://form.argosidentity.com?pid={project_Id}, KR region https://form-kr.argosidentity.com?pid={project_Id}
URL with Token ID: https://form.argosidentity.com?pid={project_Id}&token={tokenId}
with Encryption enabled: https://form.argosidentity.com?pid={project_Id}&encrypted={encrypted} — encrypted carries the JSON {"token": "{tokenId}"} encrypted and then URL-encoded

5. Encrypted Only

You can enable the encrypted only option in the dashboard. After activation, URL query parameters only allow pid(project id), encrypted and lang(language), other parameters are not allowed.

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 is not an allowed parameter, so access is denied.

By using this guide, you can effectively leverage query string and Token ID options in ID check to optimize your KYC process and enhance user experience.

POST/Token

Secure token registration API guide with private mode and encryption settings

GET/Token

Encrypted token retrieval API guide in private mode

Token expired

This event is triggered when a Token ID expires according to the configured expiration conditions. You can manage tokens based on usage count or time through Token Expiration settings, and webhooks are automatically sent when tokens expire. This allows you to track token lifecycle and prevent token reuse issues.

​1. Customizable Query String Options

​2. Basic URL Structure

​3. Key Query String Parameters

​3-0. Which parameter for which situation?

​3 - Common

​3 - ID check

​3 - Knowledge-Based

​4. Token ID Options

​5. Encrypted Only

​Related documents

POST/Token

GET/Token

Token expired

1. Customizable Query String Options

2. Basic URL Structure

3. Key Query String Parameters

3-0. Which parameter for which situation?

3 - Common

3 - ID check

3 - Knowledge-Based

4. Token ID Options

5. Encrypted Only

Related documents