BureauGator: Bureau API¶

The BureauGator API provides programmatic access to our comprehensive bureau intelligence platform, delivering enhanced risk assessment and income estimation capabilities through advanced multi-bureau data processing.

Base URL¶

https://gator.credeau.com

Variables¶

The following variables will be referenced throughout this documentation:

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
`user_id`	Unique identifier for an end user	Alphanumeric string, max 64 chars, non-PII	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

⚠️ 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¶

Bureau API¶

POST /api/bureau

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.
`fetched_timestamp`	string	Yes	Timestamp when the report was fetched
`raw_data`	string	Yes	Base64 encoded string of the fetched report
`format_type`	string	Yes	Format type of fetched report (Bureau Name & Data Format)

Encoding a fetched 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)

⚠️ Note

The format_type can have one of the following values -

cibil_json

crif_json

crif_json_v2

crif_xml

crif_hardpull

experian_softpull_json

equifax_softpull_json

Follow here for detailed response structures.

Response¶

Response Fields (JSON)¶

Field Name	Description
`reference_id`	`<reference_id>`
`feature_name`	`feature_value`

⚠️ Note

The response will have multiple features with associated values of varying data types.

Success Responses¶

HTTP 200 OK (Success)¶

When the bureau report is successfully processed and features are generated:

{
    "reference_id": "<reference_id>",
    "cbs_stpl_v1": 0.0067,
    "cbs_monthly_affordability_v1": 500,
    "cbs_risk_grade_v1": 0,
    "is_risky_customer": false,
    "score": 700,
    "income_calculated": 30000
    ...
}

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:

Verify that you're using the correct client ID and authentication token

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:

Contact Credeau support to whitelist your IP address

Provide your organization's name and the IP address(es) that need access

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 1000 requests per minute per IP.

Best Practice for Rate Limit Handling

When implementing retries for rate-limited requests:

Use exponential backoff: Start with a base delay (e.g., 1 second) and double it after each retry
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 raw_data field has an invalid json or encoded string is not correct.

{
    "detail": "error in decoding raw_data: …"
}

Example Usage¶

cURL¶

curl --location 'https://gator.credeau.com/api/bureau' \
--header 'x-client-id: <client_id>' \
--header 'x-auth-token: <auth_token>' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "sample_user",
    "reference_id": "sample_ref",
    "fetched_timestamp": "2024-08-11 16:07:56",
    "format_type": "crif_json",
    "raw_data": "<base64 encoded bureau response>"
}'

Python¶

import requests
import json
import base64

def fetch_bureau_insights(client_id, auth_token, user_id, reference_id, fetched_timestamp, raw_data, format_type, timeout=30):
    """
    Fetch bureau insights from the BureauGator API.

    Args:
        client_id (str): Client identifier
        auth_token (str): Authentication token
        user_id (str): User identifier
        reference_id (str): Unique identifier for each loan application (lead_id)
        fetched_timestamp (str): Timestamp when the report was fetched
        raw_data (str): Base64 encoded string of the fetched report
        format_type (str): Format type of fetched report (Bureau Name & Data Format)
        timeout (int): Maximum time in seconds to wait for the response (default: 30)

    Returns:
        dict: The response containing bureau insights data

    Raises:
        Exception: If request fails or timeout is exceeded
    """
    url = "https://gator.credeau.com/api/bureau"

    headers = {
        "x-client-id": client_id,
        "x-auth-token": auth_token,
        "Content-Type": "application/json"
    }

    payload = {
        "user_id": user_id,
        "reference_id": reference_id,
        "fetched_timestamp": fetched_timestamp,
        "raw_data": raw_data,
        "format_type": format_type
    }

    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    return response.json()

# Example usage
client_id = "<client_id>"
auth_token = "<auth_token>"
user_id = "sample_user"
reference_id = "sample_ref"
fetched_timestamp = "2024-08-11 16:07:56"
format_type = "crif_json"
raw_data = "<base64 encoded bureau response>"

result = fetch_bureau_insights(client_id, auth_token, user_id, reference_id, fetched_timestamp, raw_data, format_type, timeout=30)
print(json.dumps(result, indent=2))

⚠️ Note

The timeout parameter should be carefully configured based on your specific use case:

For real-time user journeys (e.g., instant loan approvals), use shorter timeouts (20-30 seconds)

For background processing or batch operations, longer timeouts (30-60 seconds) are recommended

Consider implementing a timeout strategy that balances user experience with system reliability

Rate Limiting -

The API implements rate limiting with 429 (Too Many Requests) responses

For production environments, consider implementing exponential backoff for rate-limited requests as suggested here

Bureau Response Structure¶

`cibil_json`¶

{
    "controlData": {
        "success": true
    },
    "consumerCreditData": [
        {
            "tuefHeader": {
                "headerType": "TUEF",
                "version": "12",
                "memberRefNo": "NB8851",
                "enquiryMemberUserId": "NB88518888_CIRC2CNPE",
                "subjectReturnCode": 1,
                "enquiryControlNumber": "009267923320",
                "dateProcessed": "30062025",
                "timeProcessed": "001827"
            },
            "scores": [
                {
                    "scoreName": "CIBILTUSC3",
                    "scoreCardName": "16",
                    "scoreCardVersion": "10",
                    "scoreDate": "30062025",
                    "score": "00162"
                }
            ],
            "enquiries": [
                {
                    "index": "I001",
                    "enquiryDate": "29062025",
                    "memberShortName": "NOT DISCLOSED",
                    "enquiryPurpose": "10",
                    "enquiryAmount": 10000
                },
                {
                    "index": "I002",
                    "enquiryDate": "23072024",
                    "memberShortName": "NOT DISCLOSED",
                    "enquiryPurpose": "10",
                    "enquiryAmount": 10000
                },
                {
                    "index": "I003",
                    "enquiryDate": "03052024",
                    "memberShortName": "NOT DISCLOSED",
                    "enquiryPurpose": "10",
                    "enquiryAmount": 10000
                }
            ],
            "names": [],
            "ids": [],
            "telephones": [],
            "emails": []
        }
    ],
    "consumerSummaryData": {
        "accountSummary": {
            "totalAccounts": 0,
            "overdueAccounts": 0,
            "zeroBalanceAccounts": 0,
            "highCreditAmount": 0,
            "currentBalance": 0,
            "overdueBalance": 0,
            "recentDateOpened": "01011900",
            "oldestDateOpened": "01011900"
        },
        "inquirySummary": {
            "totalInquiry": 3,
            "inquiryPast30Days": 1,
            "inquiryPast12Months": 1,
            "inquiryPast24Months": 1,
            "recentInquiryDate": "29062025"
        }
    }
}

`crif_json`¶

{
    "cir_report_file": {
        "header_segment": {},
        "request_data": {},
        "request_status": [],
        "report_data": {
            "standard_data": {
                "demogs": {
                    "variations": []
                },
                "employment_details": [],
                "tradelines": [],
                "inquiry_history": [],
                "score": []
            },
            "requested_services": [],
            "accounts_summary": {
                "primary_accounts_summary": {
                    "number_of_accounts": "9",
                    "active_accounts": "4",
                    "overdue_accounts": "0",
                    "secured_accounts": "2",
                    "unsecured_accounts": "7",
                    "untagged_accounts": "0",
                    "total_current_balance": "105914.0",
                    "current_balance_secured": "70025.0",
                    "current_balance_unsecured": "35889.0",
                    "total_sanctioned_amt": "105914.0",
                    "total_disbursed_amt": "105914.0",
                    "total_amt_overdue": "0.0"
                },
                "secondary_accounts_summary": {
                    "number_of_accounts": "0",
                    "active_accounts": "0",
                    "overdue_accounts": "0",
                    "secured_accounts": "0",
                    "unsecured_accounts": "0",
                    "untagged_accounts": "0",
                    "total_current_balance": "0.0",
                    "total_sanctioned_amt": "0.0",
                    "total_disbursed_amt": "0.0",
                    "total_amt_overdue": "0.0"
                },
                "mfi_group_accounts_summary": {
                    "number_of_accounts": "0",
                    "active_accounts": "0",
                    "overdue_accounts": "0",
                    "closed_accounts": "0",
                    "no_of_other_mfis": "0",
                    "no_of_own_mfis": "0",
                    "total_own_current_balance": "0.0",
                    "total_own_installment_amt": "0",
                    "total_own_disbursed_amt": "0.0",
                    "total_own_overdue_amt": "0.0",
                    "total_other_current_balance": "0.0",
                    "total_other_installment_amt": "0",
                    "total_other_disbursed_amt": "0.0",
                    "total_other_overdue_amt": "0.0",
                    "max_worst_delinquency": "0"
                },
                "additional_summary": [
                    {
                        "attr_name": "NUM-GRANTORS",
                        "attr_value": "5"
                    },
                    {
                        "attr_name": "NUM-GRANTORS-ACTIVE",
                        "attr_value": "4"
                    },
                    {
                        "attr_name": "NUM-GRANTORS-DELINQ",
                        "attr_value": "0"
                    },
                    {
                        "attr_name": "NUM-GRANTORS-ONLY-PRIMARY",
                        "attr_value": "4"
                    },
                    {
                        "attr_name": "NUM-GRANTORS-ONLY-SECONDARY",
                        "attr_value": "0"
                    }
                ],
                "perform_attributes": []
            },
            "trends": {
                "name": "",
                "dates": "",
                "values": "",
                "reserved1": "",
                "reserved2": "",
                "reserved3": "",
                "description": ""
            },
            "alerts": [
                {
                    "type": "",
                    "description": "",
                    "reserved1": ""
                }
            ]
        }
    }
}

`crif_json_v2`¶

{
    "INDV-REPORT-FILE":{
        "INDV-REPORTS":{
            "INDV-REPORT":{
                "HEADER":{},
                "REQUEST":{},
                "STATUS-DETAILS":{},
                "PERSONAL-INFO-VARIATION":{},
                "SECONDARY-MATCHES":null,
                "ACCOUNTS-SUMMARY":{},
                "ALERTS":{},
                "SCORES":{},
                "INQUIRY-HISTORY":{},
                "RESPONSES":{},
                "INDV-RESPONSES":{},
                "GRP-RESPONSES":{}
            }
        }
    }
}

`crif_hardpull`¶

{
    "CIR-REPORT-FILE": {
        "HEADER-SEGMENT": {},
        "REQUEST-STATUS": [],
        "REPORT-DATA": {
            "STANDARD-DATA": {
                "DEMOGS": {
                    "VARIATIONS": []
                },
                "EMPLOYMENT-DETAILS": [],
                "TRADELINES": [],
                "INQUIRY-HISTORY": [],
                "SCORE": []
            },
            "REQUESTED-SERVICES": [],
            "ACCOUNTS-SUMMARY": {
                "PRIMARY-ACCOUNTS-SUMMARY": {
                    "NUMBER-OF-ACCOUNTS": "14",
                    "ACTIVE-ACCOUNTS": "3",
                    "OVERDUE-ACCOUNTS": "0",
                    "SECURED-ACCOUNTS": "0",
                    "UNSECURED-ACCOUNTS": "14",
                    "UNTAGGED-ACCOUNTS": "0",
                    "TOTAL-CURRENT-BALANCE": "24275.0",
                    "CURRENT-BALANCE-SECURED": "0.0",
                    "CURRENT-BALANCE-UNSECURED": "24275.0",
                    "TOTAL-SANCTIONED-AMT": "26000.0",
                    "TOTAL-DISBURSED-AMT": "26000.0",
                    "TOTAL-AMT-OVERDUE": "0.0"
                },
                "SECONDARY-ACCOUNTS-SUMMARY": {
                    "NUMBER-OF-ACCOUNTS": "0",
                    "ACTIVE-ACCOUNTS": "0",
                    "OVERDUE-ACCOUNTS": "0",
                    "SECURED-ACCOUNTS": "0",
                    "UNSECURED-ACCOUNTS": "0",
                    "UNTAGGED-ACCOUNTS": "0",
                    "TOTAL-CURRENT-BALANCE": "0.0",
                    "TOTAL-SANCTIONED-AMT": "0.0",
                    "TOTAL-DISBURSED-AMT": "0.0",
                    "TOTAL-AMT-OVERDUE": "0.0"
                },
                "MFI-GROUP-ACCOUNTS-SUMMARY": {
                    "NUMBER-OF-ACCOUNTS": "0",
                    "ACTIVE-ACCOUNTS": "0",
                    "OVERDUE-ACCOUNTS": "0",
                    "CLOSED-ACCOUNTS": "0",
                    "NO-OF-OTHER-MFIS": "0",
                    "NO-OF-OWN-MFIS": "0",
                    "TOTAL-OWN-CURRENT-BALANCE": "0.0",
                    "TOTAL-OWN-INSTALLMENT-AMT": "0",
                    "TOTAL-OWN-DISBURSED-AMT": "0.0",
                    "TOTAL-OWN-OVERDUE-AMT": "0.0",
                    "TOTAL-OTHER-CURRENT-BALANCE": "0.0",
                    "TOTAL-OTHER-INSTALLMENT-AMT": "0",
                    "TOTAL-OTHER-DISBURSED-AMT": "0.0",
                    "TOTAL-OTHER-OVERDUE-AMT": "0.0",
                    "MAX-WORST-DELINQUENCY": "0"
                },
                "ADDITIONAL-SUMMARY": [
                    {
                        "ATTR-NAME": "NUM-GRANTORS",
                        "ATTR-VALUE": "9"
                    },
                    {
                        "ATTR-NAME": "NUM-GRANTORS-ACTIVE",
                        "ATTR-VALUE": "3"
                    },
                    {
                        "ATTR-NAME": "NUM-GRANTORS-DELINQ",
                        "ATTR-VALUE": "0"
                    },
                    {
                        "ATTR-NAME": "NUM-GRANTORS-ONLY-PRIMARY",
                        "ATTR-VALUE": "3"
                    },
                    {
                        "ATTR-NAME": "NUM-GRANTORS-ONLY-SECONDARY",
                        "ATTR-VALUE": "0"
                    }
                ],
                "PERFORM-ATTRIBUTES": []
            },
            "TRENDS": {
                "NAME": "",
                "DATES": "",
                "VALUES": "",
                "RESERVED1": "",
                "RESERVED2": "",
                "RESERVED3": "",
                "DESCRIPTION": ""
            },
            "ALERTS": [
                {
                    "TYPE": "",
                    "DESCRIPTION": "",
                    "RESERVED1": ""
                }
            ]
        }
    }
}

`experian_softpull_json`¶

{
    "INProfileResponse": {
        "Header": {},
        "UserMessage": {},
        "CreditProfileHeader": {},
        "Current_Application": {
            "Current_Application_Details": {}
        },
        "CAIS_Account": {
            "CAIS_Summary": {},
            "CAIS_Account_DETAILS": []
        },
        "Match_result": {
            "Exact_match": "Y"
        },
        "TotalCAPS_Summary": {},
        "CAPS": {
            "CAPS_Summary": {},
            "CAPS_Application_Details": []
        },
        "NonCreditCAPS": {
            "NonCreditCAPS_Summary": {},
            "CAPS_Application_Details": []
        },
        "SCORE": {
            "BureauScore": "581",
            "BureauScoreConfidLevel": "",
            "CreditRating": ""
        }
    }
}

`experian_xml`¶

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header/>
  <soapenv:Body>
    <processResponse xmlns="http://nextgenws.ngwsconnect.experian.com">
      <processReturn>
        <INProfileResponse>
          <Header>
          </Header>
          <UserMessage>
          </UserMessage>
          <CreditProfileHeader>
          </CreditProfileHeader>
          <Current_Application>
          </Current_Application>
          <CAIS_Account>
          </CAIS_Account>
          <Match_result>
          </Match_result>
          <TotalCAPS_Summary>
          </TotalCAPS_Summary>
          <CAPS>
          </CAPS>
          <NonCreditCAPS>
          </NonCreditCAPS>
          <SCORE>
            <BureauScore>580</BureauScore>
            <BureauScoreConfidLevel/>
          </SCORE>
        </INProfileResponse>
      </processReturn>
    </processResponse>
  </soapenv:Body>
</soapenv:Envelope>

`equifax_softpull_json`¶

{
    "InquiryResponseHeader": {},
    "InquiryRequestInfo": {},
    "Score": [],
    "CCRResponse": {
        "Status": "1",
        "CIRReportDataLst": [
            {
                "InquiryResponseHeader": {},
                "InquiryRequestInfo": {},
                "Score": [],
                "CIRReportData": {
                    "IDAndContactInfo": {},
                    "RetailAccountDetails": [
                        {
                            "seq": "1",
                            "AccountNumber": "**********",
                            "Institution": "BANK",
                            "AccountType": "Credit Card",
                            "OwnershipType": "Individual",
                            "Balance": "14647",
                            "PastDueAmount": "0",
                            "LastPayment": "36942",
                            "Open": "Yes",
                            "HighCredit": "43836",
                            "LastPaymentDate": "2024-10-21",
                            "DateReported": "2024-10-31",
                            "DateOpened": "2019-10-26",
                            "CreditLimit": "60000",
                            "AccountStatus": "Current Account",
                            "source": "INDIVIDUAL",
                            "History48Months": []
                        }
                    ],
                    "RetailAccountsSummary": {
                        "NoOfAccounts": "13",
                        "NoOfActiveAccounts": "6",
                        "NoOfWriteOffs": "0",
                        "TotalPastDue": "0.00",
                        "MostSevereStatusWithIn24Months": "WOF",
                        "SingleHighestCredit": "100813.00",
                        "SingleHighestSanctionAmount": "3680000.00",
                        "TotalHighCredit": "211462.00",
                        "AverageOpenBalance": "605730.83",
                        "SingleHighestBalance": "3514556.00",
                        "NoOfPastDueAccounts": "1",
                        "NoOfZeroBalanceAccounts": "2",
                        "RecentAccount": "Housing Loan on 23-10-2021",
                        "OldestAccount": "Credit Card on 06-04-2016",
                        "TotalBalanceAmount": "3634385.00",
                        "TotalSanctionAmount": "3763808.00",
                        "TotalCreditLimit": "602000.0",
                        "TotalMonthlyPaymentAmount": "33057.00"
                    },
                    "ScoreDetails": [],
                    "EnquirySummary": {},
                    "OtherKeyInd": {},
                    "RecentActivities": {}
                }
            }
        ]
    }
}