BPMCore Accounts API

The Accounts API provides comprehensive management of journal entries and accounting transactions in the BankLingo platform. This API enables manual journal postings, retrieving accounting records, and reversing transactions.

Base Endpoint

All commands are executed through:

POST /api/core/cmd

Commands & Queries

1. Retrieve Journal Entries

Retrieves a paginated and filterable list of journal entries with detailed account information.

Command Name: RetrieveJournalEntriesQuery

Request Parameters

Parameter	Type	Required	Description
currencyCode	string	No	Filter by currency code (e.g., "NGN", "USD")
startDate	datetime	No	Start date for filtering (inclusive)
endDate	datetime	No	End date for filtering (inclusive)
searchText	string	No	Search by GL Code or Transaction Reference
glCode	string	No	Filter by specific General Ledger code
branchId	long	No	Filter by branch ID (omit for all branches)
pageNumber	integer	No	Page number for pagination (default: 1)
pageSize	integer	No	Number of items per page (default: 20)
isExport	boolean	No	Export all results without pagination (default: false)

Request Example

{
  "Cmd": "RetrieveJournalEntriesQuery",
  "Data": {
    "currencyCode": "NGN",
    "startDate": "2024-01-01",
    "endDate": "2024-12-31",
    "searchText": "SAL",
    "pageNumber": 1,
    "pageSize": 50
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Journal entries retrieved successfully.",
  "Data": {
    "items": [
      {
        "Id": 12345,
        "GLCode": "1001",
        "AccountName": "Cash at Bank",
        "AccountTypeId": 1,
        "AccountTypeDescription": "Asset",
        "JournalEntryType": 1,
        "JournalEntryTypeDescription": "Debit",
        "DebitAmount": "50000.00",
        "CreditAmount": "",
        "CurrencyCode": "NGN",
        "BranchName": "Head Office",
        "TransactionReference": "SAL/2024/001",
        "AccountDescription": "Salary Payment January 2024",
        "BookingDate": "2024-01-15 10:30:00",
        "JournalTransactionId": 789,
        "TransactionEncodedKey": "8a8e8e8e8e8e8e8e",
        "Notes": "Monthly salary disbursement"
      }
    ],
    "totalRows": 150,
    "totalPages": 3,
    "pageSize": 50,
    "currentPage": 1
  },
  "HasNext": true,
  "HasPrevious": false
}

Response Fields

Field	Type	Description
Id	long	Unique journal entry ID
GLCode	string	General ledger account code
AccountName	string	Name of the GL account
AccountTypeId	integer	Account type enum value (1=Asset, 2=Liability, 3=Equity, 4=Income, 5=Expense)
AccountTypeDescription	string	Human-readable account type
JournalEntryType	integer	Entry type (1=Debit, 2=Credit)
JournalEntryTypeDescription	string	"Debit" or "Credit"
DebitAmount	string	Formatted debit amount (empty if credit)
CreditAmount	string	Formatted credit amount (empty if debit)
CurrencyCode	string	Three-letter currency code
BranchName	string	Name of the branch
TransactionReference	string	Unique transaction reference
AccountDescription	string	Description/narration of the entry
BookingDate	string	Formatted booking date
JournalTransactionId	long	Parent transaction ID (groups related entries)
TransactionEncodedKey	string	Encoded key for the entry
Notes	string	Additional notes

---

2. Retrieve Journal Transactions

Retrieves a list of journal transactions (grouped journal entries). Each transaction contains multiple debit and credit entries.

Command Name: RetrieveJournalTransactionsQuery

Request Parameters

Parameter	Type	Required	Description
startDate	datetime	No	Start date for filtering
endDate	datetime	No	End date for filtering
searchText	string	No	Search by transaction ID or username
pageNumber	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20)
isExport	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "RetrieveJournalTransactionsQuery",
  "Data": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "searchText": "admin",
    "pageNumber": 1,
    "pageSize": 20
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Journal transactions retrieved successfully.",
  "Data": {
    "items": [
      {
        "Id": 789,
        "TransactionId": "JT/2024/000789",
        "TransactionDate": "2024-01-15 10:30:00",
        "BookingDate": "2024-01-15T10:30:00",
        "TransactionType": 1,
        "TransactionTypeDesc": "Manual Journal Entry",
        "Amount": 50000.00,
        "Entries": 4,
        "UserName": "admin@banklingo.com",
        "UserEncodedKey": "8a8e8e8e8e8e8e8e",
        "IsManualPosting": true,
        "IsReversed": false,
        "IsAReversedTransaction": false,
        "Remarks": "Monthly salary entries"
      }
    ],
    "totalRows": 25,
    "totalPages": 2,
    "pageSize": 20,
    "currentPage": 1
  },
  "HasNext": true,
  "HasPrevious": false
}

Response Fields

Field	Type	Description
Id	long	Unique transaction ID
TransactionId	string	Human-readable transaction reference
TransactionDate	string	Formatted transaction date
BookingDate	datetime	Raw booking date
TransactionType	integer	Transaction type enum
TransactionTypeDesc	string	Description of transaction type
Amount	decimal	Total debit amount
Entries	integer	Number of journal entries in this transaction
UserName	string	User who created the transaction
UserEncodedKey	string	Encoded key of the user
IsManualPosting	boolean	True if manually posted
IsReversed	boolean	True if this transaction has been reversed
IsAReversedTransaction	boolean	True if this is a reversal of another transaction
Remarks	string	Transaction remarks

---

3. Retrieve Journal Transaction By ID

Retrieves a single journal transaction with all its entries and detailed account information.

Command Name: RetrieveJournalTransactionByIdQuery

Request Parameters

Parameter	Type	Required	Description
journalTransactionId	long	Yes	Unique transaction ID

Request Example

{
  "Cmd": "RetrieveJournalTransactionByIdQuery",
  "Data": {
    "journalTransactionId": 789
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Journal transaction retrieved successfully.",
  "Data": {
    "Id": 789,
    "TransactionId": "JT/2024/000789",
    "TransactionDate": "2024-01-15 10:30:00",
    "TransactionType": 1,
    "TransactionTypeDesc": "Manual Journal Entry",
    "UserName": "admin@banklingo.com",
    "IsManualPosting": true,
    "IsReversed": false,
    "Remarks": "Monthly salary entries",
    "Entries": [
      {
        "Id": 12345,
        "GLCode": "1001",
        "GLAccountId": 50,
        "AccountDescription": "Cash at Bank",
        "AccountTypeId": 1,
        "AccountTypeDescription": "Asset",
        "JournalEntryType": 1,
        "JournalEntryTypeDescription": "Debit",
        "Amount": 50000.00,
        "DebitAmount": 50000.00,
        "CreditAmount": 0,
        "BookingDate": "2024-01-15 10:30:00",
        "BookingDateRaw": "2024-01-15T10:30:00",
        "CurrencyCode": "NGN",
        "BranchId": 1,
        "BranchName": "Head Office",
        "TransactionReference": "SAL/2024/001",
        "Notes": "Salary payment"
      },
      {
        "Id": 12346,
        "GLCode": "5001",
        "GLAccountId": 120,
        "AccountDescription": "Salary Expense",
        "AccountTypeId": 5,
        "AccountTypeDescription": "Expense",
        "JournalEntryType": 2,
        "JournalEntryTypeDescription": "Credit",
        "Amount": 50000.00,
        "DebitAmount": 0,
        "CreditAmount": 50000.00,
        "BookingDate": "2024-01-15 10:30:00",
        "BookingDateRaw": "2024-01-15T10:30:00",
        "CurrencyCode": "NGN",
        "BranchId": 1,
        "BranchName": "Head Office",
        "TransactionReference": "SAL/2024/001",
        "Notes": "Salary expense recognition"
      }
    ],
    "TotalDebits": 50000.00,
    "TotalCredits": 50000.00,
    "IsBalanced": true
  }
}

---

4. Post Journal Entry

Posts a manual journal entry with multiple debit and credit entries. The system validates that debits equal credits before posting.

Command Name: PostJournalEntryCommand

Request Parameters

Parameter	Type	Required	Description
transactionReference	string	No	Custom reference (auto-generated if omitted)
entries	array	Yes	Array of journal entry items (see below)
notes	string	No	Additional notes for the transaction
bookingDate	datetime	Yes	Booking date for the entries
currencyCode	string	Yes	Currency code (e.g., "NGN")

Entry Object Structure

Parameter	Type	Required	Description
glAccountId	long	Yes	General ledger account ID
amount	decimal	Yes	Amount for this entry
journalEntryType	integer	Yes	1 = Debit, 2 = Credit
branchId	long	No	Branch ID (defaults to user's branch)
reference	string	No	Entry-specific reference

Request Example

{
  "Cmd": "PostJournalEntryCommand",
  "Data": {
    "transactionReference": "ACCRUAL/2024/001",
    "bookingDate": "2024-01-31",
    "currencyCode": "NGN",
    "notes": "Month-end interest accrual",
    "entries": [
      {
        "glAccountId": 150,
        "amount": 25000.00,
        "journalEntryType": 1,
        "branchId": 1,
        "reference": "Interest receivable"
      },
      {
        "glAccountId": 420,
        "amount": 25000.00,
        "journalEntryType": 2,
        "reference": "Interest income"
      }
    ]
  }
}

Validation Rules

1. Balanced Entry: Total debits must equal total credits
2. Valid GL Accounts: All glAccountId values must exist and be active
3. Currency Consistency: All entries must use the same currency
4. Authorization: User must have permission to post journal entries
5. Date Validation: Booking date cannot be in a closed accounting period

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Journal entry posted successfully.",
  "Data": {
    "TransactionId": "JT/2024/000790",
    "JournalTransactionId": 790,
    "BookingDate": "2024-01-31T00:00:00",
    "TotalDebits": 25000.00,
    "TotalCredits": 25000.00,
    "EntriesPosted": 2
  }
}

Error Responses

Unbalanced Entry

{
  "IsSuccessful": false,
  "StatusCode": "01",
  "Message": "Total debits (30000.00) must equal total credits (25000.00)",
  "Data": null
}

Invalid GL Account

{
  "IsSuccessful": false,
  "StatusCode": "02",
  "Message": "GL Account with ID 999 not found or inactive",
  "Data": null
}

---

5. Reverse Journal Transaction

Reverses an existing journal transaction by creating offsetting entries.

Command Name: ReverseJournalTransactionCommand

Request Parameters

Parameter	Type	Required	Description
transactionId	long	Yes	ID of the transaction to reverse
reason	string	No	Reason for reversal
isBackDated	boolean	No	Whether to backdate the reversal
backDateValueDate	datetime	No	Value date for backdated reversal
isBookingDate	boolean	No	Use specific booking date
bookingDate	datetime	No	Custom booking date

Request Example

{
  "Cmd": "ReverseJournalTransactionCommand",
  "Data": {
    "transactionId": 789,
    "reason": "Incorrect salary amount posted",
    "isBackDated": false
  }
}

Business Rules

1. Reversal Validation: Cannot reverse an already-reversed transaction
2. Permission Check: User must have reversal authorization
3. Period Check: Reversal must be in an open accounting period
4. Audit Trail: System tracks reversal reason and user
5. Reference Linking: Reversal transaction is linked to original

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Journal transaction reversed successfully.",
  "Data": {
    "ReversalTransactionId": "JT/2024/000791",
    "ReversalJournalTransactionId": 791,
    "OriginalTransactionId": "JT/2024/000789",
    "ReversalDate": "2024-01-16T14:20:00",
    "Reason": "Incorrect salary amount posted",
    "EntriesReversed": 4
  }
}

Error Responses

Already Reversed

{
  "IsSuccessful": false,
  "StatusCode": "03",
  "Message": "Transaction JT/2024/000789 has already been reversed",
  "Data": null
}

Transaction Not Found

{
  "IsSuccessful": false,
  "StatusCode": "02",
  "Message": "Journal transaction with ID 999 not found",
  "Data": null
}

---

Common Use Cases

Example 1: Manual Expense Accrual

Post month-end accruals for expenses not yet invoiced:

{
  "Cmd": "PostJournalEntryCommand",
  "Data": {
    "transactionReference": "ACCR-UTIL-202401",
    "bookingDate": "2024-01-31",
    "currencyCode": "NGN",
    "notes": "Utilities expense accrual for January",
    "entries": [
      {
        "glAccountId": 510,
        "amount": 150000.00,
        "journalEntryType": 1,
        "reference": "Utilities expense"
      },
      {
        "glAccountId": 220,
        "amount": 150000.00,
        "journalEntryType": 2,
        "reference": "Accrued liabilities"
      }
    ]
  }
}

Example 2: Error Correction

Query and reverse an incorrectly posted entry:

// Step 1: Find the transaction
{
  "Cmd": "RetrieveJournalEntriesQuery",
  "Data": {
    "searchText": "SAL/2024/001",
    "pageSize": 10
  }
}

// Step 2: Reverse it
{
  "Cmd": "ReverseJournalTransactionCommand",
  "Data": {
    "transactionId": 789,
    "reason": "Wrong GL account used - should be 5002 not 5001"
  }
}

// Step 3: Post correct entry
{
  "Cmd": "PostJournalEntryCommand",
  "Data": {
    // ... correct entry details
  }
}

Example 3: Monthly Reporting

Retrieve all journal entries for month-end reporting:

{
  "Cmd": "RetrieveJournalEntriesQuery",
  "Data": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "isExport": true,
    "currencyCode": "NGN"
  }
}

---

Integration Notes

Journal Entry Types

Value	Description	Normal Balance
1	Debit	Asset, Expense accounts increase
2	Credit	Liability, Equity, Income accounts increase

Account Types

ID	Type	Examples
1	Asset	Cash, Receivables, Fixed Assets
2	Liability	Payables, Loans, Accruals
3	Equity	Capital, Retained Earnings
4	Income	Interest Income, Fees
5	Expense	Salaries, Rent, Utilities

Transaction Types

ID	Description	Usage
1	Manual Journal Entry	User-posted adjustments
2	Automated Entry	System-generated postings
3	Reversal	Reversal of previous entry

---

Best Practices

1. Always Balance Entries: Ensure debits = credits before posting
2. Use Meaningful References: Include dates, departments, or invoice numbers
3. Add Detailed Notes: Explain the business reason for manual entries
4. Review Before Posting: Double-check GL codes and amounts
5. Document Reversals: Always provide clear reversal reasons
6. Use Filters Wisely: Narrow date ranges and use specific GL codes for faster queries
7. Export for Audit: Use isExport: true for comprehensive audit trails

---

Related APIs:

• General Ledger Management
• Account Setup
• Financial Reports

---

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer