Ledgersync

## Sections
• [LedgerSync Rest API](https://app.theneo.io/ledgersync/ledgersync-api/ledgersync-rest-api.md): The Ledgersync Rest API provides developers with access to essential financial data retrieval and synchronization functionalities. Users can integrate this API to seamlessly fetch and update information related to transactions, accounts, and other financial data sources. This API serves as a vital resource for automating and streamlining financial data management processes within applications.
• [Getting Started](https://app.theneo.io/ledgersync/ledgersync-api/getting-started.md): Welcome to the Ledgersync documentation! This guide will quickly walk you through the essential steps needed to start using our API, including how to register for a customer account and authenticate your API requests. Additionally, we'll introduce you to our Sandbox environment, perfect for testing your integrations. Quick Start Before integrating with our API in a live environment, we recommend experimenting with our Sandbox to safely test your implementations. Follow these steps to get started: Register a Customer Account in the Live Environment Visit https://ledgersyncappv2.com/sign-up to create your customer account for the live environment. You will need to provide your email and password during registration. Register for the Sandbox Environment For testing purposes, access our Sandbox environment at https://104.196.54.242.sslip.io/staging/sign-up . Register here to create a separate account for development and testing. API Authentication Use the email and password from your registration (for both live and Sandbox environments) to authenticate your API requests. Remember, credentials for the live and Sandbox environments are separate and not interchangeable.
• [Authentication](https://app.theneo.io/ledgersync/ledgersync-api/authentication.md): Securing access to the LedgerSync is essential for protecting your data and ensuring that only authorized users can perform operations. Our API employs a token-based authentication system to facilitate this security measure. Obtaining Your Authentication Token Authenticate Endpoint : Begin by obtaining an authentication token. This is done by making a request to our authenticate endpoint using your registered email and password. Upon successful authentication, the system will provide you with an authentication token. Extract Token : The response from the authenticate endpoint will include your authentication token. This token is vital for accessing other API endpoints and must be included in the headers of all subsequent API requests. Using Your Authentication Token Header Inclusion : For every API request after authentication, you need to include the provided authentication token in the request header. This serves as your access key to the API, validating your requests across all endpoints. Token Management : It's important to manage your token responsibly. The token has an expiration timeframe, and once it expires, you will need to re-authenticate to obtain a new one. Keep your token secure and avoid sharing it publicly to prevent unauthorized access to your account.
  • [Authenticate](https://app.theneo.io/ledgersync/ledgersync-api/authentication/authenticate.md): This section enables users to authenticate themselves securely on the Ledgersync platform, granting access to their account and associated data. By providing the necessary credentials, users can verify their identity and gain entry to the system, ensuring a seamless and protected user experience.
• [Accounts](https://app.theneo.io/ledgersync/ledgersync-api/accounts.md): The Account API section allows users to retrieve detailed information about accounts within the Ledgersync system. Users can access account details, such as account numbers, types, and statuses, to easily manage and track financial information. This section provides essential data for seamless integration and efficient account management within the Ledgersync platform.
  • [Add Bank Account Widget Integration](https://app.theneo.io/ledgersync/ledgersync-api/accounts/add-bank-account-widget-integration.md): This section is dedicated to guiding developers through the integration of the "Add Bank Account" widget provided by the Ledgersync API. Integrating this widget into your application empowers users to seamlessly add their bank accounts, enhancing user experience and streamlining the account management process. Overview The "Add Bank Account" widget offers a user-friendly interface for users to link their bank accounts directly within your application, promoting a smooth and efficient onboarding experience. This integration is designed to complement your application's functionality, offering a direct, secure, and intuitive way for users to manage their financial accounts. Key Benefits Improved User Experience : By incorporating the widget, users are presented with a straightforward and guided process for adding bank accounts, keeping them engaged and satisfied. Simplified Account Management : The widget reduces complexities in the account addition process, minimizing user effort and potential for errors. Secure and Trustworthy : With a focus on security, the widget ensures that user financial data is handled with the utmost care, maintaining privacy and trust. Integration Process By retrieving the URL for the "Add Bank Account" widget through the Ledgersync API, developers can effortlessly embed this functionality into their applications. The widget is designed to integrate seamlessly into your app's existing flow, ensuring a consistent and engaging user experience. The integration of the "Add Bank Account" widget signifies a step forward in providing users with a comprehensive, secure, and efficient tool for financial account management within your platform. See below example of returning JSON: { "status": "OK", "widgetUrl": "https://connect.finicity.com?analytics=google%3AUA-123456789-1&customerId=53829905&partnerId=2445582741601&redirectUri=https%3A%2F%2Fce5d9f86.ngrok.io%2Fapi%2Fpublic%2Fredirect-handler&signature=4837879cbdab90530c5191bec7209719cbb25657d38b6d6e862f809d44aaf661&timestamp=1589996840006&ttl=1590004040006&type=aggregation&webhook=https%3A%2F%2Fce5d9f86.ngrok.io%2Fapi%2Fpublic%2Fwebhook-handler&webhookContentType=application%2Fjson"}
  • [Add Lite Bank Account Widget Integration](https://app.theneo.io/ledgersync/ledgersync-api/accounts/add-lite-bank-account-widget-integration.md): Add Lite provides the capability to design custom screens that enable users to choose their financial institution (FI) and account. To utilize Add Lite, you must provide an institutionId. You can obtain this by conducting a search through the institutions endpoint using a search term provided by your customer. After a customer selects an institution from the generated list, you will acquire the necessary institutionId for the Connect Lite endpoint. See below example of returning JSON: { "status": "OK", "widgetUrl": "https://connect.finicity.com?analytics=google%3AUA-123456789-1&customerId=53829905&partnerId=2445582741601&redirectUri=https%3A%2F%2Fce5d9f86.ngrok.io%2Fapi%2Fpublic%2Fredirect-handler&signature=4837879cbdab90530c5191bec7209719cbb25657d38b6d6e862f809d44aaf661×tamp=1589996840006&ttl=1590004040006&type=aggregation&webhook=https%3A%2F%2Fce5d9f86.ngrok.io%2Fapi%2Fpublic%2Fwebhook-handler&webhookContentType=application%2Fjson"}
  • [Fix Bank Account Connection Integration](https://app.theneo.io/ledgersync/ledgersync-api/accounts/fix-bank-account-connection-integration.md): This section elaborates on integrating the "Fix Account Connection" feature via the Ledgersync API. This crucial functionality provides users with a straightforward method to address and resolve issues related to their bank account connections directly within your application. Overview The "Fix Account Connection" feature is designed to enhance user confidence and application reliability by offering a direct pathway to rectify connection issues with financial institutions. By accessing this feature, users are guided through a seamless process to update credentials, resolve multi-factor authentication (MFA) challenges, or re-establish lost connections, ensuring uninterrupted access to their financial data. Key Scenarios Lost Financial Institution Connection : Automatically prompts users to re-establish connection without navigating away from your application, maintaining a smooth user experience. Credential Updates : Facilitates the update of user credentials directly within the widget, ensuring continued access to their account information. Expired MFA Challenges : Allows users to promptly address and update expired MFA challenges, securing their account access and data integrity. Integration Benefits Enhanced User Trust : By enabling users to quickly fix connection issues, your application builds greater trust and reliability. Seamless User Experience : The widget integrates directly into your app's flow, allowing users to resolve issues without disrupting their experience. Secure and Efficient : Ensures that sensitive user information is handled securely while providing an efficient pathway to fix connectivity issues. Implementation Integrating the "Fix Account Connection" widget through the Ledgersync API allows developers to embed this essential feature seamlessly into their applications. Designed to address specific connection issues, the widget guides users to the relevant account screen with an error prompt for a targeted fix, streamlining the resolution process. This integration not only simplifies the management of financial account connections but also reinforces the security and efficiency of user interactions with your platform.
  • [List Bank Accounts](https://app.theneo.io/ledgersync/ledgersync-api/accounts/list-bank-accounts.md): This section allows users to retrieve a list of all accounts associated with a specific username. By accessing this endpoint, users can efficiently manage and view all accounts linked to a particular user profile.
  • [List Sub-Accounts](https://app.theneo.io/ledgersync/ledgersync-api/accounts/list-sub-accounts.md): This section allows users to retrieve a list of all sub-accounts associated with a specific bank account for a given username. By accessing this endpoint, users can conveniently view and manage all related sub-accounts within the Ledgersync system.
  • [Get Account Summary](https://app.theneo.io/ledgersync/ledgersync-api/accounts/get-account-summary.md): This section allows users to retrieve a concise summary of a specific bank account. Users can access key information such as account status and relevant messages pertaining to the account summary retrieval process. This functionality provides a quick overview of the account's status and relevant details for easy reference.
  • [Refresh Accounts](https://app.theneo.io/ledgersync/ledgersync-api/accounts/refresh-accounts.md): This section allows users to refresh all accounts data associated with a specific bank account ID. By using this functionality, users can ensure that the most up-to-date information from the bank account is retrieved and synchronized with the system. This helps maintain accurate and current financial data for the specified bank account.
  • [Update Account](https://app.theneo.io/ledgersync/ledgersync-api/accounts/update-account.md): The "Update Account" section allows users to modify the details of a specific account associated with a bank account. By providing the necessary information such as the unique bank account identifier and the new account name, users can easily update the account information. The response will indicate the status and provide a message confirming the success of the account update process.
  • [Delete Bank Account](https://app.theneo.io/ledgersync/ledgersync-api/accounts/delete-bank-account.md): The Delete Bank Account section allows users to remove a specific bank account and its sub-accounts from the Ledgersync system. By utilizing this functionality, users can effectively manage their list of connected financial institutions and streamline their account information. This feature ensures accurate data maintenance and organization within the Ledgersync platform.
• [Clients](https://app.theneo.io/ledgersync/ledgersync-api/clients.md): The Clients section in Ledgersync allows users to retrieve detailed information about clients, such as their contact details, account status, and transaction history. By accessing this section, users can efficiently manage client data and gain insights into their financial relationships.
  • [Add Client](https://app.theneo.io/ledgersync/ledgersync-api/clients/add-client.md): This section allows users to add a new client in the Ledgersync system. By providing the necessary client information, users can seamlessly integrate new clients into their accounts. This action streamlines the process of managing and organizing client data within the platform.
  • [List Clients](https://app.theneo.io/ledgersync/ledgersync-api/clients/list-clients.md): This section allows users to retrieve a list of all clients. By accessing this endpoint, users can view details such as client names, emails, phone numbers, and account information. This functionality simplifies the process of managing and monitoring clients within the Ledgersync system.
  • [Update Client](https://app.theneo.io/ledgersync/ledgersync-api/clients/update-client.md): This section allows users to modify and manage client information within the Ledgersync system. With this functionality, users can update client usernames, contact information, preferences, and account status seamlessly. This section empowers users to keep client details accurate and up-to-date, ensuring smooth communication and service delivery.
  • [Delete Client](https://app.theneo.io/ledgersync/ledgersync-api/clients/delete-client.md): The "Delete Client" section allows users to remove a client from their Ledgersync account. By utilizing this functionality, users can efficiently manage their client data by deleting unnecessary or outdated information. This API section empowers users to maintain a clean and organized client list within their account.
• [List institutions](https://app.theneo.io/ledgersync/ledgersync-api/institutions/list-institutions.md): The "List institutions" section of the Ledgersync Rest API allows users to retrieve a list of financial institutions available for integration. With this functionality, users can easily access information such as institution names, account types, contact details, and more to streamline the integration process with their own applications. This section provides a convenient way for users to explore and select the institutions they wish to connect with through the API.
• [Transactions](https://app.theneo.io/ledgersync/ledgersync-api/transactions.md): The Transaction API section in Ledgersync allows users to retrieve detailed information about financial transactions within their account. With this API, users can access essential data related to each transaction, enabling them to track and manage their financial activity effectively.
  • [List Transactions](https://app.theneo.io/ledgersync/ledgersync-api/transactions/list-transactions.md): This section allows users to retrieve a list of account transactions associated with a specific client. By querying this endpoint, users can view detailed information such as transaction amount, account number, bank details, and transaction dates for a given client's account. This enables users to track and analyze financial activities efficiently.
  • [Transaction Status](https://app.theneo.io/ledgersync/ledgersync-api/transactions/transaction-status.md): The transaction status indicates the availability of the transaction from the financial institution. The status may be active, pending, or shadow. An individual transaction’s status may fluctuate between these statuses, depending on the current reporting by the financial institution. Active Transactions An active transaction is a transaction that is currently found on an institution’s transaction record during the most recent refresh. Pending Transactions A pending transaction is a transaction that has been initiated but has not been cleared or posted by the institution. Pending transactions are short-lived. Each refresh will capture all available pending transactions at the time; if any of those transactions are not found in a subsequent refresh, they will be removed from the transaction response. There is no continuity guarantee for transactions to move from pending to active. When an institution changes a transaction from pending to posted, the pending transaction may be updated to active, or may be inactivated and a new transaction record with an active status may appear. This behavior is determined by the financial institution’s reporting. Pending transactions can only change to active or be removed from the response, they cannot change to shadow. Shadow Transactions LedgerSync has added the ability to identify transactions that were found in an earlier aggregation of an account, but are not found in the institution’s current data records. This feature is identified by the status field set to shadow. The shadow status on a transaction record is a transaction that was previously reported as active by the financial institution, but that financial institution removed that transaction record from their reporting in a subsequent aggregation, or the institution does not provide unique ids to identify the transaction and has significantly changed the transaction from a previous reporting. Due to variance in how financial institutions report transactions, including transactions that are modified or deleted long after they are posted, some shadow transactions are likely to appear as duplicates to active transactions. The shadow transaction feature is enabled for institutions known to engage in removing and reposting transactions to prevent false duplicates from appearing in the endpoint response. Shadow transactions can be handled by partners in a variety of ways, including choosing to not display these transactions at all; removing them from the data store; displaying a button to allow the customer to confirm these transactions should be removed; or ignoring the field entirely.
  • [Refresh Transactions](https://app.theneo.io/ledgersync/ledgersync-api/transactions/refresh-transactions.md): The Refresh Transactions section of the Ledgersync Rest API allows users to update and synchronize transaction data from a specific bank account. By triggering a refresh, users can ensure that their transaction records are up-to-date and accurate, enabling seamless financial management and reconciliation processes.
  • [Refresh Historic Transactions](https://app.theneo.io/ledgersync/ledgersync-api/transactions/refresh-historic-transactions.md): Refresh up to 24 months of historical transactions for the accounts. The length of history available depends on the institution. The recommended timeout setting for this request is 180 seconds to receive a response. However, the operation will still complete if you terminate the connection after making the call. To verify when the refresh is complete, you will need to check for an updated aggregation attempt date in the account records. The date range sent to the institution is based on the account's creation date. Consequently, making this service call a second time for the same account usually will not add any new transactions. Therefore, a subsequent call for a known account ID will typically return immediately.
• [Statements](https://app.theneo.io/ledgersync/ledgersync-api/statements.md): The Statement API section in Ledgersync allows users to retrieve detailed financial statements and transaction data. Users can access comprehensive information about their accounts and transactions, enabling them to efficiently manage their financial records and analyze their financial performance. This API section empowers users with valuable insights into their financial health and facilitates seamless integration with other financial tools.
  • [List Statements](https://app.theneo.io/ledgersync/ledgersync-api/statements/list-statements.md): This section allows users to retrieve a list of account statements for a specific client within the Ledgersync platform. By accessing this API resource, users can easily view and manage detailed information related to the client's account transactions and balances.
  • [Download Statement](https://app.theneo.io/ledgersync/ledgersync-api/statements/download-statement.md): This section in Ledgersync API allows users to retrieve their statement files in PDF format as byte arrays. By accessing this section, users can seamlessly download their statement files and manipulate them programmatically for further processing or storage. This functionality enhances the convenience and flexibility of managing financial data within the Ledgersync platform.
  • [Convert Statement](https://app.theneo.io/ledgersync/ledgersync-api/statements/convert-statement.md): The Convert API section in Ledgersync allows users to seamlessly transform PDF bank statements into either XLS or QBO formats. By utilizing this feature, users can efficiently convert and transfer financial data for further analysis or integration into their accounting systems. This functionality streamlines the process of converting statements, enhancing workflow productivity.
• [Checks](https://app.theneo.io/ledgersync/ledgersync-api/checks.md): The Checks API allows users to retrieve detailed information about checks, including their status, amount, and payment details. With this API, users can easily access and manage check data for efficient tracking and reconciliation processes.
  • [List Checks](https://app.theneo.io/ledgersync/ledgersync-api/checks/list-checks.md): This section allows users to retrieve a list of account checks associated with a specific client. Users can access detailed information such as check number, payee, transaction date, and total items, facilitating efficient management and tracking of client transactions.
• [Webhooks](https://app.theneo.io/ledgersync/ledgersync-api/webhooks.md): Webhooks allow your application to receive real-time notifications about specific events that occur within our platform. By setting up webhooks, your system can automatically respond to these events, enabling seamless integration and efficient workflows.
  • [Handling Webhooks](https://app.theneo.io/ledgersync/ledgersync-api/webhooks/handling-webhooks.md): When an event you are subscribed to occurs, our system will send an HTTP POST request to your specified callback URL. The payload will be in JSON format and include detailed information about the event. Example Payload: Select... { "eventType": "accountAdded", "eventId": "b52e0e1c-611f-43fb-89c4-401a34eb91ba ", "timestamp": "2024-07-15 13:07:07.727", "payload": { "accounts": "[1542, 1367, 1257]", } }
  • [Webhooks Events](https://app.theneo.io/ledgersync/ledgersync-api/webhooks/webhooks-events.md): accountAdded mfaUpdated transactionsRefreshed bankAccountDeleted
  • [Retries](https://app.theneo.io/ledgersync/ledgersync-api/webhooks/retries.md): Overview To ensure the reliability and delivery of webhook events, our system employs an automatic retry mechanism. If an initial webhook delivery attempt fails, the system will attempt to resend the event according to a predefined retry schedule. This approach helps to account for temporary issues such as network disruptions or server downtimes on the receiving end. Retry Schedule The retry mechanism follows an exponential backoff strategy with an initial delay of 30 seconds. The system will attempt retries up to a maximum duration of 3 days. The retry intervals increase exponentially as follows: Retry Number Time Elapsed Since Initial Attempt 1 30 seconds 2 1 minute 3 2 minutes 4 4 minutes 5 8 minutes 6 16 minutes 7 32 minutes 8 1 hour 4 minutes 9 2 hours 8 minutes 10 4 hours 16 minutes 11 8 hours 32 minutes 12 17 hours 4 minutes 13 1 day 10 hours 8 minutes 14 2 days 20 hours 16 minutes Conditions for Retry A retry is triggered if the initial delivery attempt fails due to receiving any HTTP response code other than a 2xx status code (e.g., 200 OK, 201 Created). This includes, but is not limited to: Client errors (4xx), such as 404 Not Found, 401 Unauthorized, etc. Server errors (5xx), such as 500 Internal Server Error, 502 Bad Gateway, etc. Maximum Retry Duration The system will continue to retry delivery for a maximum of 3 days. If the event has not been successfully delivered after this period, the delivery attempts will cease, and the event will be marked as failed. Exponential Backoff Strategy The exponential backoff strategy helps to reduce the load on both the sender and the receiver by gradually increasing the time between retries. This ensures that temporary issues on the receiving server have time to resolve before the next attempt is made. Handling Successful Delivery Upon successful delivery of the webhook event (i.e., when a 2xx response code is received), no further retries will be attempted. The system will mark the event as successfully delivered, and you will no longer see retry attempts for that specific event. Best Practices To ensure the best experience and reliability in receiving webhooks: Ensure your server is configured to handle incoming webhook requests promptly. Implement appropriate error handling and response codes to communicate with our retry mechanism. Consider using a queueing mechanism on your server to manage and process incoming webhook events efficiently.
• [Testing](https://app.theneo.io/ledgersync/ledgersync-api/testing.md): This section designed to assist developers in thoroughly testing their integration with our API using simulated financial institution data. This ensures that your application can gracefully handle various scenarios, from successful connections to handling errors and multi-factor authentication (MFA) challenges. Testing with Finbank To facilitate effective testing, we recommend using "Finbank" within the widget to simulate bank connections. Finbank is a fictional financial institution available in the testing environment that mimics real bank behavior, allowing you to test different user scenarios without connecting to actual banks. Procedure Search for "Finbank" in the widget to begin testing. Select any bank from the list provided by Finbank. Enter the provided credentials (username and password) as per the table below when prompted. Follow on-screen instructions to complete the testing scenario, which may include handling MFA challenges or encountering specific errors based on the credentials used. Test Accounts and Scenarios Below is a table of usernames, passwords, and the expected outcomes when using these credentials in the testing environment. These accounts cover a range of scenarios, including successful connections, handling of various MFA types, and error simulations. Username Password MFA Type Testing Details demo go (none) Success demo Codes: 123,125,127, 128, or 130 (none) Service will fail with the error code given in password. invalid_user go (none) Returns Error 103: Invalid Credentials. tfa_text go Text-based MFA If the answer to the MFA challenge is "mfa", then the response is another MFA challenge. tfa_image go Image captcha Any MFA answer is accepted. tfa_choice go Multiple text options If the answer to the MFA challenge is "fail", the call fails with code 187 (Invalid MFA). tfa_multi go Same as MFA with image choice (style 1) Any MFA answer is accepted. demo imagechoice MFA with image choice (style 1) Any MFA answer is accepted. demo imagechoice2 MFA with image choice (style 2) Any MFA answer is accepted.