KYC2020 - API Library

Introduction

The KYC2020 API enables you to integrate your systems with our back-end API services. Our APIs follow a stateless and service-oriented architecture. The REST convention is used and it accepts and returns JSON data. The API is organized in a variety of ways i.e. GET, POST, DELETE depending on the type of operation performed.

Here are a few points to note

  • All requests should use the KYC2020 root API URL
  • API URL is dynamic and should start with base URL: https://api.kyc2020.com/
  • All API requests must be made over HTTPS
  • All API calls must be accompanied with credentials explained in the Authentication section

Authentication

The KYC2020 API uses a combination of account Email ID and API key to authenticate requests. The API Key can be found within your subscription in the KYC2020 Single Sign-On Portal.

Please ensure you follow best practices for managing your API credentials.

A few thing you may want to consider are:

  • Provide your API key and Email in the Authorization header of the API request
  • Do not share API keys or give them to parties outside your organization
  • Never store your API keys in publicly-accessible locations
Field Name Type Description
apikey String Your KYC2020 Account specific API key
email String Your KYC2020 Account Email ID

HTTP Response Codes

Every API response comes with an HTTP response code. The following section mentions the response codes and their meaning used across the API library.

# Response Code Description
1 200 Success
2 400 Bad Request - Please check your request and ensure it confirms to the documented one
3 401 Authentication Error - Wrong Email or API Key, Un-authorized to access the requested resource, or Account expired.
4 403 Forbidden - The resource can not be accessed
5 404 URL Not found - The resource you are requesting is not found on server
6 405 Wrong method call or request type
7 415 Content Type not defined in the API Request header
8 423 API access is blocked or not available for this account
9 429 Quota Exceeded - Too many requests to serve, retry after some time
10 500 Internal Application Error - There was a problem with the response. Check response object for details,Service Under Maintenance - Service not available right now, retry after some time
11 502 One of the DecisionIQ components (SSE) is unable to serve requests
12 503 KYC Process Interface is down

Application Response Object

Each HTTP response is accompanied by a response object in the response packet that contains the application-specific response status. For all the responses except HTTP status 200, the response object will be in line with the response code and descriptions given in the HTTP Response Codes section. Here is a description of the fields in the response object.

Field Name Type Description
code String Status Code
status String Brief Status e.g. 'OK', 'ERROR', 'UNAUTHORIZED' etc
message String Descriptive message for the status

Here are the KYC2020 API status codes and their meaning for HTTP response 200.

Code Description
2000 All good, a proper response was sent.
2001 No data pertaining to the request could be found.
3000 One of the KYC2020 Decision components is unable to serve request.
4001 Malformed JSON Request, API Key not defined, or Name is left blank.
4011 Invalid Private Key or Email, Insufficient privilege for requested Lists or subscription expired.
4051 Invalid Request Method.
4151 Content Type in the request header is not defined.
4231 Account is locked or you do not have API access.
4291 Search quota exhausted or too many requests within a short span of time, or more parallel requests than the account limits.
5001 KYC2020 Component down, unable to serve request.

Rate Limit

The number of concurrent connections the server can handle depends on many factors such as the current load on the server and your account configuration. The API comes with throttling and overload protection.

Based on your account privilege, the API controls the number of requests you can make in a specific interval measured as quota per second (QPS). If you are sending a large number of requests within a short span of time and that exceeds the QPS setup for your account, you are most likely going to be denied a response for some of the requests. In this kind of scenario, we recommend you retry sending the failed requests after a few seconds by interleaving the successive requests.

In spite of that, if you continue to experience service denials, you may need to upgrade your account to increase the quota setup. Please reach out to our support desk for further assistance.

Endpoint Descriptions - Screening Services

# End Point Description
1 POST /ss/v3/smartscan SmartScan request
2 POST /ss/v3/decisioniq/{include_smartscan} DecisionIQ request along with the option to perform SmartScan screening as well
3 POST /ss/v1/adversemedia/{include_smartscan} Adverse Media request along with option to perform SmartScan screening as well

Endpoint Descriptions - AUM

Customer List
# End Point Description
1 GET /aum/customerlist/{customerlistname} Details of a Customer List with information such as preferences and ongoing monitoring schedule details
2 POST /aum/customerlist Create or update a Customer List
3 DELETE /aum/customerlist/{customerlistname} Delete a Customer List
Watchlist
# End Point Description
1 GET /aum/watchlistgroup View all watchlist groups available
2 GET /aum/watchlistgroup/{watchlistname}/details View the watchlist details included in the specified watchlist group
Scan Summary
# End Point Description
1 GET /aum/scansummary Scan summary of all Customer Lists setup for Ongoing Monitoring for the current date
2 GET /aum/scansummary/{date} Scan summary of all Customer Lists setup for Ongoing Monitoring for the specified date
3 GET /aum/scansummary/details Detailed Scan report of all Customer Lists setup for Ongoing Monitoring for current date
4 GET /aum/scansummary/{customerlistname}/details Detailed Scan report of specified Customer List setup for Ongoing Monitoring for current date
5 GET /aum/scansummary/date/{date}/details Detailed Scan report of all Customer Lists setup for Ongoing Monitoring for the specified date
6 GET /aum/scansummary/{customerlistname}/date/{date}/details Detailed Scan report of the specified Customer List setup for the specified date
Audit Summary
# End Point Description
1 GET /aum/auditsummary/{date} Ongoing monitoring audit summary of all customer lists on the mentioned date
2 GET /aum/auditsummary/{date}/{customerlistname} Ongoing monitoring audit summary of specified customer list on the mentioned date
3 GET /aum/auditsummary/{sdate}/{edate}/details Detailed Ongoing monitoring audit of all customer lists between specified dates
4 GET /aum/auditsummary/{sdate}/{edate}/{customerlistname}/details Detailed Ongoing monitoring audit of specified customer list between the mentioned dates
Statistics
# End Point Description
1 GET /aum/rescancount Detail of number of times each record has been re-scanned for all customers
2 GET /aum/rescancount/{sdate}/{edate} Detail of number of times each record has been re-scanned between the specified dates
3 GET /aum/decision/{decisionchange}/details Detailed report of records with Alerts or No Alerts [Alert indicates a change in decision from the original one]
4 GET /aum/decision/{customerlistname}/{decisionchange}/details Detailed report of records with Alerts or No Alerts for the specified Customer List
5 GET /aum/decision/{sdate}/{edate}/{decisionchange}/details Detailed report of records with Alerts or No Alerts between specified dates
6 GET /aum/decision/{customerlistname}/date/{sdate}/{edate}/{decisionchange}/details Detailed report of records with Alerts or No Alerts for the specified Customer List between the mentioned dates
Bulk Upload
# End Point Description
1 POST /aum/batch/upload/scan Upload Customer records in Bulk for screening - clearing and adding to a Customer List for Ongoing Monitoring.

API Collections

The following section describes the various API classes and collections available.

Loader
Please Wait