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
400	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": "[e-mail]",
            "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: "[e-mail]", 
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: "[e-mail]", 
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

pending

{

"verificationResult":"success",

"faceSimilarityScore":99,

"livenessScore":91,

"kycStatus":"pending",

"retryCount":0

}

retry

{

"message": "no match face or 2 face detected",

"kycStatus": "incomplete",

"retryCount": 1

}

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	Language selection for retured value. (ISO 3166-2 Code) (ex. "en")

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.