BizFirstFi Platform API Documentation
Comprehensive API reference for KYC, AML, and Payroll platforms
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/v1Complete Know Your Customer verification system for identity validation, document verification, and compliance management.
Key Endpoints:
POST /kyc/verifications
- Start customer verificationGET /kyc/customers/{id}
- Retrieve customer dataPOST /kyc/documents
- Upload verification documentsGET /kyc/compliance-reports
- Generate compliance reports
AML Platform
/aml/v1Advanced Anti-Money Laundering monitoring system for transaction analysis, suspicious activity detection, and regulatory reporting.
Key Endpoints:
POST /aml/transactions
- Submit transaction for monitoringGET /aml/alerts
- Retrieve suspicious activity alertsPOST /aml/cases
- Create investigation casesPOST /aml/sar-filings
- Submit Suspicious Activity Reports
Payroll Platform
/payroll/v1Comprehensive payroll management system for employee administration, time tracking, tax calculations, and compliance reporting.
Key Endpoints:
POST /payroll/runs
- Create payroll runGET /payroll/employees
- Manage employee dataPOST /payroll/time-entries
- Submit time tracking dataGET /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
Java
<dependency>
<groupId>com.bizfirstfi</groupId>
<artifactId>platform-sdk</artifactId>
</dependency>
View Documentation
Support and Resources
Module Documentation
Training Materials
Developer Support
- API Support: [email protected]
- Integration Help: [email protected]
- Status Page: status.bizfirstfi.com
- Developer Portal: developers.bizfirstfi.com