Getting started

​​Credolab's credit scores and fragments can be retrieved with one simple API. Below find the steps to call our API:

  1. Make sure you have successfully embed credoSDK into your app and initialise the data collection and upload to our server.
    PS: we are not able to generate any scores and fragments without the collecting any data
  2. Make sure you have received the subscription credentials inside your e-mail inbox. It usually takes 1-3 days to receive them after you sign up. This is the precondition for obtaining our score and the various fragments.
  3. Login at https://scoring-sales.credolab.com/ (this is the host during the trial period).
  4. Retrieve the score value and the fragments. Score results can be obtained via the reference number declared during dataset upload.

    Note: Since this is a trial version, the system is configured with a Testing Scorecard. We do not recommend you to use this scores to make credit decisions in production.

Accounts API - Introduction

This method intended for authentication in the credolab system. The user email and password (subscription credential) will be sent to your e-mail within 1-3 days upon sign up.

POST v6.0/account/login

Description:

Obtain security token value with subscription credentials. Token expiration time is 60 minutes.

Parameters:

Name Description
userEmail[string] User email password[string] Password

Request body example (application/json):


{
	"userEmail": "example@ww.ww",
	"password": "TestPasswordValue"
}

Response:

Security token information.

Response body example (application/json):


{
	"access_token": "access_token_value",
	"token_type": "bearer",
	".issued": "2018-04-08T11:01:41.9286886+03:00",
	".expires": "2018-04-08T11:01:41.9286886+03:00",
	"refresh_token": "sample refresh token"
}

Using of Authorization Token in Request Header

While sending the access token in the Authorization request header field, the client uses the Bearer authentication scheme to transmit the access token.

Authorization: Bearer access_token_value

POST v6.0/account/login/refreshToken

Description:

Refresh the expired access token.

Parameters:

Name Description
refreshToken[string] A Refresh Token is a special kind of token that contains the information required to obtain a new security token.

Request body example (application/json):


{
	"refreshToken": "sample refresh token"
}

Response:

Security token information.

Response body example (application/json):


{
	"access_token": "sample access token",
	"token_type": "bearer",
	".issued": "2018-04-08T11:01:41.9286886+03:00",
	".expires": "2018-04-08T11:01:41.9286886+03:00",
	"refresh_token": "sample refresh token"
}

Datasets API - Introduction

This area is intended to view dataset details and scoring information and requires Authentication.

GET/v6.0/datasets/{referenceNumber}/datasetinsight

Description:

Request dataset insight information.

Parameters:

Name Description
referenceNumber[string] Unique identifier of the dataset registered on the credolab server.

Response Result:

Request dataset insight information.

Response Result Name and Details:

Main Entity Entity 1 Name Description Example
Result Attributes   datasetInfo
[Entity] 
Dataset information
Result Attributes datasetInfo  referenceNumber
[string]
The unique reference code for each dataset and insight. "12345678"
Result Attributes
datasetInfo
uploadDate
[timestamp]
Date/time when the dataset is uploaded to the credolab server.
Timestamp uses ISO-8601: YYYY-MM-DDThh24:mi:ssz and expressed in GMT.
"2021-08-31T06:23:14.342556"
Result Attributes
datasetInfo
source
[integer]
The device platform the dataset is collected from.
There are 3 types: 0 - Android, 1 - iOS, 2 – Web.
0
Result Attributes
  requestedDate
[timestamp]
Date/time when the API is triggered by the requestor.
Timestamp ISO-8601 format: YYYY-MM-DDThh24:mi:ssZ and expressed in GMT.
"2021-08-31T06:25:39.757978"
Result Attributes
  requestor
[string]
E-mail login of the user who triggered the API. requestor@test.com
Result Attributes
scores
[array of scores entity]
Separate entity with details on each scorecard that is deployed on the subscription.
Result Attributes
scores
code
[string]
Component code that is defined by credolab. "SC01"
Result Attributes
scores
value
[integer]
Score value is determined based on the dataset captured and scorecard configured by credolab. 595
Result Attributes
scores
probability
[float]
Probability of default.
Expressed in 4 decimal places.
0.0407
Result Attributes

fragments
[array of fragments entity]
Separate entity with details on each fragment that is deployed on the subscription.
Result Attributes
fragments
code
[string]
Fragment setting code that is defined by credolab based on client’s requirement.

For Android/iOS, credoLab will set up 3 standard fragments: “velocity”, “device” and “permission” on top of the customised fragments (if any)
"device_info"
Result Attributes
fragments
value
[Dynamic - e.g string/array/object];
Fragment value is insight other than score, that can be extracted from the digital footprint of a device.
Fragment value can be customised and displayed in dynamic structure (string/array/object) according to the client’s request.
For Android/iOS, credolab will set up 3 standard fragments: “velocity”, “device” and “permission” on top of the customised fragments (if any). Kindly note that this is only available for paid subscribers.
{ "deviceID":"5c3b94feaa6f3a6ee01e46e58819991c", "osVersion":"10", "brand":"Redmi", "model":"M2006C3LG" }

Response body example (Sample from source = Android):


{
   "datasetInfo":{
      "referenceNumber":"12345678",
      "uploadDate":"2021-08-31T06:23:14.342556",
      "source":0
   },
   "requestedDate":"2021-08-31T06:25:39.757978",
   "requestor":"requestor@test.com",
   "scores":[
      {
         "code":"SC01",
         "value":595,
         "probability":0.0407
      }
   ],
   "fragments":[
      {
         "code":"velocity",
         "value":{
            "isRepeatableUpload":"1",
            "associatedDatasetsCount":"2"
         }
      },
      {
         "code":"device_info",
         "value":{
            "deviceID":"5c3b94feaa6f3a6ee01e46e58819991c",
            "osVersion":"10",
            "brand":"Redmi",
            "model":"M2006C3LG"
         }
      },
      {
         "code":"permission",
         "value":[
            {
               "permission":"READ_CONTACTS",
               "state":"1"
            },
            {
               "permission":"READ_EXTERNAL_STORAGE",
               "state":"1"
            },
            {
               "permission":"READ_CALENDAR",
               "state":"1"
            },
            {
               "permission":"GET_ACCOUNTS",
               "state":"1"
            },
            {
               "permission":"QUERY_ALL_PACKAGES",
               "state":null
            },
            {
               "permission":"BLUETOOTH",
               "state":"1"
            },
            {
               "permission":"ACCESS_WIFI_STATE",
               "state":"1"
            },
            {
               "permission":"USE_FINGERPRINT",
               "state":"1"
            }
         ]
      },
      {
         "code":"fragment_sample",
         "value":{
            "sample_attribute_1":"value",
            "sample_attribute_2":"value"
         }
      }
   ]
}


Response body example (Sample from source = iOS):


{
   "datasetInfo":{
      "referenceNumber":"123456789",
      "source":1,
      "uploadDate":"2021-06-10T15:51:26.327685"
   },
   "requestedDate":"2021-07-23T10:20:16.555Z",
   "requestor":"requestor@test.com",
   "scores":[
      {
         "code":"SC01",
         "value":585,
         "probability":0.0407
      }
   ],
   "fragments":[
      {
         "code":"permissions",
         "value":[
            {
               "permission":"NSPhotoLibraryUsageDescription",
               "state":0
            },
            {
               "permission":"NSContactsUsageDescription",
               "state":0
            },
            {
               "permission":"NSAppleMusicUsageDescription",
               "state":0
            },
            {
               "permission":"NSCalendarsUsageDescription",
               "state":0
            },
            {
               "permission":"NSRemindersUsageDescription",
               "state":0
            }
         ]
      },
      {
         "code":"device_info",
         "value":{
            "deviceID":"12345678910",
            "osVersion":"10",
            "brand":"iPhone",
            "model":"12_mini"
         }
      },
      {
         "code":"velocity",
         "value":[
            {
               "isRepeatableUpload":"1",
               "associatedDatasetsCount":"2"
            }
         ]
      },
      {
         "code":"fragment_sample",
         "value":{
            "sample_attribute_1":"value",
            "sample_attribute_2":"value"
         }
      }
   ]
}



POST/v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} [Not Available for Trial User]


Description:

Assesses risk for transactions based on the provided device and transaction details. Available only if Iovation scoring is set up.

Parameters:

Name Description
referenceNumber[string] The unique identifier of the dataset for which the fraud result should be provided.
rulesetId[string] The identifier for the rule set to use for the transaction. The value is NOT CASE-SENSITIVE.

Request body parameters:

Name Description
accountCode[string] The unique identifier for the end-user's account, or for the transaction.
tranasctionInsight [optional] Transaction attributes that can be sent along with device information, to enable fraud check based on identity data.

Transaction Insight Pararmeters [optional]:

Name Description Example
email [string] Customer's email address. acc@domain.com
eventId[string] ID associated with a transaction. This may be your own system tracking IDs. 168200gsd851
mobilePhoneNumber[string] The user's mobile phone number. +15032246010

Request body example (application/json):


{
    "iovationRequestParams": {
        "accountCode": "string",
        "transactionInsight": {
            "additionalProp1": {},
            "additionalProp2": {},
            "additionalProp3": {}
        }
    }
}

Response Result:

Iovation fraud result

Response Result Name and Details:

Please refer to API_Response (API v6.0) with IOVATION for more details

Response body example (application/json):


{
    "accountCode": "account_code",
    "requestedDate": "2020-01-20T14:33:14.682Z",
    "rulesetId": "rulesetId",
    "requestor": "string",
    "value": {
        "id": "string",
        "result": "string",
        "reason": "string",
        "statedIp": "string",
        "accountCode": "string",
        "trackingNumber": 0,
        "details": {
            "device": {
                "alias": 0,
                "blackboxMetadata": {
                    "age": 0,
                    "timeStamp": "2020-01-20T14:33:14.683Z"
                },
                "firstSeen": "2020-01-20T14:33:14.683Z",
                "isNew": true,
                "mobile": {
                    "brand": "string",
                    "charging": true,
                    "imei": "string",
                    "manufacturer": "string",
                    "model": "string",
                    "orientation": "string",
                    "screenResolution": "string",
                    "app": {
                        "bundleId": "string",
                        "exeName": "string",
                        "debug": true,
                        "marketId": "string",
                        "name": "string",
                        "signerId": "string",
                        "version": "string"
                    },
                    "location": {
                        "enabled": true,
                        "timezone": "string"
                    },
                    "system": {
                        "allowUnknownStore": true,
                        "androidSdkLevel": "string",
                        "buildFingerprint": "string",
                        "carrier": "string",
                        "carrierCountryCode": "string",
                        "hostname": "string",
                        "jailRootDetected": true,
                        "localeCurrency": "string",
                        "localeLang": "string",
                        "networkOperatorCountry": "string",
                        "networkOperatorName": "string",
                        "osVersion": "string",
                        "simulator": true,
                        "uptime": 0
                    },
                    "build": {
                        "device": "string",
                        "product": "string"
                    }
                },
                "os": "string",
                "type": "string"
            },
            "statedIp": {
                "address": "string",
                "isp": "string",
                "parentOrganization": "string",
                "source": "string",
                "ipLocation": {
                    "city": "string",
                    "country": "string",
                    "countryCode": "string",
                    "region": "string",
                    "latitude": 0,
                    "longitude": 0
                }
            },
            "realIp": {
                "address": "string",
                "isp": "string",
                "parentOrganization": "string",
                "source": "string",
                "ipLocation": {
                    "city": "string",
                    "country": "string",
                    "countryCode": "string",
                    "region": "string",
                    "latitude": 0,
                    "longitude": 0
                }
            },
            "ruleResults": {
                "score": 0,
                "rulesMatched": 0,
                "rules": [
                    {
                        "type": "string",
                        "reason": "string",
                        "score": 0
                    }
                ]
            }
        }
    }
}

Error Codes

HTTP Status Code Description
400 The server cannot or will not process the request due to an apparent client error (for example: some required field is empty).
401 You are not authenticated (either not authenticated at all or authenticated incorrectly), please reauthenticate and try again.
403 The request was valid but the server is refusing action. The user might not have the necessary permissions for a resource.
404 The requested resource could not be found.
405 A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.
410 Indicates that the requested resource is no longer available (e.g. dataset file has been deleted from the server).
415 The request entity has a media type which the server (or resource) does not support or media type is missed.
500 A generic error message appearing when an unexpected condition is encountered on the service.
503 An issue with CredoLab server availability.

Error Messages

CredoLab informs API clients of both the high-level error class (using the status code) and the finer-grained details of the problem (using HTTP response body with content type: application/problem+JSON).

The latest approach is [RFC 7807]-based.

An exception has up to 4 properties:

Name Description
Status (integer) The HTTP status code [RFC 7231] for the exception.
Title (string) A short and human-readable summary of the problem type.
Detail (string) A human-readable explanation specific to this occurence of the problem.
Type (string) A URI reference that identifies the problem type.

Example:


{
	"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
	"title": "subscription_suspended",
	"status": 400,
	"detail": "Unable to login to the suspended subscription"
}

Credolab API performs validation of data models that are passed as the body parameters, thus responding with 400(Bad request) status code, e.g:


{
	"errors": {
		"password": [
		"Password is required"
		],
		"userEmail": [
			"Email is required"
		]
	},
	"title": "One or more validation errors occurred.",
	"status": 400
}

Below is the list of the supported error messages for the API actions provided by credolab.

Account API

Action Status Title Details
v6.0/account/login 400 password_invalid Invalid password was entered while logging in.
v6.0/account/login 400 subscription_suspended Unable to login to the suspended subscription.
v6 .0/account/login 400 profile_inactive Your profile is inactive. Please contact your subscription administrator.
v6.0/account/login 404 user_email_invalid Invalid email was entered while logging in.
v6.0/account/login/refreshToken 400 profile_inactive Your profile is inactive. Please contact your subscription administrator.
v6.0/account/login/refreshToken 400 subscription_suspended Unable to refresh token for the suspended subscription.
v6.0/account/login/refreshToken 404 refresh_token_invalid The provided refresh token is not registered in the system.

DataSets API

Action Status Title Details
v6.0/datasets/{refer enceNumber}/datasetinsight 404 reference_number_invalid The specified dataset does not exist on the server.
v6.0/datasets/{refer enceNumber}/datasetinsight 400 insights_is_not_configured Subscription does not have insight configured for the dataset requested.
v6.0/datasets/{refer enceNumber}/datasetinsight 410 dataset_removed The specified dataset has been removed due to retention policies
v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} 400 ruleset_id_invalid The ruleset setting for the provided code was not found in the subscription.
v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} 400 missing_settings No ruleset settings exist for the subscription.
v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} 400 empty_iovation_metadata The dataset does not contain Iovation metadata.
v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} 404 reference_number_invalid The specified dataset does not exist on the server.
v6.0/datasets/{referenceNumber}/iovation/fraud/checks/{rulesetId} 410 dataset_removed The specified dataset has been removed due to retention policies.


Testing on Swagger

You can test the API on swagger by using the following link:

Swagger - Web API v6.0 for Testing