BaridiBaridi BI API Integration Guide

Overview#

The BaridiBaridi BI APIs provide comprehensive business intelligence and customer evaluation services. The API is built using FastAPI and follows OpenAPI 3.1.0 specifications.

Base URL: https://apis.bi.baridibaridi.co.tz

OpenAPI Specification: https://apis.bi.baridibaridi.co.tz/openapi.json

API Services#

The API provides two main service categories:

1. Customer Evaluation API - Credit evaluation and package recommendations
2. Dashboard API - Customer asset tracking and statistics

Customer Evaluation API#

The Customer Evaluation API uses a Random Forest Classifier for intelligent credit evaluation and package recommendations based on customer data and AC unit configurations.

Create Enhanced Evaluation#

Submit a comprehensive customer evaluation with AC units configuration.

Endpoint: POST /api/evaluation/v1/evaluations

Request Body Parameters#

AC Units Object (ac_units)#

Route Data Object (route_data)#

Coordinates Object (route_data.coordinates)#

Request Body Example:

{
  "customer_name": "Example Restaurant Ltd",
  "customer_zoho_id": "ZCRM_12345",
  "phone": "+255712345678",
  "email": "contact@example.com",
  "address": "123 Main Street, Dar es Salaam",
  "business_type": "Restaurant",
  "business_age": 5,
  "is_seasonal_business": false,
  "property_type": "Commercial",
  "property_size": "Large",
  "ac_units": {
    "small": 2,
    "medium": 3,
    "large": 1
  },
  "package_type": "Commercial",
  "estimated_cost": 15000000,
  "route_data": {
    "distance": "15.2 km",
    "duration": "25 min",
    "fuel_cost": "TZS 12,150",
    "route_type": "Real Roads",
    "coordinates": {
      "warehouse": {
        "lat": -6.7924,
        "lng": 39.2083
      },
      "customer": {
        "lat": -6.8160,
        "lng": 39.2803
      }
    }
  },
  "additional_requirements": "Installation needed on weekends",
  "preferred_date": "2025-12-15",
  "preferred_time": "Morning"
}

Response:

{
  "success": true,
  "data": {
    "evaluation_id": "eval_12345",
    "credit_score": 85,
    "recommendation": "Approved",
    "risk_level": "Low"
  },
  "message": "Evaluation completed successfully"
}

cURL Example:

curl -X POST "https://apis.bi.baridibaridi.co.tz/api/evaluation/v1/evaluations" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Example Restaurant Ltd",
    "customer_zoho_id": "ZCRM_12345",
    "business_type": "Restaurant",
    "business_age": 5,
    "is_seasonal_business": false,
    "property_type": "Commercial",
    "property_size": "Large",
    "ac_units": {
      "small": 2,
      "medium": 3,
      "large": 1
    },
    "package_type": "Commercial",
    "estimated_cost": 15000000,
    "route_data": {
      "distance": "15.2 km",
      "duration": "25 min",
      "fuel_cost": "TZS 12,150",
      "route_type": "Real Roads",
      "coordinates": {
        "warehouse": {"lat": -6.7924, "lng": 39.2083},
        "customer": {"lat": -6.8160, "lng": 39.2803}
      }
    }
  }'

Get Package Recommendation#

Get intelligent package recommendations based on AC unit configuration.

Endpoint: POST /api/evaluation/v1/package-recommendation

Query Parameters#

Response:

{
  "package": "Commercial",
  "total_units": 6,
  "total_cost": 8500000,
  "breakdown": {
    "small": {
      "count": 2,
      "cost": 2000000
    },
    "medium": {
      "count": 3,
      "cost": 4500000
    },
    "large": {
      "count": 1,
      "cost": 2000000
    }
  }
}

cURL Example:

curl -X POST "https://apis.bi.baridibaridi.co.tz/api/evaluation/v1/package-recommendation?ac_units_small=2&ac_units_medium=3&ac_units_large=1" \
  -H "Content-Type: application/json"

Get Evaluations List#

Retrieve a paginated list of all customer evaluations.

Endpoint: GET /api/evaluation/v1/evaluations

Query Parameters#

Response:

{
  "page": 1,
  "per_page": 20,
  "total": 150,
  "data": [
    {
      "id": "eval_12345",
      "customer_name": "Example Restaurant Ltd",
      "created_at": "2025-11-20T10:30:00Z",
      "status": "approved",
      "total_cost": 15000000
    }
  ]
}

Get Leads#

Retrieve a comprehensive paginated list of all customer evaluation leads with advanced filtering.

Endpoint: GET /api/evaluation/v1/

Query Parameters#

cURL Example:

curl -X GET "https://apis.bi.baridibaridi.co.tz/api/evaluation/v1/?page=1&per_page=25&from_date=2025-10-01&to_date=2025-11-20&business_type=Restaurant&status=approved"

Search Leads#

Search for specific customer evaluations by name or Zoho CRM ID.

Endpoint: GET /api/evaluation/v1/search

Query Parameters#

cURL Example:

curl -X GET "https://apis.bi.baridibaridi.co.tz/api/evaluation/v1/search?customer_name=Example%20Restaurant&page=1&per_page=25"

Get Conversion Rates#

Retrieve lead conversion statistics within a specified date range.

Endpoint: GET /api/evaluation/v1/conversionrates

Query Parameters#

Response:

{
  "Single_AC": {
    "Single_AC_Count": 45,
    "Multiple_AC_Count": 23,
    "Single_Checklist_Admits": 12,
    "Single_Non_Checklist_Admits": 33,
    "Multiple_Checklist_Admits": 8,
    "Multiple_Non_Checklist_Admits": 15,
    "SL1_Count": 10,
    "SL2_Count": 20,
    "SL3_Count": 15,
    "ML1_Count": 5,
    "ML2_Count": 10,
    "ML3_Count": 8
  }
}

Pricing Management#

Get Current Pricing#

Retrieve the current pricing configuration for AC units.

Endpoint: GET /api/evaluation/v1/pricing/current

Response:

{
  "commercial": {
    "small": 1000000,
    "medium": 1500000,
    "large": 2000000
  },
  "corporate": {
    "small": 1200000,
    "medium": 1800000,
    "large": 2500000
  }
}

Update Single Pricing#

Update pricing for a specific AC unit size and package type.

Endpoint: PUT /api/evaluation/v1/pricing

Request Body:

{
  "package_type": "Commercial",
  "unit_size": "medium",
  "unit_price": 1600000
}

Response:

{
  "success": true,
  "message": "Pricing updated successfully",
  "updated_pricing": {
    "commercial": {
      "small": 1000000,
      "medium": 1600000,
      "large": 2000000
    },
    "corporate": {
      "small": 1200000,
      "medium": 1800000,
      "large": 2500000
    }
  }
}

Bulk Pricing Update#

Update multiple pricing configurations in a single request.

Endpoint: PUT /api/evaluation/v1/pricing/bulk

Request Body:

{
  "pricing_updates": [
    {
      "package_type": "Commercial",
      "unit_size": "small",
      "unit_price": 1100000
    },
    {
      "package_type": "Commercial",
      "unit_size": "medium",
      "unit_price": 1650000
    },
    {
      "package_type": "Corporate",
      "unit_size": "large",
      "unit_price": 2700000
    }
  ]
}

Note: Maximum of 6 updates allowed per request (2 packages × 3 sizes).

Dashboard API#

The Dashboard API provides real-time customer asset tracking and analytics.

Get Customer Asset Count#

Retrieve the asset count for a specific customer by their Zoho CRM Serial ID.

Endpoint: GET /api/dashboard/customers/{zserial_id}/assets/count

Path Parameters:

• zserial_id (string): The Zoho CRM serial ID of the customer

Response:

{
  "customer_id": "ZCRM_12345",
  "total_assets": 12
}

cURL Example:

curl -X GET "https://apis.bi.baridibaridi.co.tz/api/dashboard/customers/ZCRM_12345/assets/count"

Get All Customers Asset Counts#

Retrieve asset counts for all active subscription customers.

Endpoint: GET /api/dashboard/customers/assets/counts

Query Parameters:

• limit (integer): Maximum number of results to return (default: 100, min: 1, max: 1000)

Response:

{
  "customers": [
    {
      "customer_id": "ZCRM_12345",
      "customer_name": "Example Restaurant Ltd",
      "total_assets": 12
    },
    {
      "customer_id": "ZCRM_67890",
      "customer_name": "Hotel Paradise",
      "total_assets": 25
    }
  ]
}

cURL Example:

curl -X GET "https://apis.bi.baridibaridi.co.tz/api/dashboard/customers/assets/counts?limit=50"

Check Customer Exists#

Verify if a customer exists in the system by their Zoho CRM Serial ID.

Endpoint: GET /api/dashboard/customers/{zserial_id}/exists

Path Parameters:

• zserial_id (string): The Zoho CRM serial ID of the customer

Response:

{
  "exists": true
}

cURL Example:

curl -X GET "https://apis.bi.baridibaridi.co.tz/api/dashboard/customers/ZCRM_12345/exists"

System Health#

Health Check#

General health check endpoint for container monitoring.

Endpoint: GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-20T10:30:00Z"
}

Error Handling#

The API uses standard HTTP status codes and returns validation errors in a consistent format:

Validation Error Response (422):

{
  "detail": [
    {
      "loc": ["body", "customer_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Common HTTP Status Codes:

• 200 - Success
• 422 - Validation Error
• 404 - Resource Not Found
• 500 - Internal Server Error

Data Validation Rules#

AC Units Configuration#

• small: 0-200 units
• medium: 0-200 units
• large: 0-200 units

Business Properties#

• Property Type: Commercial or Corporate
• Package Type: Commercial or Corporate
• Business Age: Integer or string category

Pagination#

• page: Minimum 1
• per_page: Minimum 1, Maximum 100 (evaluation endpoints), Maximum 1000 (dashboard endpoints)

Pricing Updates#

• unit_price: Must be greater than 0
• Bulk updates: Maximum 6 updates per request

Best Practices#

1. Use Enhanced Evaluation Endpoint - For new integrations, use /api/evaluation/v1/evaluations instead of the legacy endpoint
2. Include Complete Route Data - Provide accurate coordinates for better evaluation accuracy
3. Pagination - Always use pagination for list endpoints to improve performance
4. Health Checks - Implement regular health checks using /health and /api/dashboard/health endpoints
5. Error Handling - Implement proper error handling for validation errors (422 status)
6. Date Filters - Use from_date and to_date parameters for time-based queries
7. Bulk Operations - Use bulk pricing updates when updating multiple configurations

Support#

For API support and questions, contact the BaridiBaridi BI team or refer to the interactive API documentation at:

OpenAPI Documentation: https://apis.bi.baridibaridi.co.tz/docs