Platform Overview

The BizFirstFi platform provides three integrated modules for comprehensive business management: Know Your Customer (KYC) verification, Anti-Money Laundering (AML) monitoring, and Payroll management. Each module has its own specialized API while sharing common authentication and data standards.

Base URL

https://api.bizfirstfi.com/v1

Authentication

OAuth 2.0 / JWT Bearer Token

Rate Limiting

1000 requests/hour per API key

Platform Modules

KYC Platform

/kyc/v1

Complete Know Your Customer verification system for identity validation, document verification, and compliance management.

Key Endpoints:

  • POST /kyc/verifications - Start customer verification
  • GET /kyc/customers/{id} - Retrieve customer data
  • POST /kyc/documents - Upload verification documents
  • GET /kyc/compliance-reports - Generate compliance reports

AML Platform

/aml/v1

Advanced Anti-Money Laundering monitoring system for transaction analysis, suspicious activity detection, and regulatory reporting.

Key Endpoints:

  • POST /aml/transactions - Submit transaction for monitoring
  • GET /aml/alerts - Retrieve suspicious activity alerts
  • POST /aml/cases - Create investigation cases
  • POST /aml/sar-filings - Submit Suspicious Activity Reports

Payroll Platform

/payroll/v1

Comprehensive payroll management system for employee administration, time tracking, tax calculations, and compliance reporting.

Key Endpoints:

  • POST /payroll/runs - Create payroll run
  • GET /payroll/employees - Manage employee data
  • POST /payroll/time-entries - Submit time tracking data
  • GET /payroll/tax-reports - Generate tax reports

Authentication

All BizFirstFi APIs use OAuth 2.0 authentication with JWT bearer tokens. Authentication is handled centrally across all platform modules.

Authentication Flow

// 1. Obtain access token
POST https://auth.bizfirstfi.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "kyc:read kyc:write aml:read aml:write payroll:read payroll:write"
}

// Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "kyc:read kyc:write aml:read aml:write payroll:read payroll:write"
}

// 2. Use token in API requests
GET https://api.bizfirstfi.com/v1/kyc/customers
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Available Scopes

Scope Description Module
kyc:read Read access to KYC data and reports KYC
kyc:write Create and update KYC verifications KYC
aml:read Read access to AML alerts and cases AML
aml:write Create transactions and manage investigations AML
payroll:read Read access to payroll data and reports Payroll
payroll:write Process payroll and manage employee data Payroll
admin Full administrative access to all modules All

Common Integration Patterns

Customer Onboarding with KYC and AML

Complete customer verification and monitoring setup in a single workflow.

// 1. Start KYC verification
const kycVerification = await fetch('/kyc/verifications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer_id: 'CUST_001',
    verification_type: 'individual',
    required_documents: ['government_id', 'address_proof']
  })
});

// 2. Once KYC is approved, set up AML monitoring
if (kycVerification.status === 'approved') {
  await fetch('/aml/customer-profiles', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + token,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      customer_id: 'CUST_001',
      risk_category: 'medium',
      monitoring_enabled: true,
      alert_thresholds: {
        single_transaction: 10000,
        daily_aggregate: 25000
      }
    })
  });
}

Employee Payroll with AML Compliance

Process payroll while automatically monitoring for suspicious patterns.

// 1. Process payroll run
const payrollRun = await fetch('/payroll/runs', {
  method: 'POST',
  body: JSON.stringify({
    pay_period_start: '2024-03-01',
    pay_period_end: '2024-03-15'
  })
});

// 2. Automatically submit large transactions for AML monitoring
payrollRun.transactions.forEach(async (transaction) => {
  if (transaction.amount > 5000) {
    await fetch('/aml/transactions', {
      method: 'POST',
      body: JSON.stringify({
        transaction_id: transaction.id,
        amount: transaction.amount,
        transaction_type: 'payroll',
        source_account: 'company_payroll',
        destination_account: transaction.employee_account
      })
    });
  }
});

Cross-Module APIs

GET /unified/customers/{customer_id}

Retrieve comprehensive customer information across all modules

Response

{
  "customer_id": "CUST_001",
  "basic_info": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1-555-0123"
  },
  "kyc_status": {
    "verification_status": "approved",
    "risk_level": "low",
    "last_updated": "2024-03-15T10:30:00Z",
    "documents_verified": ["government_id", "address_proof"]
  },
  "aml_profile": {
    "monitoring_status": "active",
    "risk_score": 25,
    "total_alerts": 0,
    "last_transaction_date": "2024-03-14T15:45:00Z"
  },
  "payroll_info": {
    "employee_id": "EMP_001",
    "status": "active",
    "department": "Engineering",
    "last_pay_date": "2024-03-15T00:00:00Z"
  }
}

GET /unified/compliance-dashboard

Unified compliance dashboard across all modules

Response

{
  "compliance_summary": {
    "overall_status": "compliant",
    "last_updated": "2024-03-15T12:00:00Z"
  },
  "kyc_compliance": {
    "total_verifications": 1250,
    "pending_reviews": 15,
    "compliance_rate": 98.8,
    "overdue_renewals": 3
  },
  "aml_compliance": {
    "active_alerts": 8,
    "closed_cases": 145,
    "sar_filings_ytd": 12,
    "compliance_rate": 99.2
  },
  "payroll_compliance": {
    "tax_filings_current": true,
    "pending_deposits": 0,
    "audit_findings": 0,
    "compliance_rate": 100
  }
}

Webhooks and Events

Real-time notifications for important events across all platform modules.

Webhook Configuration

POST /webhooks/subscriptions
{
  "url": "https://your-app.com/webhooks/bizfirstfi",
  "events": [
    "kyc.verification.completed",
    "aml.alert.created",
    "payroll.run.approved"
  ],
  "secret": "your_webhook_secret"
}

Available Events

Event Type Description Module
kyc.verification.completed Customer verification process completed KYC
kyc.document.rejected Submitted document was rejected KYC
aml.alert.created New suspicious activity alert generated AML
aml.case.escalated Investigation case escalated to compliance AML
payroll.run.approved Payroll run approved and ready for processing Payroll
payroll.tax.filing.due Tax filing deadline approaching Payroll

Error Handling

Standardized error responses across all platform modules.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "customer_id",
        "issue": "Required field missing"
      }
    ],
    "request_id": "req_12345",
    "timestamp": "2024-03-15T10:30:00Z"
  }
}

Common Error Codes

HTTP Status Error Code Description
400 VALIDATION_ERROR Request data validation failed
401 UNAUTHORIZED Invalid or missing authentication
403 INSUFFICIENT_SCOPE Token lacks required permissions
404 RESOURCE_NOT_FOUND Requested resource does not exist
409 RESOURCE_CONFLICT Resource already exists or is in conflicting state
429 RATE_LIMIT_EXCEEDED API rate limit exceeded
500 INTERNAL_ERROR Unexpected server error

SDKs and Libraries

JavaScript/Node.js

npm install @bizfirstfi/platform-sdk
View Documentation

Python

pip install bizfirstfi-platform
View Documentation

Java

<dependency>
  <groupId>com.bizfirstfi</groupId>
  <artifactId>platform-sdk</artifactId>
</dependency>
View Documentation

C# / .NET

Install-Package BizFirstFi.Platform.SDK
View Documentation

Support and Resources