Solutions
About Us
All our API References are detailed here. Please use the table of contents to navigate.
Credolab's credit scores and fragments can be retrieved with one simple API. Below find the steps to call our API:
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.
Methods are intended for Authentication in the Credolab system.
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
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"
}
The area is intended to view dataset details and scoring information and requires Authentication.
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"
}
}
]
}
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
}
]
}
}
}
}
This area is intended to view dataset details and scoring information and requires Authentication.
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"
}
}
]
}
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
}
]
}
}
}
}
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. |
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.
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. |
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. |
You can test the API on swagger by using the following link: