Step 4: Make an API Call

So far, we have covered how to embed Railz Connect™ in your client-side application and use it to connect to accounting service providers. This section will guide you through the process of retrieving the accounting data using businessName and serviceName.

Overview

Anytime you want to access your user's accounting data, you will need to use the businessName and serviceName associated with that user's connection to make a request to our API.

Here is a step by step overview of this process:

  1. A successful connection redirects the user to the landing page of your choice. At this moment, you are able to access the businessName and serviceName.
  2. When you initiate an API call, the businessName and serviceName are used to request data and receive it.

API Requests

Okay, let’s dig deeper into how exactly you can retrieve accounting data from connected accounting service providers.

📘

If you are still not sure how to perform these API calls, head over to our API Reference for more details.

🚧

API Authentication

Railz expects an authentication token to be included in all API requests to the server. Refer to the Authentication section in API Reference for more information.

To make it more concrete, let's suppose that you are making a request to retrieve the monthly balance sheets for businessName:BIZ-63702dcc-d2de-443f-8a20-138c48850fcc and serviceName:quickbooks:

curl --request GET \
    https://api.railz.ai/balanceSheets?businessName=BIZ-63702dcc-d2de-443f-8a20-138c48850fcc&reportFrequency=month&serviceName=quickbooks \
  -H 'Content-Type: application/json'

The most common first response to get in a request for data returns a HTTP 202, meaning that the data you are requesting is still being processed.

Here's an example of a typical API response for data pending processing:

{
  "count": 0,
}

Because of this, your server needs to expect and be able to handle this response and proceed to poll the request to receive the data. Alternatively, you can take advantage of Webhook events to receive the data once it's extracted.

❗️

Your integration must handle empty/data in process response.

Once your data is done being processed, the API will respond with a HTTP 200 and a JSON payload containing all the data we collected from the accounting service provider in a standard format. Your app server will be ready to start handling it according to your use-case.

{
  "count": 2,
  "reports": [
    {
      "meta": {
        "reportId": "6000000aa6411a1f166e7543",
        "startDate": "2020-06-01T00:00:00",
        "endDate": "2020-09-30T00:00:00",
        "serviceName": "quickbooks",
        "businessName": "DemoBusiness",
        "reportFrequency": "quarter",
        "currency": "CAD",
        "createdAt": "2021-01-16T21:14:39",
        "updatedAt": "2021-01-16T21:14:39"
      },
      "data": [
        {
          "section": "Assets",
          "subSection": "Current Assets",
          "group": "Other Current Assets",
          "subGroup": "Bank Accounts",
          "account": "Business Bank Account",
          "value": 1612270.67
        },
        {
          "section": "Assets",
          "subSection": "Current Assets",
          "group": "Other Current Assets",
          "subGroup": "AR",
          "account": "Accounts Receivable (A/R)",
          "value": 10324.27
        },
        {
          "section": "Assets",
          "subSection": "Current Assets",
          "group": "Other Current Assets",
          "account": "Uncategorized Asset",
          "value": -1394.37
        },
        {
          "section": "Assets",
          "subSection": "Current Assets",
          "group": "Other Assets",
          "subGroup": "Fixed Assets",
          "account": "Accumulated Depreciation",
          "value": -1500
        },
        {
          "section": "Assets",
          "subSection": "Current Assets",
          "group": "Other Assets",
          "subGroup": "Fixed Assets",
          "account": "Furniture and Fixtures",
          "value": 10000
        },
        {
          "section": "Liabilities",
          "subSection": "Current Liabilities",
          "group": "Other Current Liabilities",
          "subGroup": "AP",
          "account": "Accounts payable (A/P)",
          "value": 8078.89
        },
        {
          "section": "Liabilities",
          "subSection": "Current Liabilities",
          "group": "Other Current Liabilities",
          "account": "Bank Revaluations",
          "value": -110
        },
        {
          "section": "Liabilities",
          "subSection": "Current Liabilities",
          "group": "Other Current Liabilities",
          "account": "GST/HST Payable",
          "value": 5498.18
        },
        {
          "section": "Liabilities",
          "subSection": "Current Liabilities",
          "group": "Other Current Liabilities",
          "account": "Unrealised Currency Gains",
          "value": -1091.22
        },
        {
          "section": "Liabilities",
          "subSection": "Non-Current Liabilities",
          "group": "Long Term Liabilities",
          "account": "Shareholder Notes Payable",
          "value": 510000
        },
        {
          "section": "Liabilities",
          "subSection": "Non-Current Liabilities",
          "group": "Long Term Liabilities",
          "account": "Small Business Loan - BoA",
          "value": 70000
        },
        {
          "section": "Equity",
          "subSection": "Equity",
          "account": "Owners’ Equity — Invested Capital",
          "value": 1000000
        },
        {
          "section": "Equity",
          "subSection": "Equity",
          "group": "Net Income",
          "account": "Profit for the year",
          "value": 37324.72
        }
      ]
    }
  ]
}

Progress Check

Before moving on, let's review what we just did:

👍

Mastered the API Calls Flow

  • Use businessName and serviceName to request accounting data.
  • Request data with /balanceSheets and handle 202 empty/pending response.
  • Request data with /balanceSheets and handle 200 data ready response.

Did this page help you?