Skip to content

CredForge: Business Rule Engine (BRE) API

The BRE API provides programmatic access to our comprehensive Business Rule Engine (BRE) platform, delivering enhanced decision making using customised workflows.

Base URL

https://credforge.credeau.com/api

Variables

Variable Description Format Source
client_id Unique identifier for your organization Alphanumeric string Provided by Credeau during onboarding
auth_token Secret token for API authentication Alphanumeric string Provided by Credeau during onboarding
workflow_endpoint Unique API identifier for the workflow you want to execute Alphanumeric string Generated during strategy formation
workflow_name Name of the workflow, representing a strategy Alphanumeric string Generated during strategy formation
user_id Unique identifier for an end user Alphanumeric string, max 64 chars Generated by your application
reference_id Unique identifier for each loan application (lead_id). One customer can have many. Alphanumeric string Generated by your application
app_user_id Unique identifier for an end user registered on MobileGator SDK, if Integrated Alphanumeric string, max 64 chars, non-PII Generated by your application
request_id Unique identifier for each request Alphanumeric string Generated by the API

⚠️ Note

Keep these credentials secure and never share them publicly. These credentials are unique to your organization and will be used to authenticate all API requests.

Endpoints

POST /execute/${client_id}/${workflow_endpoint}

Authentication

The API requires two authentication headers:

Header Value
x-client-id <client_id>
x-auth-token <auth_token>

and, one content type header:

Header Value
Content-Type application/json

Request Parameters

Request Body (JSON)

Parameter Type Required Description
user_id string Yes Unique identifier of the user
reference_id string Yes Unique identifier for each loan application (lead_id). One customer can have many.
input_data json Yes Input parameters required to execute the workflow

⚠️ Note

Fields in input_data vary depending upon the workflow being executed. Please refer to the workflow and sample workflows documentations for the required fields.

Response

Success Responses

HTTP 200 OK (Success)

When a workflow is successfully executed, and decision is made:

{
    "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_<workflow_name>_<version>",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {},
        "features": {}
    }
}

⚠️ Note

Fields in output_data vary depending upon the workflow being executed. Please refer to the workflow and sample workflows documentations for the required fields.

Error Responses

HTTP 401 Unauthorized (Wrong credentials)

This error occurs when either an invalid client ID or authentication token is provided in the request headers. The response includes a request ID that can be used for troubleshooting.

⚠️ Note

If you receive this error:

  1. Verify that you're using the correct client ID and authentication token
  2. Contact Credeau support

HTTP 403 Forbidden (Invalid Access)

This error can occur when the requesting IP address is not whitelisted in the Credeau firewall. For security reasons, all API requests must originate from pre-approved IP addresses.

<html>
    <head><title>403 Forbidden</title></head>
    <body>
        <center><h1>403 Forbidden</h1></center>
    </body>
</html>

⚠️ Note

To resolve this error:

  1. Contact Credeau support to whitelist your IP address
  2. Provide your organization's name and the IP address(es) that need access
  3. Once whitelisted, you'll be able to access the API from the approved IP addresses

HTTP 422 Unprocessable Content (Wrong Request Payload)

This error is returned when any of the required parameters is missing from the request payload. The response includes details about which fields are missing and the received input.

{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "body",
                "user_id"
            ],
            "msg": "Field required",
            "input": {
                "reference_id": "...",
                "fetched_timestamp": "...",
                "raw_data": "...",
                "format_type": "..."
            }
        }
    ]
}

HTTP 429 Too Many Requests (Rate Limit Exceeded)

This error is returned when the rate of requests exceeds the allowed limit of 500 requests per minute per IP.

Best Practice for Rate Limit Handling

When implementing retries for rate-limited requests:

  1. Use exponential backoff: Start with a base delay (e.g., 1 second) and double it after each retry
  2. Add jitter: Include random variation (±20%) to the delay to prevent thundering herd problems

Example implementation:

import random
import time

def get_retry_delay(attempt, base_delay=1, max_delay=60):
    # Calculate exponential backoff
    delay = min(base_delay * (2 ** attempt), max_delay)

    # Add jitter (±20%)
    jitter = delay * 0.2

    return delay + random.uniform(-jitter, jitter)

This approach helps distribute retry attempts and prevents overwhelming the API when rate limits are hit.

HTTP 500 Internal Server Error

This error is returned when the passed input contains unexpected values in correct format.

{
    "detail": "..."
}

Workflow

Workflow is a programatic representation of a business strategy to drive a decision based on custom requirements and respecitve input variables.

A Workflow can contain the following components in an order that justifies a business strategy -

  1. ECM (External Connection Manager) - To fetch data from external sources (Bureau, 3rd Party APIs, etc...) using pre-defined configurable templates for commonly used sources (CIBIL, Crif, Experian, Equifax, and some 3rd party APIs)
  2. Feature Engine - To execute custom logic in the form of Python functions to generate variables from the fetched data and raw data provided by the user
  3. Rule Engine - To apply business rules on the raw/fetched/generated variables to make a decision

Example

Eample Workflow

  1. Input Data
    • name - Full name of the applicant
    • dob - Date Of Birth of the Applicant
    • pan - Pan Number of the Applicant
    • email - Email of the Applicant
    • mobile - Mobile Number of the Applicant
    • address - Address of the Applicant
    • income - Annual Income of the Applicant
    • occupation - Occupation of the Applicant
    • loan_amt - Loan Amount requested by the Applicant
  2. Rule Engine (Basic Checks)
    • age >= 18
    • income >= 50000
    • occupation in ['Salaried', 'Self Employed']
    • address not in Blacklisted Pincodes
    • Decision - Proceed if all above conditions are met else Reject
  3. ECM (Bureau Report)
    • Fetch bureau report using pan, dob and mobile
    • Output - Bureau Report
  4. Feature Engine (Generate Features)
    • Generate features from bureau report
    • Output - Features
  5. Rule Engine (Bureau Checks)
    • bureau_score >= 600
    • obligations <= 20000
    • bounces <= 1
    • Decision - Proceed if all above conditions are met else Reject
  6. ECM (Account Aggregator)
    • Fetch account aggregator report using pan, dob and mobile
    • Output - Account Aggregator Report
  7. Feature Engine (Generate Features)
    • Generate features from account aggregator report
    • Output - Features
  8. Rule Engine (Account Aggregator Checks)
    • obligations <= 20000
    • bounces <= 1
    • Decision - Approved if all above conditions are met else Reject

Sample Workflows

Following are some real world workflows that can be used as reference -

⚠️ Note

In the workflow output, look for the following keys for final decision -

output_data → rules_output → final_decision → <key>

Where key can be one of the following and more -

  • Decision - Final decision of the workflow. Can have values like - Approve, Reject, Proceed To Bank, etc...
  • DecisionReason - Decision reason for the workflow. Can have values like - geocoding bre checked, bureau bre checked, etc...
  • LoanAmount - Approved loan amount for the application. Can have values like - 50000, 100000, etc...

Location BRE

Provides decision based on the provided location information.

Endpoint

POST /execute/${client_id}/location_bre

Request Body

{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "lead_id": "<lead_id>",
        "latitude": <latitude>,
        "longitude": <longitude>
    }
}

Response Body

{
    "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_location_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
            "final_decision": {
                "Decision": "Proceed to Next Rule",
                "DecisionReason": "geocoding bre checked",
                "RulesEvaluation": {},
                "version": "v1",
                "rule_engine_name": "geocoding"
            }
        },
        "features": {
            "output_features": {
                "geocoding": {
                    "state": "uttar pradesh",
                    "pincode": "201301",
                    "city": "noida"
                }
            },
            "prev_output_features": {},
            "geocoding": {}
        }
    }
}

Bureau Mobile BRE

Provides decision based on the Mobile & Bureau Intelligence (Credit Bureau + BureauGator + MobileGator).

Endpoint

POST /execute/${client_id}/bureau_mobile_bre

Request Body

⚠️ Note

The input_data differs based on how the bureau data is passed.

Bureau API called from within the workflow
{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "lead_id": "<lead_id>",
        "app_user_id": "<app_user_id>",
        "declared_income": <income>,
        "pan_number": "<pan_number>",
        "name_aadhar": "<name_aadhar>",
        "address_aadhar": "<address_aadhar>",
        "state_aadhar": "<state_aadhar>",
        "city_aadhar": "<city_aadhar>",
        "pincode_aadhar": "<pincode_aadhar>",
        "phone": "<PHONE>",
        "pan_name": "<PAN_NAME>",
        "dob": "<DOB>",
        "profession": "<profession>",
        "salary_source": "<salary_source>",
        "declared_income": "<declared_income>",
        "loan_purpose": "<loan_purpose>",
        "income_type": "<income_type>",
        "gender": "<gender>"
    }
}
Bureau API called externally
{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "lead_id": "<lead_id>",
        "app_user_id": "<app_user_id>",
        "declared_income": <income>,
        "external": {
            "bureau_type": "<bureau_format_name>",
            "bureau_raw_json": "<base64_encoded_raw_bureau_report>"
        }
    }
}

⚠️ Note

The bureau_format_name supports values like -

  • cibil_json
  • crif_json
  • crif_json_v2
  • crif_xml
  • crif_hardpull
  • experian_softpull_json
  • equifax_softpull_json
  • experian_softpull_json_v2

Encoding a bureau report (Python) -

import base64

def encode_base64(data: str, encoding: str='utf-8') -> str:
    '''
    Convert given string into base64 encoded string
    '''
    b64_encoded_data = base64.b64encode(bytes(data, encoding=encoding))
    return b64_encoded_data.decode(encoding)

Response Body

{
    "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_bureau_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
            "final_decision": {
                "Decision": "Approve",
                "LoanAmount": 5000,
                "RulesEvaluation": {
                    "mobile bre checked": true
                },
                "DecisionReason": "mobile bre checked",
                "version": "v1",
                "rule_engine_name": "mobilegator"
            },
            "basic": {},
            "mobilegator": {}
        },
        "features": {
            "output_features": {
                "bureaugator": {
                    "bureau_score": 700,
                    "cbs_risk_grade": 1,
                    "cbs_stpl_v1": 0.083,
                    "cbs_monthly_affordability_v1": 7000,
                    "bureau_affordability": 6000
                },
                "mobilegator": {
                    "fraud_flag": false,
                    "all_sms_count": 1000,
                    "credeau_payday_score": 0.85,
                    "mobilegator_affordability": 5000,
                    "estimated_salary": 20000
                }
            },
            "bureaugator": {},
            "mobilegator": {},
            "prev_output_features": {},
        }
    }
}

Bank BRE

Provides decision based on the banking data transactions (Account Aggregator or Bank Statement Analyser).

Endpoint

POST /execute/${client_id}/bank_bre

Request Body

⚠️ Note

The input_data differs based on how the banking data is passed.

Account Aggregator API called from within the workflow
{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "request_id": "bank_aa_request_id",
        "bank_type": "bank_aa"
    }
}
Bank Statement Analyzer API called from within the workflow
{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "report_id": "bank_bsa_report_id",
        "auth_token": "bank_bsa_auth_token",
        "bank_type": "bank_bsa"
    }
}
Account Aggregator / Bank Statement Analyser API called externally
{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "lead_id": "<lead_id>",
        "declared_income": <income>,
        "external": {
            "bank_type": "bank_aa/bank_bsa",
            "bank_data": {
                "metadata": {
                    "currency": "<currency>",
                    "bank_name": "<bank_name>",
                    "ifsc_code": "<ifsc_code>",
                    "account_type": "<account_type>",
                    "employer_name": "<employer_name>",
                    "account_number": "<account_number>",
                    "account_holder_name": "<account_holder_name>",
                    "statement_fetch_date": "<statement_fetch_date>",
                    "statement_start_date": "<statement_start_date>",
                    "statement_end_date": "<statement_end_date>"
                },
                "transaction_data": [
                    {
                        "txnId": "S99114288",
                        "type": "DEBIT",
                        "amount": 262.5,
                        "currentBalance": "30585.51",
                        "transactionTimestamp": "2025-05-24 02:45:58",
                        "narration": "UPI/MPOKKET FINANCI/514408328499/OidmpokketVA1b8"
                    },
                    {
                        "txnId": "S63581773",
                        "type": "DEBIT",
                        "amount": 32,
                        "currentBalance": "52339.77",
                        "transactionTimestamp": "2025-06-10 19:42:06",
                        "narration": "UPI/Ganesh Kirana S/106258920869/UPI"
                    },
                    {
                        "type": "DEBIT",
                        "amount": 35,
                        "currentBalance": "52304.77",
                        "transactionTimestamp": "2025-06-11 16:49:35",
                        "txnId": "S99003246",
                        "narration": "UPI/KANTIBHAI DHAMO/106299053289/UPI"
                    }
                ]
            }
        }
    }
}

Response Body

{
    "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_bank_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
            "final_decision": {
                "Decision": "Reject",
                "LoanAmount": null,
                "DecisionReason": "bank bre checked",
                "RulesEvaluation": {},
                "version": "v1",
                "rule_engine_name": "bank"
            },
            "pre_bureau": {}
        },
        "features": {
            "output_features": {}
        },
        "prev_output_features": {},
    }
}

Bureau Mobile Bank BRE

Provides decision based on the Account, Mobile & Bureau Intelligence (Account Aggregator + Credit Bureau + BureauGator + MobileGator).

Endpoint

POST /execute/${client_id}/bureau_mobile_bank_bre

Request Body

{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "lead_id": "<lead_id>",
        "app_user_id": "<app_user_id>",
        "declared_income": <income>,
        "external": {
            "bureau_type": "<bureau_format_name>",
            "bureau_raw_json": "<base64_encoded_raw_bureau_report>",
            "bank_type": "bank_aa/bank_bsa",
            "bank_data": {
                "metadata": {
                    "currency": "<currency>",
                    "bank_name": "<bank_name>",
                    "ifsc_code": "<ifsc_code>",
                    "account_type": "<account_type>",
                    "employer_name": "<employer_name>",
                    "account_number": "<account_number>",
                    "account_holder_name": "<account_holder_name>",
                    "statement_fetch_date": "<statement_fetch_date>",
                    "statement_start_date": "<statement_start_date>",
                    "statement_end_date": "<statement_end_date>"
                },
                "transaction_data": [
                    {
                        "txnId": "S99114288",
                        "type": "DEBIT",
                        "amount": 262.5,
                        "currentBalance": "30585.51",
                        "transactionTimestamp": "2025-05-24 02:45:58",
                        "narration": "UPI/MPOKKET FINANCI/514408328499/OidmpokketVA1b8"
                    },
                    {
                        "txnId": "S63581773",
                        "type": "DEBIT",
                        "amount": 32,
                        "currentBalance": "52339.77",
                        "transactionTimestamp": "2025-06-10 19:42:06",
                        "narration": "UPI/Ganesh Kirana S/106258920869/UPI"
                    },
                    {
                        "type": "DEBIT",
                        "amount": 35,
                        "currentBalance": "52304.77",
                        "transactionTimestamp": "2025-06-11 16:49:35",
                        "txnId": "S99003246",
                        "narration": "UPI/KANTIBHAI DHAMO/106299053289/UPI"
                    }
                ]
            }
        }
    }
}

⚠️ Note

The bureau_format_name supports values like -

  • cibil_json
  • crif_json
  • crif_json_v2
  • crif_xml
  • crif_hardpull
  • experian_softpull_json
  • equifax_softpull_json
  • experian_softpull_json_v2

Encoding a bureau report (Python) -

import base64

def encode_base64(data: str, encoding: str='utf-8') -> str:
    '''
    Convert given string into base64 encoded string
    '''
    b64_encoded_data = base64.b64encode(bytes(data, encoding=encoding))
    return b64_encoded_data.decode(encoding)

Response Body

{
    "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_bureau_mobile_bank_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
            "final_decision": {
                "Decision": "Approve",
                "LoanAmount": 5000,
                "RulesEvaluation": {
                    "bureau bre checked": true
                },
                "DecisionReason": "bureau bre checked",
                "version": "v1",
                "rule_engine_name": "bureaugator"
            },
            "basic": {}
        },
        "features": {
            "output_features": {
                "bureaugator": {},
                "mobilegator": {},
                "accountgator": {}
            },
            "bureaugator": {},
            "mobilegator": {},
            "prev_output_features": {},
        }
    }
}

Repeat BRE

Provides decision for a reapeat customer based on the information already there in the LOS.

Endpoint

POST /execute/${client_id}/repeat_bre

Request Body

{
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "input_data": {
        "pan_number": "<pan_number>",
        "name_aadhar": "<name_aadhar>",
        "address_aadhar": "<address_aadhar>",
        "state_aadhar": "<state_aadhar>",
        "city_aadhar": "<city_aadhar>",
        "pincode_aadhar": "<pincode_aadhar>",
        "phone": "<phone>",
        "dob": "<dob>",
        "max_dpd_last_loan": <max_dpd_last_loan>,
        "max_dpd_ever_internal": <max_dpd_ever_internal>,
        "previous_loan_amount": <previous_loan_amount>,
        "decided_tenure_last_loan": <decided_tenure_last_loan>,
        "actual_tenure_last_loan": <actual_tenure_loan_last>,
        "days_since_last_loan_closed": <days_since_last_loan_closed>,
        "number_of_loans_closed": <number_of_loans_closed>,
        "days_since_last_loan_taken": <days_since_last_loan_taken>,
        "days_since_first_loan_taken": <days_since_first_loan_taken>,
        "flag_current_default": <flag_current_default>,
        "number_of_loans_closed_with_dpd_0_full_cycle": <number_of_loans_closed_with_dpd_0_full_cycle>
    }
}

Response Body

{
  "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_repeat_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
        "final_decision": {
            "Decision": "Approve",
            "LoanAmount": 7000,
            "ReplaymentDate": "2025-05-03",
            "DecisionReason": "repeat bre passed with approval",
            "RulesEvaluation": {},
            "version": "v1",
            "rule_engine_name": "basic"
        },
        },
        "features": {
            "output_features": {
                "basic": {}
            },
            "basic": {},
            "prev_output_features": {}
        }
    }
}

Serving Multiple Products

The workflow samples mentioned above use intelligence based on Bank, Bureau and Mobile data, which are commonly used for serving multiple products like Payday/Bullet Loans, EMI loans, etc... And to cater to all these the input_data remains similar but the output_data changes accrodingly.

For Payday/Bullet Loans

Look for -

  1. output_data → rules_output → final_decision → Decision key in the output response to get the decision.
  2. output_data → rules_output → final_decision → LoanAmount key in the output response to get a fixed amount calculated.

Example -

{
  "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_repeat_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
        "final_decision": {
            "Decision": "Approve",
            "LoanAmount": 7000,
            "ReplaymentDate": "2025-05-03",
            "DecisionReason": "repeat bre passed with approval",
            "RulesEvaluation": {},
            "version": "v1",
            "rule_engine_name": "basic"
        },
        },
        "features": {
            "output_features": {
                "basic": {}
            },
            "basic": {},
            "prev_output_features": {}
        }
    }
}

For EMI Loans

Look for -

  1. output_data → rules_output → final_decision → EmiDecision key in the output response to get the decision.
  2. output_data → rules_output → final_decision → LoanOffers key in the output response to get a list of approved loans.

Example -

{
  "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_bureau_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
        "final_decision": {
            "EmiDecision": "Approve",
            "LoanOffers": [
                {
                    "product_code": "PL_EMI_LT_25K",
                    "tenure_months": 3,
                    "pf_percent": 4,
                    "interest_rate": 25,
                    "emi_amount": 4000,
                    "loan_amount": 10000
                }
            ],
            "DecisionReason": "bureau bre passed with approval",
            "RulesEvaluation": {},
            "version": "v1",
            "rule_engine_name": "bureau_bre"
        },
        },
        "features": {
            "output_features": {}
        }
    }
}

For Payday/Bullet & EMI Loans Combined

For Payday/Bullet Loan, look for -

  1. output_data → rules_output → final_decision → Decision key in the output response to get the decision of Payday/Bullet loan product.
  2. output_data → rules_output → final_decision → LoanAmount key in the output response to get a fixed amount calculated for Payday/Bullet loan product.

For EMI Loan, look for -

  1. output_data → rules_output → final_decision → EmiDecision key in the output response to get the decision of EMI loan product.
  2. output_data → rules_output → final_decision → LoanOffers key in the output response to get a list of approved loans for EMI loan product.

Example -

{
  "request_id": "<request_id>",
    "user_id": "<user_id>",
    "reference_id": "<reference_id>",
    "workflow_version_path": "workflow_bureau_v1",
    "engine_history": [],
    "output_data": {
        "ecm": {},
        "rules_output": {
        "final_decision": {
            "EmiDecision": "Approve",
            "Decision": "Approve",
            "LoanAmount": 7000,
            "LoanOffers": [
                {
                    "product_code": "PL_EMI_LT_25K",
                    "tenure_months": 3,
                    "pf_percent": 4,
                    "interest_rate": 25,
                    "emi_amount": 4000,
                    "loan_amount": 10000
                }
            ],
            "DecisionReason": "bureau bre passed with approval",
            "RulesEvaluation": {},
            "version": "v1",
            "rule_engine_name": "bureau_bre"
        },
        },
        "features": {
            "output_features": {}
        }
    }
}

Consideration

This is a highly customisable API that can serve multiple business strategies. Thus, the fields mentioned in input_data and output_data in the sample workflows above are not limited to the provided values, and will change as per the requirements of the strategy.

Hence, this documentation acts as the integration guide for developers, and the actual API documentation with detailed fields and descriptions will be provided by Credeau's team post strategy finalisation.