GET/Submission

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission?submission_id={submission_id}"\
-H "x-api-key: {yourAPIKey}"

Get a list of submissions.

  • The KYC / AML status can be checked by the GET request.

  • You can either check for the KYC status of a specific submission or get a list of KYC submissions with GET request.

  • If no parameter is provided, a list of all submissions is returned.

  • If a parameter is provided, filter the list by the given parameter.

  • To get a submission data of a specific submission, submission id must be provided as a parameter. Please refer to the Input Data table for detail.

Input Data

* means required parameters. (Get submission has no required parameters.)

ParameterDescription

submission_id

Submission ID. A single submission data matching the submission ID is returned.

userid

A list of submissions matching the userid is returned. The userid is an optional parameter that is inserted into submission data when posting a submission.

email

A list of submissions matching the email address is returned.

count

The number of data to be transmitted when requesting a list output(maximum of 2,000). When requesting a list without a count parameter, up to 2,000 will be the output by default.

nextpage_id

If 'nextpageKey' is returned to the response when requesting list output, it means that there is a next page. To call the next page, 'nextpage_id(nextpageKey.id)' and 'nextpage_date(nextpageKey.created_at) should be included to the request parameter.

nextpage_date

If 'nextpageKey' is returned to the response when requesting list output, it means that there is a next page. To call the next page, 'nextpage_id(nextpageKey.id)' and 'nextpage_date(nextpageKey.created_at) should be included to the request parameter.

start_date

Start date of querying period(YYYYMMDD)

end_date

End date of querying period(YYYYMMDD)

request_type

Selectively query certain items. Available options are { kyc, aml, data, others }

  • aml: aml. sub data + submission_id

  • kyc: kyc. sub data + submission_id

  • data: data. sub data + submission_id

  • others: Rest of the data except for aml, kyc, data.

Using Encryption Option for Input Data

2024.06.21

When using the encryption option, both input and output require bidirectional encryption/decryption.

Example:

Encrypt the Input object (Query String Parameter) and transmit it as the data property.

queryStringParameters : {
    data : encrypt({
        email : 'string',
        start_date : 'string',
        end_date : 'string'
    })
}

Output Data

ResponseDescription

data

KYC applicant data

data.name

name

data.gender

<male, female>

data.nationality

Three letter format (ISO alpha3 format) of nationality.

data.date_of_birth

YYYY-MM-DD format of date of birth

data.ip_address

User's IP address in IPv4 format

data.idType

ID card type

<passport, government_id, drivers_licensem, residence permit, vehicle registration certificate, visa, aadhaar, pancard>

data.idcard_issuingCountry

ISO alpha 3 format country code where ID card is issued.

data.idcard_issueDate

YYYY-MM-DD format of ID card issue date

data.idcard_expireDate

YYYY-MM-DD format of ID card expiry date

data.identityNumber

Personal Identity Number

data.documentNumber

Documnet number

data.address_city

City

data.address_country

Country

data.address_state

State

data.address_street

Street

data.address_zipcode

Zip code (postal code)

data.address_globalCode

Detailed code from the address (ex. 87C4VXX7+39)

data.address_compoundCode

Detailed code, city and country from the address (ex. VXX7+39 Washington, DC, USA)

data.address_formatted

Transformed address from detailed code

data.address_input

User input address

data.address_detail

User input detailed address

data.cf1

Optional parameter that is inserted into submission data when posting a submission.

data.cf2

Optional parameter that is inserted into submission data when posting a submission.

data.cf3

Optional parameter that is inserted into submission data when posting a submission.

email

email address

reviewer

system: when reviewed by AI agent: when reviewed by human

submission_id

Identifier given to each submission

applicant_id

Identifier given to duplicated applicant

created_at

KYC submitted date and time.

kyc_result_at

Time when the KYC result is first determined, it will be transmitted only when the result is 'approved/rejected'. (UTC+0)

updated_at

The most recent time when the submission was updated. (UTC+0)

pending_at

Time when a submission was turned into 'pending' status. (UTC+0)

userid

Optional parameter that is inserted into submission data when posting a submission.

additional_list

This field contains data entered by users during the KYC process, applicable to the Additional form set in the dashboard. The data is included for the following request types:

- When queried by a specific submissionId or email

- When ‘request_type’ is set to ‘others’

additional_list.answer

Name of each item in the Additional form

additional_list.inputValue

User input value for each item

additional_list.blockType

Data type of each item

kyc

KYC data object

kyc.result

<incomplete, pending, approved, rejected> incomplete: KYC submission is incomplete due to insufficient data.

pending: the submission is under manual review

approved: submission is approved

rejected: submission is rejected. Reject comment can be found at "kyc.comment".

KYC reject comment is returned only when KYC result is 'rejected'

Code for KYC reject comment

kyc.attempts

Object of Liveness, Detect face, Face compare

kyc.attempts[i].attemptCnt

Sum of attempts tried at Step 1 and Step 2

kyc.attempts[i].idBarcodeResult

Barcode verification result for USA, CAN, MEX ID

kyc.attempts[i].verificationResult

Authentication result on attempt [i] <success, fail>

kyc.attempts[i].verification

Detail data of authentication on attempt [i]

kyc.attempts[i].verificationParams

Authentication data on attempt [i]

kyc.attempts[i].errorCode

Liveness, Detect face, Face compare, Authentication error code

kyc.attempts[i].errorMsg

Liveness, Detect face, Face compare, Authentication error message

kyc.attempts[i].step1Time1st

Step1 API 1st call time

kyc.attempts[i].step1Time2nd

Step1 API 2nd call time

kyc.attempts[i].step1Time3rd

Step1 API 3rd call time

kyc.attempts[i].step2Time1st

Step2 API 1st call time

kyc.attempts[i].step2Time2nd

Step2 API 2nd call time

kyc.attempts[i].step2Time3rd

Step3 API 3rd call time

kyc.attempts[i].retryMsg

Cause of rejection on Liveness, Detect face, Face compare, Authentication(Korean)

kyc.attempts[i].retryCode

Code of cause for rejection on Liveness, Detect face, Face compare, Authentication(Korean)

kyc.attempts[i].faceSimilarityScore

Face similarity score on attempt [i]

kyc.attempts[i].selfieImage

Selfie image URL of attmept [i]

kyc.attempts[i].livenessScore

Liveness score on attempt [i]

aml

aml screening result data object

aml.risk_level_summary

<Not Screened, High, Medium, Low>

aml.currentstatus

<Not Screened, Red Flag>

aml.matches

Detailed AML screening result. Only available when aml.currentstatus is 'Red Flag'.

aml.matches[i].risk_level

Red flag risk level <HIGH, MEDIUM, LOW>

aml.matches[i].resource_id

Returned only when AML screening has matches. Resource ID is used to request and download the AML report for the specific match.

aml.matches[i].score

AML screening score

aml.matches[i].risk_icons

AML risk icon

nextpageKey

Key-value object delivered when there is a next page.

nextpageKey.id

The last inquired submission ID which is needed to call the next page.

nextpageKey.created_at

'created_at' value of the last inquired submission ID which is needed to call the next page.

bank_verification

The result object of the 'Account Occupancy - South Korea' option when it is activated.

bank_verification.result

Result of the 'Account Occupancy' <success ,fail>

bank_verification.type

Type of authentication <occupancy(account verification ), nameCheck(account holder verification)> (Only 'occupancy' is available for now)

bank_verification.bank_code

The 3 digit bank code.

bank_verification.account_number

The account number.

bank_verification.retry_countj

Verification code sending tried count.

id_LivenessScore

When using the attack prevention option, ID Card Liveness Score result top object

id_LivenessScore.Screen_play

Liveness score of ‘Screen play’ in ID Card Liveness verification pipeline

id_LivenessScore.Paper_printed

Liveness score of ‘Paper printed’ in ID Card Liveness verification pipeline

id_LivenessScore.Replace_portraits

Liveness score of ‘Replace portraits’ in ID Card Liveness verification pipeline

Injection_action

Returns the Injection Process execution details.

Injection_action.type

This is the type of injection process.

Injection_action.time

This is the most recent execution date of the corresponding type of Injection Process.

tokenId

TokenID used when submitting live-form in private mode.

Sample Response - Specific submission

{
   "Items":[
      {
         "data":{
            "name":"Jhon Smith",
            "gender":"male",
            "nationality":"USA",
            "date_of_birth":"1998-11-12",
            "cf1":"test",
            "ip_address":"*.*.*.*",
            "idcard_issuingCountry":"USA",
            "idcard_issueDate":"2016-08-16",
            "idType":"government_id",
            "identityNumber":"981112-1******"
         },
         "email":"test@gmail.com",
         "submission_id":"gt7rcxx9l1o*****",
         "created_at":"2022-04-07T00:30:35.919Z",
         "userid":"test1",
         "kyc":{
            "result":"rejected",
            "comment":[
               "Multiple invalid KYC attempts"
            ],
            "commentCode":[
               "too_many_retry"
            ],
            "attempts":[
               {
                  "attemptCnt":1,
                  "livenessScore":91,
                  "faceSimilarityScore":99,
                  "verificationParams":{
                     "fullName":"Jhon Smith",
                     "idType":"government_id",
                     "issueDate":"2016-08-15",
                     "identityNumber":"981112-1******"
                  },
                  "verificationResult":"fail",
                  "retryMsg":[
                     "Face compare failed: no matching face"
                  ],
                  "retryCode":[
                     "face_compare_fail"
                  ]
               },
               {
                  "attemptCnt":2,
                  "livenessScore":98,
                  "verificationParams":{
                     "fullName":"Jhon Smith",
                     "idType":"government_id",
                     "issueDate":"2016-08-16",
                     "identityNumber":"981112-1******"
                  },
                  "verificationResult":"success",
                  "retryMsg":[
                     "Face compare failed: no matching face"
                  ],
                  "retryCode":[
                     "face_compare_fail"
                  ]
               },
               {
                  "attemptCnt":3,
                  "faceSimilarityScore":99,
                  "verificationParams":{
                     "fullName":"Jhon Smith",
                     "idType":"government_id",
                     "issueDate":"2016-08-16",
                     "identityNumber":"981112-1******"
                  },
                  "verificationResult":"success",
                  "retryMsg":[
                     "Face compare failed: no matching face"
                  ],
                  "retryCode":[
                     "face_compare_fail"
                  ]
               }
            ]
         }
      }
   ]
}

Using Encryption Option for Output Data

When using the encryption option, the result is returned in the data property within the response body.

Example:

response : {
   body : {
      "data": "encrypted-string",
      "isEncrypted": true
   }
}

Reject Code & Comment

kyc.commentCodekyc.comment

id_image_invalidImage

ID document not detected. Please take a picture of your ID document.

id_image_invalidId

Invalid ID document. Please resubmit with another ID document.

id_image_error

Fail to upload the ID image. Please resubmit the KYC process.

id_image_badImage

Fail to read the ID image. Please take a clear picture of your ID document.

id_info_dataMismatch

The entered information does not match with your ID document.

id_info_blacklist

According to the policy, we do not accept KYC from {country}.

id_info_notOfAge

We do not accept KYC anyone under {13} years old.

too_many_retry

Multiple invalid KYC attempts

blacklistCountry

According to the policy, we do not accept KYC from {country}.

under_ageLimit

We do not accept KYC anyone under {13} years old.

invalid_acceptedID

Inacceptable ID type. Please resubmit with another ID, check the valid ID on the submission page.

address_image_invalidImage

Invalid proof of address. Proof of address must include your full name and address. ex)utility bill, bank statement, residency certificate, etc.

address_image_error

Fail to upload proof of address image. Please retry.

address_image_badImage

Fail to read the image. Please take a clear picture of your proof of address.

address_info_expiredDocument

Expired proof of address. The proof of address should be issued within 6 months.

address_info_dataMismatch

Entered information does not match with your proof of address.

timeout

KYC rejected due to timeout

other

*Reject comment written by KYC agents.

GET/Submission/Submission ID

Querying for one, specific submission data.

  • URL and x-api-key required

  • Should be requested with Query Params

  • Available for one submission data

  • The response includes KYC personal info, KYC result, AML result, reject comment and code, retry comment and code.

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission?submission_id={submission_id}"\
-H "x-api-key: {yourAPIKey}"

Sample Request

curl --location --request GET 'https://rest-api.argoskyc.com/v3/submission?submission_id={submission_id}'\
--header 'x-api-key: {yourAPIKey}'

Sample Response

{
    "Items": [
        {
            "data": {
                "first_name": "{first_name}",
                "last_name": "{last_name}",
                "name": "{name}",
                "date_of_birth": "{YYYY-MM-DD}",
                "cf1": "{cf1}",
                "ip_address": "{ip_address}",
                "idcard_issuingCountry": "USA",
                "idType": "drivers_license"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "updated_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "kyc_result_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "userid": "{userid}",
            "reviewer": "system",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ],
                "attempts": [
                    {
                        "attemptCnt": 1,
                        "step1Time1st": "YYYY-MM-DD-HH-MM-SS-ZZZ",
                        "ocrResult": "success",
                        "retryMsg": [
                            "Failed to read PDF417 Barcode."
                        ],
                        "idBarcodeResult": "fail",
                        "retryCode": [
                            "barcode_protocol_fail"
                        ]
                    },
                    {
                        "attemptCnt": 2,
                        "step1Time2nd": "YYYY-MM-DD-HH-MM-SS-ZZZ",
                        "ocrResult": "success",
                        "retryMsg": [
                            "Failed to read PDF417 Barcode."
                        ],
                        "idBarcodeResult": "fail",
                        "retryCode": [
                            "barcode_protocol_fail"
                        ]
                    },
                    {
                        "attemptCnt": 3,
                        "step1Time3rd": "YYYY-MM-DD-HH-MM-SS-ZZZ",
                        "ocrResult": "success",
                        "retryMsg": [
                            "Failed to read PDF417 Barcode."
                        ],
                        "idBarcodeResult": "fail",
                        "retryCode": [
                            "barcode_protocol_fail"
                        ]
                    }
                ]
            }
        }
    ]
}

GET/Submission/User ID

Querying for a submission data with specific user_id

  • URL and x-api-key required

  • Should be requested with Query Params

  • It will return submission data which has the same user_id

  • The response includes KYC personal info, KYC result, AML result, reject comment and code, retry comment and code.

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission?userid={userid}"\
-H "x-api-key: {yourAPIKey}"

Sample Request

curl --location --request GET 'https://rest-api.argoskyc.com/v3/submission?userid={userid}' \
--header 'x-api-key: {yourAPIKey}'

Sample Response

{
	"Items": [
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
						"userid" : "{userid}" 
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "BRA",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "pending_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "userid" : "{userid}"
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "test"
                ],
                "commentCode": [
                    "other"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
						"userid" : "{userid}"
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
	           }
	        }
			 }
	  ]
}

GET/Submission/Email

Querying for a submission data with specific email address

  • URL and x-api-key required

  • Should be requested with Query Params

  • It will return submission data which has the same email address

  • The response includes KYC personal info, KYC result, AML result, reject comment and code, retry comment and code

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission?email={email}"\
-H "x-api-key: {yourAPIKey}"

Sample Request

curl -X GET "https://rest-api.argoskyc.com/v3/submission?email={email}"\
-H "x-api-key: {yourAPIKey}"

Sample Response

{
	"Items": [
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "BRA",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "pending_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "test"
                ],
                "commentCode": [
                    "other"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
	           }
	        }
			 }
	  ]
}

GET/Submission/List

Querying for entire submission data

  • URL and x-api-key required

  • Should be requested with Query Params

  • It will return the entire submission data

  • The response includes KYC personal info, KYC result, AML result, reject comment and code, retry comment and code

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission"\
-H "x-api-key: {yourAPIKey}"

Sample Request

curl --location --request GET 'https://rest-api.argoskyc.com/v3/submission' \
--header 'x-api-key: {yourAPIKey}'

Sample Response

"Items": [
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "BRA",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "pending_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "test"
                ],
                "commentCode": [
                    "other"
                ]
            }
        },
        {
            "data": {
                "name": "{name}",
                "gender": "male",
                "nationality": "KOR",
                "date_of_birth": "YYYY-MM-DD"
            },
            "email": "{email}",
            "submission_id": "{submission_id}",
            "created_at": "YYYY-MM-DD-HH-MM-SS-ZZZ",
            "reviewer": "{reviewer}",
            "kyc": {
                "result": "rejected",
                "comment": [
                    "Multiple invalid KYC attempts "
                ],
                "commentCode": [
                    "too_many_retry"
                ]
            }
        }
		}
]

GET/Submission/Applicant ID

Get a list of approved submissions submitted by the same person.

  • If there are multiple submissions from people with the same name, date of birth, nationality, gender, and face, it is judged as duplicate submission, and you can check the duplicate submissions.

  • For a typical applicant that doesn't have duplicate submissions, only a single approved submission is pulled.

  • Since the search is based on applicant_id, applicant_id must be obtained from submission information through GET/Submission API.

  • 'applicant_id' is a combination of name, date of birth, gender, nationality and face image. .

    • Submission data with the same 5 data will have the same 'applicant_id'.

    • 'applicanat_id' is generated randomly if no comparison is found.

Request URL

curl -X GET "https://rest-api.argoskyc.com/v3/submission/applicant?applicant_id={applicant_id}"
-H "x-api-key: {yourAPIKey}"

Input Data

* means required parameters.

ParameterDescription

*applicant_id

Unique identifier for each person

Output Data

ResponseDescription

submission_id

Unique value of submission confirmed as duplicate submission

email

Email address recorded in submission identified as a duplicate submission

Sample Reuqest

curl --location --request GET 'https://rest-api.argoskyc.com/v3/submission/applicant?applicant_id={applicant_id}' \
--header 'x-api-key: {yourAPIKey}'

Sample Response

[
    {
        "submission_id": "{submission_id}",
        "email": "{email}"
    },
    {
        "submission_id": "{submission_id}",
        "email": "{email}"
    },
    {
        "submission_id": "{submission_id}",
        "email": "{email}"
    }
]

Last updated