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 v5.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 v5.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/v5.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 Entity 2 Name Description Example
Result Attributes datasetInfo    datasetInfo
[Entity] 
Dataset information
Result Attributes datasetInfo    collectionStartDate
[timestamp]
start date/time showing when the dataset is collected by the SDK.

Timestamp uses ISO-8601 format:
YYYY-MM-DDThh24:mi:ssZ and expressed in GMT.
"2020-12-16T02:26:44.82" 
Result Attributes
datasetInfo
  collectionEndDate
[timestamp]
End date/time showing when the dataset is collected by the SDK.

Timestamp uses ISO-8601: YYYY-MM-DDThh24:mi:ssz and expressed in GMT.
 "2020-12-16T02:26:49.48"
Result Attributes
datasetInfo
  rawDataSetFileSize
[integer]
Size of the dataset in kb.  500 
Result Attributes
datasetInfo
  osVersion
[string]
Operating system version.  "8.0.0"
Result Attributes
datasetInfo
  permissions
[array of permissions entity]
Details of permissions granted by end user.   
Result Attributes
datasetInfo
permissions name
[string]
Name of the permissions.  Android sample:

android.permission.READ_CONTACTS

iOS sample:

NSAppleMusicUsageDescription 
Result Attributes
datasetInfo
permissions value
[integer] 
Flag whether the permission has been granted.

Permission not granted = 0

Granted permission = 1

Not requested = 2

For value = 2, it is only available for Android
"0"
Result Attributes
datasetInfo
  referenceNumber
[string]
The unique reference code for each dataset and score. "12345678" 
Result Attributes
datasetInfo
  uploadDate
[timestamp]
Date/time when the dataset is uploaded into the credolab server.

Timestamp uses ISO-8601: YYYY-MM-DDThh24:mi:ssz and expressed in GMT.
 "2020-12-16T02:26:49.48"
Result Attributes
datasetInfo
  source
[integer]
The device/method used to capture the dataset. There are 3 types:

0 - Android, 1 - iOs, 2 - Web.
 "0"
Result Attributes
datasetInfo
  device
[device entity]
Device details captured by the credolab process.   
Result Attributes
datasetInfo
device indetifier
[string] 
Device identifier generated by credolab engine. "08f7e908965f05febee0560ae20606f4" 
Result Attributes
datasetInfo
device model
[string] 
Device model name.

Only available for source = iOS and source = Android. Else, null.
"SM-G930F" 
Result Attributes
datasetInfo
device brand
[string] 
Device brand name.

Only available for source = iOS and source = Android. Else, null.
"samsung" 
Result Attributes
datasetInfo
device os
[string] 
Device Operating system.  "Android" 
Result Attributes
datasetInfo  device  browser
[string] 
Browser type.

Only available when source = Web. Else, it will return null. 
null 
Result Attributes
datasetInfo
 device associatedDataSetsCount
[integer] 
Number of collected datasets associated with same device. The value will be counted starting from 1. 
Result Attributes
datasetInfo

isRepeatableUpload
[boolean] 
Flag whether the device has been used before to capture the dataset.

When the device has been used more than 1 time, it will be marked as true. Else, false. 
true 
Result Attributes
datasetInfo
  requestedData
[timestamp]
Date/time when the API is triggered by the requestor.

Timestamp uses ISO-8601: YYYY-MM-DDThh24:mi:ssz and expressed in GMT.
 "2020-12-16T02:26:49.48"
Result Attributes

  requestor
[string]
E-mail login of the users 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] 
Scorecard code that is defined by credolab.  SC01 
Result Attributes
>scores
  value
[integer]
Score value 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 code that is defined by credolab.  F01 
Result Attributes
fragments
  items
[array of items entity] 
Separate entity with details on each item of fragment.   
Result Attributes
fragments
items name
[string] 
Name of the item in the fragment (customizable, configured by credolab). "education" 
Result Attributes fragments items  value
[string] 
Value of the item that is defined by fragment name.  "5" 

Response body example (Sample from source = Android):


{
   "datasetInfo":{
      "collectionStartDate":"2020-12-16T02:26:44.82",
      "collectionEndDate":"2020-12-16T02:26:49.48",
      "rawDatasetFileSize":500,
      "osVersion":"8.0.0",
      "permissions":[
         {
            "name":"permission.name",
            "value":1
         }
      ],
      "referenceNumber":"12345678",
      "uploadDate":"2020-12-16T02:26:50.04",
      "source":0,
      "device":{
         "identifier":"08f7e908965f05febee0560ae20606f4",
         "model":" SM-G930F",
         "brand":"samsung",
         "os":"Android",
         "browser":null,
         "associatedDatasetsCount":3
      },
      "isRepeatableUpload":true
   },
   "requestedDate":" 2020-12-16T02:39:24.986424",
   "requestor":"requested@test.com",
   "scores":[
      {
         "code":"SC01",
         "value":595,
         "probability":0.0407
      }
   ],
   "fragments":[
      {
         "code":"F01",
         "items":[
            {
               "name":"fragment_property_1",
               "value":"fragment_property_value_1"
            }
         ]
      }
   ]
}

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

Description:

Assesses fraud for applications (or transactions) based on the device and the application details provided. This is available only if the iovation anti-fraud solution is set up.

Parameters:

Name Description
referenceNumber[string] The unique identifier of the dataset for which the fraud result should be provided.
ruleSet[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 Parameters [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 the API_Response (API v5.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 TYou 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
v5.0/account/login 400 password_invalid Invalid password was entered while logging in.
v5.0/account/login 400 subscription_suspended Unable to login to the suspended subscription.
v5.0/account/login 400 profile_inactive Your profile is inactive. Please contact your subscription administrator.
v5.0/account/login 404 user_email_invalid Invalid email was entered while logging in.
v5.0/account/login/refreshToken 400 profile_inactive Your profile is inactive. Please contact your subscription administrator.
v5.0/account/login/refreshToken 400 subscription_suspended Unable to refresh token for the suspended subscription.
v5.0/account/login/refreshToken 404 refresh_token_invalid The provided refresh token is not registered in the system.

DataSets API

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


Note:

1. For the trial user, the user email and password (subscription credential) will be sent to your e-mail within 1-3 days upon sign up.
2. Please select and test credolab API v5.0