API Documentation - BizFirstFi

Quick Start

The BizFirstFi API provides programmatic access to our financial compliance platform. All API endpoints use REST conventions and return JSON responses.

Base URL

https://api.bizfirstfi.com/v1

Development: http://localhost:5001/api

Authentication

API uses Bearer token authentication

Authorization: Bearer <your-api-token>

Content Type

All requests should include:

Content-Type: application/json

Open Interactive API Docs (Swagger)

Authentication Endpoints

POST /auth/login

Authenticate user and receive access token

Parameter	Type	Required	Description
email	string	Yes	User email address
password	string	Yes	User password

Request Example: POST /api/auth/login Content-Type: application/json { "email": "[email protected]", "password": "securepassword" } Response Example: { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires": "2025-08-22T00:00:00Z", "user": { "id": "123", "email": "[email protected]", "role": "ComplianceOfficer" } }

POST /auth/refresh

Refresh an existing access token

Request Example:
POST /api/auth/refresh
Authorization: Bearer <current-token>

Response Example:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2025-08-22T00:00:00Z"
}
                

KYC Endpoints

GET /kyc/applications

Retrieve list of KYC applications with optional filtering

Query Parameter	Type	Description
status	string	Filter by status (Pending, Approved, Rejected, UnderReview)
page	integer	Page number for pagination (default: 1)
limit	integer	Number of records per page (default: 20, max: 100)
customerId	string	Filter by specific customer ID

Request Example: GET /api/kyc/applications?status=Pending&page=1&limit=10 Authorization: Bearer <your-token> Response Example: { "data": [ { "id": "kyc-001", "customerId": "cust-123", "status": "Pending", "submittedAt": "2025-08-21T10:30:00Z", "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "[email protected]" }, "riskLevel": "Medium" } ], "pagination": { "total": 150, "page": 1, "limit": 10, "totalPages": 15 } }

POST /kyc/applications

Create a new KYC application

Request Example: POST /api/kyc/applications Authorization: Bearer <your-token> Content-Type: application/json { "customerId": "cust-456", "customerInfo": { "firstName": "Jane", "lastName": "Smith", "email": "[email protected]", "dateOfBirth": "1990-05-15", "nationality": "US", "address": { "street": "123 Main St", "city": "New York", "state": "NY", "zipCode": "10001", "country": "US" } } } Response Example: { "id": "kyc-002", "customerId": "cust-456", "status": "Pending", "submittedAt": "2025-08-21T11:00:00Z", "riskLevel": "Low" }

GET /kyc/applications/{id}

Retrieve specific KYC application details

Request Example: GET /api/kyc/applications/kyc-001 Authorization: Bearer <your-token> Response Example: { "id": "kyc-001", "customerId": "cust-123", "status": "UnderReview", "submittedAt": "2025-08-21T10:30:00Z", "reviewedAt": "2025-08-21T14:15:00Z", "reviewedBy": "officer-001", "customerInfo": { "firstName": "John", "lastName": "Doe", "email": "[email protected]", "dateOfBirth": "1985-03-20", "nationality": "US" }, "documents": [ { "id": "doc-001", "type": "Passport", "status": "Verified", "uploadedAt": "2025-08-21T10:35:00Z" } ], "riskAssessment": { "score": 25, "level": "Low", "factors": ["Clean background check", "Verified documents"] } }

PUT /kyc/applications/{id}/status

Update KYC application status (Compliance Officers only)

Request Example:
PUT /api/kyc/applications/kyc-001/status
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "status": "Approved",
  "reviewNotes": "All documents verified successfully",
  "reviewedBy": "officer-001"
}

Response Example:
{
  "id": "kyc-001",
  "status": "Approved",
  "reviewedAt": "2025-08-21T15:30:00Z",
  "reviewedBy": "officer-001",
  "reviewNotes": "All documents verified successfully"
}
                

Document Management Endpoints

POST /kyc/applications/{id}/documents

Upload document for KYC application

Request Example:
POST /api/kyc/applications/kyc-001/documents
Authorization: Bearer <your-token>
Content-Type: multipart/form-data

Form Data:
- file: [binary file data]
- documentType: "Passport"
- description: "Government issued passport"

Response Example:
{
  "id": "doc-002",
  "applicationId": "kyc-001",
  "type": "Passport",
  "filename": "passport_scan.pdf",
  "uploadedAt": "2025-08-21T11:45:00Z",
  "status": "PendingReview",
  "size": 2048576
}
                

GET /kyc/documents/{id}

Download specific document

Request Example:
GET /api/kyc/documents/doc-002
Authorization: Bearer <your-token>

Response:
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="passport_scan.pdf"

[Binary file data]
                

Business Management Endpoints

GET /businesses

Retrieve list of businesses

Request Example:
GET /api/businesses?page=1&limit=20
Authorization: Bearer <your-token>

Response Example:
{
  "data": [
    {
      "id": "biz-001",
      "businessName": "Acme Corp",
      "businessType": "Corporation",
      "industry": "Technology",
      "numberOfEmployees": 150,
      "createdAt": "2025-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}
                

POST /businesses

Create new business profile

Request Example: POST /api/businesses Authorization: Bearer <your-token> Content-Type: application/json { "businessName": "Tech Innovations LLC", "businessType": "LLC", "industry": "Technology", "description": "Software development company", "numberOfEmployees": 25, "address": { "streetAddress": "456 Tech Blvd", "city": "San Francisco", "state": "CA", "zipCode": "94105", "country": "US" }, "contact": { "primaryContactName": "Alice Johnson", "primaryContactEmail": "[email protected]", "primaryContactPhone": "+1-555-0123" } }

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description	Common Causes
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request format or missing required fields
401	Unauthorized	Invalid or missing authentication token
403	Forbidden	Insufficient permissions for requested operation
404	Not Found	Requested resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Required field 'email' is missing",
    "details": [
      {
        "field": "email",
        "error": "Field is required"
      }
    ]
  },
  "timestamp": "2025-08-21T12:00:00Z",
  "requestId": "req-12345"
}
                

Rate Limiting

API requests are rate limited to ensure fair usage:

Endpoint Category	Rate Limit	Time Window
Authentication	10 requests	Per minute
KYC Operations	100 requests	Per minute
Document Upload	20 requests	Per minute
Business Management	50 requests	Per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1692633600
                

SDKs and Libraries

JavaScript/Node.js

npm install @bizfirstfi/api-client

Official JavaScript SDK with TypeScript support

Python

pip install bizfirstfi-python

Python SDK with async support

C# / .NET

Install-Package BizFirstFi.ApiClient

.NET Standard 2.0 compatible library

PHP

composer require bizfirstfi/api-client

PHP SDK with modern PHP 8+ features

Testing Environment

Use our sandbox environment for testing and development:

Environment	Base URL	Purpose
Development	http://localhost:5001/api	Local development and testing
Sandbox	https://sandbox-api.bizfirstfi.com/v1	Integration testing with test data
Production	https://api.bizfirstfi.com/v1	Live production environment

Sandbox features:

Safe testing environment with synthetic data
All API endpoints available for testing
Simulated document processing and verification
Test webhooks and callbacks
Rate limiting disabled for easier testing