API Guide

You can submit your customer's KYC form data using the Argos API and check the progress of KYC.

The Argos API uses RESTful Endpoints and the default HTTP Method.

  • The response data contains the status of the request and possible error codes.

  • All response data is provided as JSON format.

  • Use token authentication.

  • All requests must be made in HTTPS. HTTP requests will fail.

1. Getting Started

To get started using API you need a valid API key. To obtain an API key, please contact Argos HELPDESK.

2. Authentication

The API uses Token-based authentication.

The API must be provided by Argos in order to use the API.

Authenticate with HTTP Headers

You can send your API key with your query as a HTTP header

The API Key should be included in the method request header as 'x-api-key: {yourAPIKey}'

curl -H "x-api-key: {yourAPIKey}" "https://rest-api.argoskyc.com/..."

Errors

Respond with a generic HTTP response code. At success, it is represented by 2xx code. 4xx occurs when there is an error in the information transmitted on the Client. 5xx occurs when there is an error on the Argos server.

Error Codes

HTTP Code
Message
Description

Invalid Query String parameters

Client error

(e.g. malformed request syntax, invalid request message framing)

403

Forbidden

API KEY is not provided or something is wrong with the API KEY.

413

Request Entity Too Large

The request is larger than the server is willing or able to process.

500

Internal Server Error

It might be Argos server error. Please contact Argos team.

502

Bad Gateway

The server received an invalid response from the upstream server.

3. GET /submission

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.

Request URL

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

Input Data

Parameter
Requirement
Description

submission_id

optional

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

userid

optional

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

optional

A list of submissions matching the email address is returned.

count

optional

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 output by default.

nextpage_id

optional

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

optional

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.

Output Data

Response
Description

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.idType

ID card type <passport, government_id, drivers_license>

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

submission_id

Identifier given to each submission

applicant_id

Identifier given to each applicant

created_at

KYC submitted date and time.

userid

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

kyc

kyc data object

kyc.result

<incomplete, pending, approved, rejected> incomplete: KYC submission is incomplete. It happens when ID card is submitted but selfie is not.

pending: the submission is under manual review

approved: submission is approved

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

kyc.comment

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

kyc.commentCode

Code for KYC reject comment

kyc.attempts

Object of Liveness, Detect face, Face compare

kyc.attempts[i].error

Liveness, Detect face, Face compare error message

kyc.attempts[i].retryMsg

Cause of rejection on Liveness, Detect face, Face compare

kyc.attempts[i].livenessScore

Liveness score on attempt [i]

kyc.attempts[i].faceSimilarityScore

Face similarity 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].resource_id

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

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.

Sample Response1. Get one

{
    "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": [
                    "Too many retry "
                ],
	              "commentCode": [
                    "too_many_retry"
                ],
                "attempts": [
                {
                    "attemptCnt": 1,
                    "livenessScore": 91,
                    "faceSimilarityScore": 99,
                    },
                {
                    "attemptCnt": 2,
                    "livenessScore": 98,
                     "retryMsg": "1. Face compare failed: no matching face"
                },
                {
                 "attemptCnt": 3,
                    "faceSimilarityScore": 99,
                     "retryMsg": "1. Liveness check failed: Absolute face size is too small"
                }
            ],
            }
        }
    ]
}

Sample Response 2. Get List

{ 
Items: [ 
{ 
data: { 
name: "John Smith", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "example@gmail.com", 
submission_id: "whkksdfyi1on0e", 
created_at: "2022-01-17T02:05:02.309Z", 
userid: "John Smith", 
kyc: { 
result: "approved" 
} 
}, 
{ 
data: { 
name: "Smith John", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "example@gmail.com", 
submission_id: "whksdkyi1i76x", 
created_at: "2022-01-17T02:00:02.808Z", 
userid: "John ", 
kyc: { result: "incomplete" 
} 
}

3-1. GET /submission/applicant

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 a 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..

Request URL

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

Input data

Parameter
requirement
Description

applicant_id

required

Unique identifier for each person

Output data

Response
Description

submission_id

Unique value of submission confirmed as duplicate submission

email

Email address recorded in submission identified as a duplicate submission

4. POST /submission/step1

Request URL

curl -X POST "https://rest-api.argoskyc.com/v2/submission/step1" \
-H "x-api-key: {yourAPIKey}" \
--form .

Input data

Parameter
Format
Requirement
Description

issuingCountry

string (ISO3)

*required

ISO alpha 3 format of the country the ID card is issued.

email

string

*required

email address of the KYC applicant

idType

string

*required

<passport, government_id, drivers_license>

idImage

file

*required

jpg, jpeg, png file format of the ID image (size limit: 3mb)

userid

string

optional

custom optional unique identifier of the user

cf1

string

optional

custom optional field

cf2

string

optional

custom optional field

cf3

string

optional

custom optional field

Output Data

Response
Description

submissionId

The unique submission ID of this submission. This ID is required for step 2.

reviewOCRData

OCR object that contains ID card information. If OCR fails, this parameter is not returned.

reviewOCRData.ocr_birthDate

birth date in YYYY-MM-DD format

reviewOCRData.ocr_issueDate

issue date if available

reviewOCRData.ocr_expireDate

expire date if available

reviewOCRData.ocr_lastName

last name if available

reviewOCRData.ocr_firstName

first name if available

reviewOCRData.ocr_name

name if available

reviewOCRData.ocr_gender

gender if available

reviewOCRData.ocr_nationality

ISO3 code format of nationality if available

reviewOCRData.ocr_identityNumber

(KOREAN ID ONLY) Unique personal identity number

reviewOCRData.ocr_licenseNumber

(KOREAN DRIVER LICENSE ONLY) driver license number

file_upload

"true" if the ID card image is successfully received. "false" otherwise.

Sample Response

{"reviewOCRData":
	{
	 	"ocr_issueDate":"2020-02-25",
		"ocr_gender":"male",
	 	"ocr_nationality":"USA",
	 	"ocr_birthDate":"1975-08-25",
		"ocr_name":"John Smith"
	},
	 "file_upload":true,
	 "submissionId":"1cz94l9ksfi1bokk"
	}

5. POST /submission/step2

Request URL

curl -X POST "https://rest-api.argoskyc.com/v2/submission/step2" \
-H "x-api-key: {yourAPIKey}" \
-form ...

Input data

Parameter
Format
Requirement
Description

submissionId

string

*required

The unique submission ID received from step 1.

faceImage

file

*required

A selfie image that has only one face. If multiple faces are detected, it will respond with retry. (size limit: 3mb)

name

string

*required

The format of the name can either be:

• “Lastnames, Firstnames Middlenames” (e.g., “Trump, Donald John”). This is the preferred format for when you know the explicit lastname of the individual.

• “Firstname Middlenames Lastnames” (e.g., “Donald John Trump”). Use this format when you do not explicitly know the lastname of the profile. The algorithm will determine this automatically.

date_of_birth

string

*required

YYYY-MM-DD

gender

string

optional

<male, female>

nationality

string

optional

ISO alpha 3 format of nationality. The nationality is not necessarily same as the ID issued country.

identity_number

string

optional

(KOREAN ID ONLY) This is unique identity number for Korean photo IDs.

license_number

string

optional

(KOREAN DRIVER LICENSE ONLY) license number for ID verification

serial_number

string

optional

(KOREAN DRIVER LICENSE ONLY) 6 letter unique serial number in Korean driver's license

date_of_issue

string

optional

YYYY-MM-DD format of photo ID issue date.

addressImage

file

optional

Address document image to verify the address information. (size limit: 3mb)

address_street

string

optional

street

address_city

string

optional

city

address_state

string

optional

state

address_country

string

optional

country code in ISO 3 format

address_zipcode

string

optional

zip-code (postal code)

globalCode

string

optional

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

compoundCode

string

optional

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

formatted_address

string

optional

Transformed address from detailed code

address_input

string

optional

User input address

address_detail

string

optional

User input detailed address

Output Data

Response
Description

kycStatus

<pending, approved, rejected, incomplete>

If kycStatus is 'pending', the kyc submission is completed, but it will be manually reviewed to finalize whether the submission is approved or rejected.

If kycStatus is 'incomplete', the kyc is not accepted due to invalid KYC data and step 2 retry is recommended until kycStatus returns 'pending', 'approved' or 'rejected'.

faceSimilarityScore

The face similarity score between the face in the photo ID and the selfie face image. The score is ranged from 0 to 100. The closer the socre is to 100, it is more likely that the two faces are matched.

livenessScore

The liveness score evaluates whether the face in the selfie image is a live person or not. The score is ranged from 0 to 100. The closer the score is to 100, it is more likely that the image is a picture of a live person.

verificationResult

<success, fail>

retryCount

Retry count of step 2. If step 2 is attempted more than 3 times, the KYC is rejected.

message

If the kycStatus is "incomplete", message is shown to explain why the KYC application is not accepted.

Notice kycStatus is "incomplete" and retryCount is increased in case of following:

  1. No face detected in the face image

  2. More than two faces detected in the face image

  3. Face compare score is below 85

  4. Liveness fraud check score is below 50

  5. (Korean Only) ID verification fails

Sample Response

{

"verificationResult":"success",

"faceSimilarityScore":99,

"livenessScore":91,

"kycStatus":"pending",

"retryCount":0

}

5-1. POST /address_code

Only available to the projects with address 'collection' option.

Request URL

curl -X POST "https://rest-api.argoskyc.com/v2/address_code" \
-H "x-api-key: {yourAPIKey}" \

Sample Request 1

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest-api.argoskyc.com/v2/address_code',
  'headers': {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    'address': '1600 Pennsylvania Avenue NW, Washington, DC 20500, USA'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Sample Request 2

curl --location --request POST 'https://rest-api.argoskyc.com/v2/address_code' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'language=en' \
--data-urlencode 'address= 1600 Pennsylvania Avenue NW, Washington, DC 20500, USA'

Sample Response

{
    "formatted_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500, USA",
    "compound_code": "VXX7+39 Washington, DC, USA",
    "global_code": "87C4VXX7+39"
}

Input Data

Parameter
Format
Requirement
Description

address

string

Required

You can search by entering one of the following:

  • Address

  • Global code

  • Compound code

  • Latitude and longitude (Separate by comma, ex. 38.897,77.036)

language

string

optional

Output Data

Response
Description

formatted_address

Transformed address from detailed code

compound_code

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

global_code

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

6. DELETE /submission

Delete a single submission data.

It will completely delete the submission data and the image files associated with the submission.

Caution!! Deleted submission cannot be restored.

Sample Request

curl -X DELETE "https://rest-api.argoskyc.com/v2/submission?submission_id={submission_id}"

Input Data

Parameter
Description

submission_id

Submission ID. Unique ID for a specific submission

Sample Response

{
	"message": "success",
	"content": "Submission #{submissionID} deleted successfully."
}

7. GET /report/aml

Returns an application/pdf report of AML screening result.

AML report is provided for each 'resourceId'. 'resourceId' is required to download AML report.

Request URL

curl -X GET "https://rest-api.argoskyc.com/v2/report/aml?resourceId={resourceId}"

Input Data

Parameter
Description

resourceId

'resourceId' is a unique number of a person screened as a result of AML screening.

'resourceId' can be found if a submission is screened for AML Red-Flag.

Each matching AML screening result has a unique 'resourceId'.

One submission may have multiple matches; therefore, multiple 'resourceId'.

Output Data

As a response, application/pdf file format of the report is downloaded.

8. GET /image

Request URL

curl -X GET "https://rest-api.argoskyc.com/v2/image?submission_id={submission_id}&type={type}"

Input Data

Parameter
Requirement
Description

submission_id

required

unique submission Id.

type

required

<idImage, selfieImage, addressImage>

idImage: downloads the image of photo ID

selfieImage: downloads the face image

addressImage: downloads the address document if the submission has such file.

Output Data

As a response, document file is downloaded.

PreviousFAQNextAPI Errors

Last updated