Query String and Token
Query String and Token Guide
A comprehensive guide to the Query String and Token ID options for Liveform. These options enable features such as transmitting additional information, preventing duplicate submissions, and identifying users. Explore essential tools to optimize your ID Check 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:
https://form.argosidentity.com/?pid={project_Id} - URL with Query String:
https://form.argosidentity.com/?pid={project_Id}&blacklistCountries=false
2-1. Key Query String Parameters
| 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. |
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. |
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. |
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 issuingCountryis KOR and Universal mode is on, selecting IdType page will be shown to users. |
2-1-a. ID Types, Fields and Knowledge-Based, Auxiliary ID Field Prefill Parameter Values
[Knowledge-Based] knowledgeField Parameter Values
[Knowledge-Based] knowledgeField Parameter Values
-
name -
gender -
birthDate -
nationality -
SSN(Only the USA supported) -
address -
phoneNumbere.g.{'knowledgeField': 'gender,nationality,name'}
[Knowledge-Based] knowledgePrefill Parameter Values
[Knowledge-Based] knowledgePrefill Parameter Values
-
nameInput name -
birthDateRequire input YYYY-MM-DD -
gendermale or female -
nationalityISO Alpha-3 -
SSNRequire input number with hyphen(-) -
addressInput the keyword address in Google Maps -
phoneNumberCountry code with phone number without hyphen(-) e.g.{'knowledgePrefill': 'gender=male,birthdate=1990-01-01,SSN=123-12-0001,address=Washington D.C.,phoneNumber=+15555551234'}addressis the keyword to put in the search field in Google Maps.
[ID document] allowedIdTypes
[ID document] allowedIdTypes
-
passport -
drivers_license -
government_id -
residence_permit -
vehicle_registration_certificate -
visa -
pancard -
aadhaar -
foreign_registrator -
identification_carde.g.{'allowedIdTypes': 'passport,government_id,drivers_license'}
[ID document] allowedDocumentFields
[ID document] allowedDocumentFields
-
gender -
nationality -
expiry_date -
numberSame field as passport number -
issue_date -
id_number -
serial_number -
name -
date_of_birth -
curp_numberOnly available for Maxican ID card -
versionOnly available for New Zealand Driver’s license -
type_of_permitOnly available for Alien Registration Card in South Korea e.g.{'allowedDocumentFields': 'gender,name,date_of_birth,issue_date'}
[ID document] selectedIdType
[ID document] selectedIdType
-
passport -
drivers_license -
government_id -
residence_permit -
vehicle_registration_certificate -
visa -
pancard -
aadhaar -
foreign_registrator -
identification_carde.g.{'selectedIdType': 'passport'}
[ID document] auxidField Parameter Values
[ID document] auxidField Parameter Values
-
phoneNumberSMS-based phone number verification\ e.g.{'auxidField': 'phoneNumber'}
Every parameter value must not contain a space. ❌ Non-compliant Example
{'knowledgeField': 'gender, nationality, name'}
In the example above, the query string exact option does not contain a space after the comma, like{'knowledgeField': 'gender,nationality,name'}
2-1-b. Skip to Select Country in Knowledge-Based
In Knowledge-Based, ifallowedCountries set one nationality.e.g.
{'allowedCountries': 'USA'} The form skips to the select country page.
All Query String values must be URL-encoded.
2-2. Unique User ID and Custom Fields
- 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.
2-3. Auxiliary ID Field
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. Supported fields:- ‘phoneNumber’: SMS-based phone number verification
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. Token ID Options
ThetokenId is a string used for Liveform submissions in Private Mode.
Purpose: Prevent shared or duplicate use of the same URL.
3-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.
If the above conditions are not met, multiple users may proceed with the same Token ID simultaneously.
3-2. Methods to Check Token ID
- Webhook
- GET Submission API (single retrieval using
submission_id) - Download Submission CSV from the dashboard
3-3. URL Structure for Token ID
- Base Form URL:
https://form.argosidentity.com/?pid={project_Id} - URL with Token ID:
https://form.argosidentity.com/?pid={project_Id}&token={tokenId}
4. Encrypted Only
You can set encrypted only option in the dashboard. After set, URL query parameter only allowespid(project id), encrypted and lang(language) option, other option is disabled.
-
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) The unallowed parameter email was used in this URL.