Developer Platform
API Reference

API Reference

Complete reference documentation for all BigLedger REST APIs. Since all BigLedger applets are built with Angular, every feature in the BigLedger interface has a corresponding API endpoint, ensuring 100% programmatic access to all functionality.

We will continuously improve this documentation, suggestions are welcome.

ℹ️
Interactive Documentation: This reference includes live examples, sample requests/responses, and interactive testing capabilities. Use our API Explorer to test endpoints directly.

Base URLs

Production Environment 

https://api.bigledger.com/v1

Sandbox Environment 

https://sandbox-api.bigledger.com/v1
Start with Sandbox: Always begin development and testing in the sandbox environment. It mirrors production exactly but uses test data.

Authentication

All API requests require authentication via API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Common Headers

Include these headers in all requests:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
X-Company-Id: your-company-id

Core API Modules

Accounting APIs

Complete accounting operations including chart of accounts, journal entries, and financial reporting.

E-Invoice APIs

PEPPOL and MyInvois compliance with automated validation and submission.

Inventory APIs

Complete inventory management including stock levels, transfers, and adjustments.

Sales & CRM APIs

Customer management, sales orders, quotes, and invoicing.

POS APIs

Point-of-sale operations, session management, and retail transactions.

API Design Patterns

RESTful URLs

BigLedger APIs follow RESTful conventions:

GET    /api/v1/customers           # List customers
POST   /api/v1/customers           # Create customer
GET    /api/v1/customers/{id}      # Get specific customer
PUT    /api/v1/customers/{id}      # Update customer
DELETE /api/v1/customers/{id}      # Delete customer

Standard Response Format

All API responses follow this structure:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_123456789"
  }
}

Error Response Format

Error responses include detailed information:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid customer data",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_123456789"
  }
}

Pagination

For list endpoints, use cursor-based pagination:

GET /api/v1/customers?limit=20&cursor=eyJpZCI6MTIzfQ

Response includes pagination metadata:

{
  "success": true,
  "data": [
    // Customer records
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTQzfQ",
    "limit": 20,
    "total": 156
  }
}

Filtering and Sorting

Use query parameters for advanced filtering and sorting:

# Basic filtering
GET /api/v1/invoices?status=draft&customerName=acme

# Date range filtering
GET /api/v1/invoices?fromDate=2024-01-01&toDate=2024-01-31

# Sorting (ascending/descending)
GET /api/v1/invoices?sort=createdAt:desc

# Multiple sort fields
GET /api/v1/invoices?sort=dueDate:asc,total:desc

# Search across multiple fields
GET /api/v1/customers?search=acme&searchFields=name,email,phone

# Complex filtering with operators
GET /api/v1/invoices?total[gte]=1000&total[lte]=5000&status[ne]=cancelled

Supported Filter Operators

OperatorDescriptionExample
eqEqual (default)status=active
neNot equalstatus[ne]=cancelled
gtGreater thantotal[gt]=100
gteGreater than or equaltotal[gte]=100
ltLess thantotal[lt]=1000
lteLess than or equaltotal[lte]=1000
inIn arraystatus[in]=draft,pending
ninNot in arraystatus[nin]=cancelled,void
containsContains textname[contains]=acme
startswithStarts withname[startswith]=A
endswithEnds withemail[endswith]=.com

Rate Limiting

API requests are rate limited by API key:

  • Default Limit: 1000 requests per hour
  • Burst Limit: 10 requests per second
  • Headers: Rate limit information is included in response headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Bulk Operations

For high-volume operations, use bulk endpoints to process multiple records efficiently:

Bulk Create 

POST /api/v1/bulk/customers
Content-Type: application/json

{
  "operations": [
    {
      "operation": "create",
      "data": {
        "name": "Customer 1",
        "email": "customer1@example.com"
      }
    },
    {
      "operation": "create",
      "data": {
        "name": "Customer 2",
        "email": "customer2@example.com"
      }
    }
  ]
}

Bulk Update 

POST /api/v1/bulk/customers
{
  "operations": [
    {
      "operation": "update",
      "id": "cust_123",
      "data": {
        "creditLimit": 15000
      }
    },
    {
      "operation": "update",
      "id": "cust_456",
      "data": {
        "status": "inactive"
      }
    }
  ]
}

Bulk Response Format 

{
  "success": true,
  "data": {
    "processed": 2,
    "successful": 1,
    "failed": 1,
    "results": [
      {
        "index": 0,
        "success": true,
        "data": {
          "id": "cust_789",
          "name": "Customer 1"
        }
      },
      {
        "index": 1,
        "success": false,
        "error": {
          "code": "VALIDATION_ERROR",
          "message": "Email already exists"
        }
      }
    ]
  }
}

Bulk Endpoints Available

  • POST /api/v1/bulk/customers - Bulk customer operations (max 100 records)
  • POST /api/v1/bulk/invoices - Bulk invoice operations (max 50 records)
  • POST /api/v1/bulk/inventory-adjustments - Bulk inventory updates (max 200 records)
  • POST /api/v1/bulk/journal-entries - Bulk accounting entries (max 100 records)
  • POST /api/v1/bulk/payments - Bulk payment processing (max 100 records)

Webhooks

Subscribe to real-time events:

POST /api/v1/webhooks/subscribe
{
  "url": "https://your-app.com/webhooks",
  "events": ["invoice.created", "payment.received", "stock.updated"]
}

WebSocket API

For real-time data updates and live synchronization:

Connection 

const ws = new WebSocket('wss://api.bigledger.com/v1/stream');

// Authenticate and subscribe
ws.onopen = function() {
  ws.send(JSON.stringify({
    "type": "auth",
    "token": "YOUR_API_KEY",
    "companyId": "YOUR_COMPANY_ID"
  }));
};

// Subscribe to events
ws.send(JSON.stringify({
  "type": "subscribe",
  "channels": ["invoice.updates", "stock.changes", "payment.received"],
  "filters": {
    "invoice.updates": {
      "status": ["draft", "sent"]
    }
  }
}));

Available Channels

  • invoice.created - New invoice created
  • invoice.updated - Invoice modified
  • invoice.sent - Invoice sent to customer
  • payment.received - Payment recorded
  • stock.updated - Inventory levels changed
  • customer.created - New customer added
  • order.status_changed - Sales order status updated
  • einvoice.submitted - E-invoice submitted to government
  • report.generated - Financial report completed

Message Format 

{
  "type": "event",
  "channel": "invoice.created",
  "data": {
    "id": "inv_123",
    "invoiceNumber": "INV-2024-0001",
    "customerId": "cust_456",
    "total": 1060.00,
    "status": "draft",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "companyId": "company_abc123",
    "timestamp": "2024-01-15T10:30:00Z",
    "eventId": "evt_789xyz"
  }
}

Common HTTP Status Codes

CodeMeaningDescription
200OKRequest successful
201CreatedResource created successfully
400Bad RequestInvalid request data
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource not found
422Unprocessable EntityValidation errors
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error

Testing Your Integration

Sandbox Environment

Use the sandbox environment for testing:

https://api-sandbox.bigledger.com/v1

Interactive API Explorer

Try our interactive API explorer with live testing capabilities:

Open API Explorer

Features:

  • Live Testing: Make real API calls from your browser
  • Authentication: Built-in API key management
  • Code Generation: Generate code samples in multiple languages
  • Response Inspector: Detailed response analysis
  • History: Track your API testing history

Postman Collection

Import our comprehensive Postman collection:

Download BigLedger API Collection

Included:

  • All API endpoints with sample requests
  • Environment variables for sandbox/production
  • Pre-request authentication scripts
  • Test scripts for response validation
  • Example workflows for common integrations

OpenAPI Specification

Download our OpenAPI (Swagger) specification:

API Modules

Authentication
OAuth 2.0 flows, API key management, and security best practices.
Accounting APIs
Chart of accounts, journal entries, and financial reporting endpoints.
E-Invoice APIs
PEPPOL and MyInvois compliance with automated validation.
Inventory APIs
Stock management, transfers, adjustments, and real-time tracking.
Sales & CRM APIs
Customers, sales orders, quotes, invoices, and CRM operations.
Purchasing APIs
Purchase orders, suppliers, bills, and procurement workflows.
POS APIs
Point-of-sale transactions, sessions, and retail operations.
Reporting APIs
Financial reports, analytics, and business intelligence data.
Webhooks API
Real-time event notifications and webhook management.
Batch Operations
Bulk operations for high-volume data processing.
Integration APIs
Third-party integrations and data synchronization.
Error Handling
Comprehensive error codes and troubleshooting guide.

Quick Reference

Common Endpoints 

# Authentication & Company Info
GET    /v1/auth/verify
GET    /v1/company

# Core Business Entities
GET    /v1/customers              # List customers
POST   /v1/customers              # Create customer
GET    /v1/customers/{id}         # Get customer
PUT    /v1/customers/{id}         # Update customer
DELETE /v1/customers/{id}         # Delete customer

# Invoicing
GET    /v1/invoices               # List invoices
POST   /v1/invoices               # Create invoice
GET    /v1/invoices/{id}          # Get invoice
PUT    /v1/invoices/{id}          # Update invoice
POST   /v1/invoices/{id}/send     # Send invoice
POST   /v1/invoices/{id}/payment  # Record payment

# Inventory
GET    /v1/items                  # List inventory items
GET    /v1/stock                  # Current stock levels
POST   /v1/stock-adjustments      # Adjust stock
POST   /v1/stock-transfers        # Transfer stock

# Accounting
GET    /v1/accounts               # Chart of accounts
POST   /v1/journal-entries        # Create journal entry
GET    /v1/reports/balance-sheet  # Balance sheet
GET    /v1/reports/profit-loss    # P&L statement

Response Time SLA

Operation TypeTarget Response TimeSLA
Read operations (GET)< 200ms99.9%
Write operations (POST/PUT)< 500ms99.5%
Bulk operations< 5 seconds99.0%
Report generation< 10 seconds95.0%
File uploads< 30 seconds95.0%

Global Request/Response Headers

Request Headers:

Authorization: Bearer {api_key}     # Required
Content-Type: application/json      # Required for POST/PUT
X-Company-Id: {company_id}          # Required
X-Request-ID: {unique_id}           # Optional, for tracking
X-API-Version: 2024-01-15           # Optional, date-based versioning
Accept-Encoding: gzip, deflate      # Optional, for compression
User-Agent: YourApp/1.0.0           # Recommended

Response Headers:

Content-Type: application/json
X-Request-ID: req_123456789
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000
X-Response-Time: 150ms
Cache-Control: no-cache