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}'
1
curl -H "x-api-key: {yourAPIKey}" "https://rest-api.argoskyc.com/..."
Copied!

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

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

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

Sample Response1. Get one

1
{
2
"Items": [
3
{
4
"data": {
5
"name": "Jhon Smith",
6
"gender": "male",
7
"nationality": "USA",
8
"date_of_birth": "1998-11-12",
9
"cf1": "test",
10
"ip_address": "*.*.*.*",
11
"idcard_issuingCountry": "USA",
12
"idcard_issueDate": "2016-08-16",
13
"idType": "government_id",
14
"identityNumber": "981112-1******"
15
},
16
"email": "[email protected]",
17
"submission_id": "gt7rcxx9l1o*****",
18
"created_at": "2022-04-07T00:30:35.919Z",
19
"userid": "test1",
20
"kyc": {
21
"result": "rejected",
22
"comment": [
23
"Too many retry "
24
],
25
"commentCode": [
26
"too_many_retry"
27
],
28
"attempts": [
29
{
30
"attemptCnt": 1,
31
"livenessScore": 91,
32
"faceSimilarityScore": 99,
33
},
34
{
35
"attemptCnt": 2,
36
"livenessScore": 98,
37
"retryMsg": "1. Face compare failed: no matching face"
38
},
39
{
40
"attemptCnt": 3,
41
"faceSimilarityScore": 99,
42
"retryMsg": "1. Liveness check failed: Absolute face size is too small"
43
}
44
],
45
}
46
}
47
]
48
}
Copied!

Sample Response 2. Get List

1
{
2
Items: [
3
{
4
data: {
5
name: "John Smith",
6
gender: "male",
7
nationality: "USA",
8
date_of_birth: "1965-08-29",
9
cf1: "test",
10
ip_address: "XX.XX.XXX.XXX"
11
},
12
13
submission_id: "whkksdfyi1on0e",
14
created_at: "2022-01-17T02:05:02.309Z",
15
userid: "John Smith",
16
kyc: {
17
result: "approved"
18
}
19
},
20
{
21
data: {
22
name: "Smith John",
23
gender: "male",
24
nationality: "USA",
25
date_of_birth: "1965-08-29",
26
cf1: "test",
27
ip_address: "XX.XX.XXX.XXX"
28
},
29
30
submission_id: "whksdkyi1i76x",
31
created_at: "2022-01-17T02:00:02.808Z",
32
userid: "John ",
33
kyc: { result: "incomplete"
34
}
35
}
Copied!

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

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

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

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

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

1
{"reviewOCRData":
2
{
3
"ocr_issueDate":"2020-02-25",
4
"ocr_gender":"male",
5
"ocr_nationality":"USA",
6
"ocr_birthDate":"1975-08-25",
7
"ocr_name":"John Smith"
8
},
9
"file_upload":true,
10
"submissionId":"1cz94l9ksfi1bokk"
11
}
Copied!

5. POST /submission/step2

Request URL

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

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

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. 1.
    No face detected in the face image
  2. 2.
    More than two faces detected in the face image
  3. 3.
    Face compare score is below 85
  4. 4.
    Liveness fraud check score is below 50
  5. 5.
    (Korean Only) ID verification fails

Sample Response

pending
retry
{
"verificationResult":"success",
"faceSimilarityScore":99,
"livenessScore":91,
"kycStatus":"pending",
"retryCount":0
}
{
"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

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

Sample Request 1

1
var request = require('request');
2
var options = {
3
'method': 'POST',
4
'url': 'https://rest-api.argoskyc.com/v2/address_code',
5
'headers': {
6
'x-api-key': 'YOUR_API_KEY',
7
'Content-Type': 'application/x-www-form-urlencoded'
8
},
9
form: {
10
'address': '1600 Pennsylvania Avenue NW, Washington, DC 20500, USA'
11
}
12
};
13
request(options, function (error, response) {
14
if (error) throw new Error(error);
15
console.log(response.body);
16
});
Copied!

Sample Request 2

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

Sample Response

1
{
2
"formatted_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500, USA",
3
"compound_code": "VXX7+39 Washington, DC, USA",
4
"global_code": "87C4VXX7+39"
5
}
Copied!

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

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

Input Data

Parameter
Description
submission_id
Submission ID. Unique ID for a specific submission

Sample Response

1
{
2
"message": "success",
3
"content": "Submission #{submissionID} deleted successfully."
4
}
Copied!

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

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

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

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

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.