Compliance KYABC API (0.1.0)
Download OpenAPI specification:Download
KYC risk rating is formed based on customer data collected by financial institutions.
KryptoGO Compliance evaluates each customer's possible involvement in financial crimes, based on customer risk (sanctions list screening, company-related information, political figures, terrorist lists, court decisions, negative news scan results, etc.), calculate a risk score. This risk score will correspond to a KYC risk rating. According to the level of risk, there are 5 standard types of KYC risk ratings.
- Low risk (0-24 points)
- Low to medium risk (25-49 points)
- Medium risk (50-74 points)
- High risk (75-99 points)
- Very high risk (100 points)
The KYC risk rating ensures compliance with global regulations such as AML, KYC, and CTF/CFT standards. To determine whether the risk factor is really relevant to the customer based on the customer’s personally identifiable information, and conduct EDD (enhanced due diligence) to ask the customer to submit other documents, such as the source of income, confirmation of registered address, etc.
In order to protect your own company from corruption and money laundering, it is extremely important to implement a KYC risk assessment for all customers-this is the most reliable way to determine which customers are riskier to your company and thus avoid liability.
KYC risk ratings can be formed manually or automatically. Although the results cannot be absolutely accurate anyway, large companies with large amounts of information need automation. At KryptoGO, our advanced technology provides each customer with a KYC risk rating, the results are as accurate as possible, and users can be manually rechecked, and our CAMS anti-money laundering specialist can even assist you in risk assessment.
Get blockchain address risk information
Get information of a given blockchain address (only supports BTC/ETH for now):
- Received, sent amount and current balance
- Number of transactions
- Owner (e.g. crypto exchange) of this address
- Risk signals (with sum of all signals equals to 1)
- Risk score calculated from risk signals
Authorizations:
path Parameters
symbol required | string blockchain symbol (should be btc or eth) |
address required | string the blockchain address to search |
Responses
Response samples
- 200
{- "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
- "transaction_count": 439,
- "balance": 0.0367757,
- "received": 12.90683409,
- "sent": 12.87005839,
- "risk_score": 0.9,
- "signals": {
- "atm": 0,
- "dark_market": 0,
- "dark_service": 0,
- "exchange_mlrisk_high": 0.5,
- "exchange_mlrisk_low": 0,
- "exchange_mlrisk_moderate": 0,
- "exchange_mlrisk_veryhigh": 0,
- "exchange_fraudulent": 0,
- "gambling": 0.3,
- "illegal_service": 0,
- "miner": 0.1,
- "mixer": 0.1,
- "p2p_exchange_mlrisk_high": 0,
- "p2p_exchange_mlrisk_low": 0,
- "marketplace": 0,
- "wallet": 0,
- "payment": 0,
- "ransom": 0,
- "scam": 0,
- "stolen_coins": 0
}
}
Create search tasks
Create DD tasks which belong to the owner of API token. Different target attribute should be specified when the search type is KYB or KYC. The callback URL will be called when:
- The task is completed (i.e. the search results are generated)
- The task's accepted status is changed (refer to
[POST] /task/{task_id}/accepted
)
Authorizations:
Request Body schema: application/json
The search task to create
search_setting_id | int The ID of search setting to use |
SearchTaskKycTarget (object) or SearchTaskKybTarget (object) | |
search_source | Array of arrays The array of source to search (Default is searching all):
|
callback_url | string <uri> The URL which will be called when the task is completed, or the task's accepted status is channged |
customer_reference | string The internal customer reference of your system |
from_idv_id | int (Optional) ID of certain IDV task, indicates the source of this search task. If |
Responses
Callbacks
Request samples
- Payload
[- {
- "search_setting_id": 120,
- "target": {
- "type": 1,
- "name": "黃琪",
- "birthday": "1988-02-03",
- "citizenship": "TWN"
}, - "search_source": [
- 0,
- 1,
- 2,
- 3,
- 4
], - "customer_reference": "000000123",
- "from_idv_id": null
}
]
Response samples
- 200
[- {
- "task_id": 123,
- "timestamp": 1623859200
}
]
Callback payload samples
{- "task_id": 123,
- "search_setting": {
- "mode": 1,
- "time_range_year": 3,
- "language": "lang_zh-TW",
- "negative_words": [
- "貪污",
- "詐欺"
], - "number_of_pages": 30
}, - "target": {
- "type": 1,
- "name": "黃琪",
- "birthday": "1988-02-03",
- "citizenship": "TWN"
}, - "customer_reference": "000000123",
- "progress": null,
- "task_origin": 1,
- "creation_time": 1623859200,
- "update_time": 1623867890,
- "audit_time": 1623859200,
- "report": {
- "sanction_matched": false,
- "potential_risk": 12,
- "accepted": true,
- "comment": "The negative news are not related to the target"
}, - "metadata": [
- {
- "key": "Residential Address",
- "value": "123 Main St, Anytown, CA 12345"
}, - {
- "key": "SSN",
- "value": "123-45-6789"
}
]
}
Get information of a search task
Authorizations:
path Parameters
task_id required | string Example: 120 |
Responses
Response samples
- 200
{- "task_id": 123,
- "search_setting": {
- "mode": 1,
- "time_range_year": 3,
- "language": "lang_zh-TW",
- "negative_words": [
- "貪污",
- "詐欺"
], - "number_of_pages": 30
}, - "target": {
- "type": 1,
- "name": "黃琪",
- "birthday": "1988-02-03",
- "citizenship": "TWN"
}, - "customer_reference": "000000123",
- "progress": null,
- "task_origin": 1,
- "creation_time": 1623859200,
- "update_time": 1623867890,
- "audit_time": 1623859200,
- "report": {
- "sanction_matched": false,
- "potential_risk": 12,
- "accepted": true,
- "comment": "The negative news are not related to the target"
}, - "metadata": [
- {
- "key": "Residential Address",
- "value": "123 Main St, Anytown, CA 12345"
}, - {
- "key": "SSN",
- "value": "123-45-6789"
}
]
}
Update a search task's accepted status
When accepted
is updated, the comment
and accepted
fields of this search task can't be changed,
and if this search task has callback URL, the server will call it.
Authorizations:
Request Body schema: application/json
The search task information to update
comment | string The comment of the search task report (usually the reason of accepting/rejecting this target) |
accepted | boolean Whether to accept the target of this search task |
Responses
Request samples
- Payload
{- "comment": "The negative news are not related to the target",
- "accepted": true
}
Response samples
- 200
- 409
{- "task_id": 123,
- "comment": "The negative news are not related to the target",
- "accepted": true
}
Set metadata to the search task
Allow custom metadata of a key-value pair object array to append to the search task.
Authorizations:
Request Body schema: application/json
The key-value pair object array
key | string The key(name) of the metadata |
value | string The value of the metadata |
Responses
Request samples
- Payload
[- {
- "key": "SSN",
- "value": "123-456-7890"
}
]
Response samples
- 200
{- "code": 0
}
Get search task history
Get search task history of a given customer
Authorizations:
query Parameters
page_size required | int Example: page_size=10 The size of a page to return |
page_number required | int Example: page_number=1 The page number (starting from 1) to return |
customer_reference | string Example: customer_reference=000000123 The internal customer reference of your system |
Responses
Response samples
- 200
{- "data": [
- {
- "task_id": 123,
- "search_setting": {
- "mode": 1,
- "time_range_year": 3,
- "language": "lang_zh-TW",
- "negative_words": [
- "貪污",
- "詐欺"
], - "number_of_pages": 30
}, - "target": {
- "type": 1,
- "name": "黃琪",
- "birthday": "1988-02-03",
- "citizenship": "TWN"
}, - "customer_reference": "000000123",
- "progress": null,
- "task_origin": 1,
- "creation_time": 1623859200,
- "update_time": 1623867890,
- "audit_time": 1623859200,
- "report": {
- "sanction_matched": false,
- "potential_risk": 12,
- "accepted": true,
- "comment": "The negative news are not related to the target"
}, - "metadata": [
- {
- "key": "Residential Address",
- "value": "123 Main St, Anytown, CA 12345"
}, - {
- "key": "SSN",
- "value": "123-45-6789"
}
]
}
], - "paging": {
- "page_number": 1,
- "page_size": 10,
- "total_count": 15
}
}
Create an IDV task
Create an IDV task by uploading ID image and selfie face photo (selfie face photo can be replaced with photo of the person holding ID document). A DD search task can be created automatically from the recognized information in images.
Authorizations:
Request Body schema: application/json
The body of the idv task API request
country | string The country of the ID. Should be ISO-3166 Alpha-3 |
id_type | string The type of ID. Supports |
id_image | string The base64 encoding of ID image (front side). Max. 15MB & <8000 pixels per side & longest side >300 pixels |
id_mime_type | string (Optional) Mime type of ID image. Can be |
id_back_image | string (Optional) The base64 encoding of ID image (back side). Required when |
id_back_mime_type | string (Optional) Mime type of ID image back side. Can be |
face_image | string The base64 encoding of face image. At least one of |
face_mime_type | string (Optional) Mime type of face image. Can be |
id_and_face_image | string The base64 encoding of image of the person holding ID document. At least one of |
id_and_face_mime_type | string (Optional) Mime type of image of the person holding ID document. Can be |
expected_name | string (Optional) The expected full name of the ID holder.
If it doesn't match the recognized name on the ID, the result state will be |
expected_birthday | string (Optional) The expected birthday of the ID holder in YYYY-MM-DD format.
If it doesn't match the recognized birthday on the ID, the result state will be |
expected_id_number | string (Optional) The expected ID number of the ID holder.
If it doesn't match the recognized ID number on the ID, the result state will be |
expected_issuing_date | string (Optional) The expected issuing Date of the ID holder.
If it doesn't match the recognized ID number on the ID, the result state will be |
expected_expiry_date | string (Optional) The expected expiry Date of the ID holder.
If it doesn't match the recognized ID number on the ID, the result state will be |
expected_gender | string (Optional) The expected gender of the ID holder.
If it doesn't match the recognized ID number on the ID, the result state will be |
callback_url | string <uri> (Optional) The URL which will be called when the IDV task is completed |
customer_reference | string (Optional) The internal customer reference of your system |
auto_create_dd_task | boolean (Optional) Whether to automatically create DD search task for the target if the result state is |
dd_task_callback_url | string (Optional) The callback URL to use if a DD search task is created from this IDV task |
dd_task_search_setting_id | int (Optional) The ID of search setting to use if a DD search task is created from this IDV task. Required when a DD search task is created |
Responses
Callbacks
Request samples
- Payload
{- "country": "TWN",
- "id_type": "ID_CARD",
- "id_image": "iVBORw0KGgoAAA...",
- "id_mime_type": "image/jpeg",
- "id_back_image": "iVBORw0KGgoAAA...",
- "id_back_mime_type": "image/jpeg",
- "face_image": "iVBORw0KGgoAAA...",
- "face_mime_type": "image/jpeg",
- "id_and_face_image": "iVBORw0KGgoAAA...",
- "id_and_face_mime_type": "image/jpeg",
- "expected_name": "王又曾",
- "expected_birthday": "1990-06-21",
- "expected_id_number": "A123456789",
- "expected_issuing_date": "2020-03-10",
- "expected_expiry_date": "2025-03-10",
- "expected_gender": "M",
- "customer_reference": "000000123",
- "auto_create_dd_task": true,
- "dd_task_search_setting_id": 120
}
Response samples
- 200
- 400
{- "idv_task_id": 12,
- "timestamp": 1623859200
}
Callback payload samples
{- "idv_task_id": 12,
- "country": "TWN",
- "id_type": "ID_CARD",
- "id_sub_type": "NATIONAL_ID",
- "expected_name": "王又曾",
- "expected_birthday": "1990-06-21",
- "expected_id_number": "A123456789",
- "expected_country": "TWN",
- "expected_issuing_date": "2020-03-10",
- "expected_expiry_date": "2025-03-10",
- "expected_gender": "M",
- "customer_reference": "000000123",
- "first_name": "又曾",
- "last_name": "王",
- "full_name": "王又曾",
- "birthday": "1965-03-16",
- "id_number": "A223456789",
- "issuing_date": "2020-03-10",
- "expiry_date": "2025-03-10",
- "gender": "M",
- "state": 0,
- "review_reasons": [
- {
- "code": 500,
- "description": "Name doesn't match expected result"
}
], - "reject_reasons": [
- {
- "code": 100,
- "description": "Manipulated document"
}
], - "created_search_task_id": 102,
- "audit_status": "Accepted",
- "audit_timestamp": 1641982000,
- "auditor_employee_account": "admin",
- "dd_tasks": [
- {
- "id": 15,
- "creation_timestamp": 1641987000,
- "audit_status": 0
}
]
}
Get IDV task detail
Get IDV task detail by an unique IDV id
Authorizations:
path Parameters
idv_id required | string Example: 12 |
Responses
Response samples
- 200
{- "idv_task_id": 12,
- "country": "TWN",
- "id_type": "ID_CARD",
- "id_sub_type": "NATIONAL_ID",
- "expected_name": "王又曾",
- "expected_birthday": "1990-06-21",
- "expected_id_number": "A123456789",
- "expected_country": "TWN",
- "expected_issuing_date": "2020-03-10",
- "expected_expiry_date": "2025-03-10",
- "expected_gender": "M",
- "customer_reference": "000000123",
- "first_name": "又曾",
- "last_name": "王",
- "full_name": "王又曾",
- "birthday": "1965-03-16",
- "id_number": "A223456789",
- "issuing_date": "2020-03-10",
- "expiry_date": "2025-03-10",
- "gender": "M",
- "state": 0,
- "review_reasons": [
- {
- "code": 500,
- "description": "Name doesn't match expected result"
}
], - "reject_reasons": [
- {
- "code": 100,
- "description": "Manipulated document"
}
], - "created_search_task_id": 102,
- "audit_status": "Accepted",
- "audit_timestamp": 1641982000,
- "auditor_employee_account": "admin",
- "dd_tasks": [
- {
- "id": 15,
- "creation_timestamp": 1641987000,
- "audit_status": 0
}
]
}
Initiating an IDV transaction for Web Verification
Call the RESTful API POST endpoint /idv/init
with a JSON object containing the properties
described below to create a transaction for each user. You will receive a JSON object in
the response containing timestamp, idv_task_id and a URL which you can use to present ID
Verification to your user.
There must be more than 500
points remaining to perform this operation. Points will be
deducted after the user successfully uploads the verification information.
A DD search task can be created automatically from the recognized information in images.
Authorizations:
Request Body schema: application/json
The body of the initiate API request
id_type | string (Optional) The type of ID. Supports |
locale | string (Optional) Renders web page in the specified language. Supported locale values:
|
workflow_id | int Applies this acquisition workflow to the transaction. Supported workflowId values:
|
success_url | string (Optional) Redirects to this URL after a successful transaction. Max length is 2047 |
error_url | string (Optional) Redirects to this URL after an unsuccessful transaction. Max length is 255 |
country | string The country of the ID. Should be ISO-3166 Alpha-3 |
expected_name | string (Optional) The expected full name of the ID holder.
If it doesn't match the recognized name on the ID, the result state will be |
expected_birthday | string (Optional) The expected birthday of the ID holder in YYYY-MM-DD format.
If it doesn't match the recognized birthday on the ID, the result state will be |
expected_id_number | string (Optional) The expected ID number of the ID holder.
If it doesn't match the recognized ID number on the ID, the result state will be |
callback_url | string <uri> (Optional) The URL which will be called when the IDV task is completed |
customer_reference | string The internal customer reference of your system. Max length is 100 |
auto_create_dd_task | boolean (Optional) Whether to automatically create DD search task for the target if the result state is |
dd_task_callback_url | string (Optional) The callback URL to use if a DD search task is created from this IDV task |
dd_task_search_setting_id | int (Optional) The ID of search setting to use if a DD search task is created from this IDV task. Required when a DD search task is created |
tw_id_apply_code | int (Support when id_type = ID_CARD and country = TWN) Not Issue = 0, Initial Issue = 1, Reissue = 2, Change = 3 |
tw_id_apply_date | string (Support when id_type = ID_CARD and country = TWN) Issuing date, Republic of China (ROC) format, 7 digits. |
tw_id_issue_site_id | string (Support when id_type = ID_CARD and country = TWN) Issuing location administrative area code, 5 digits, see the Ministry of the Interior API documentation appendix 'Issuing location code comparison' for details.
|
Responses
Callbacks
Request samples
- Payload
{- "id_type": "ID_CARD",
- "locale": "zh-HK",
- "workflow_id": 200,
- "success_url": null,
- "error_url": null,
- "country": "TWN",
- "expected_name": "王又曾",
- "expected_birthday": "1990-06-21",
- "expected_id_number": "A123456789",
- "customer_reference": "000000123",
- "auto_create_dd_task": true,
- "dd_task_search_setting_id": 120,
- "tw_id_apply_code": 2,
- "tw_id_apply_date": "1070102",
- "tw_id_issue_site_id": "10011"
}
Response samples
- 200
- 400
{- "idv_task_id": 15,
- "timestamp": 1641807000
}
Callback payload samples
{- "idv_task_id": 12,
- "country": "TWN",
- "id_type": "ID_CARD",
- "id_sub_type": "NATIONAL_ID",
- "expected_name": "王又曾",
- "expected_birthday": "1990-06-21",
- "expected_id_number": "A123456789",
- "expected_country": "TWN",
- "expected_issuing_date": "2020-03-10",
- "expected_expiry_date": "2025-03-10",
- "expected_gender": "M",
- "customer_reference": "000000123",
- "first_name": "又曾",
- "last_name": "王",
- "full_name": "王又曾",
- "birthday": "1965-03-16",
- "id_number": "A223456789",
- "issuing_date": "2020-03-10",
- "expiry_date": "2025-03-10",
- "gender": "M",
- "state": 0,
- "review_reasons": [
- {
- "code": 500,
- "description": "Name doesn't match expected result"
}
], - "reject_reasons": [
- {
- "code": 100,
- "description": "Manipulated document"
}
], - "created_search_task_id": 102,
- "audit_status": "Accepted",
- "audit_timestamp": 1641982000,
- "auditor_employee_account": "admin",
- "dd_tasks": [
- {
- "id": 15,
- "creation_timestamp": 1641987000,
- "audit_status": 0
}
]
}