Step 2: Create a Connection

Use Railz Connect™ to connect to your business users' financial data with the Railz API

Railz Connect™ is the client-side component that your business users will interact with in order to connect their accounts to Railz and authorize you to access their financial data via the Railz API. In this step, you will be:

  • Adding a business
  • Initializing Railz Connect™
  • Creating a business connection in Sandbox
  • Synchronizing business financial data

Adding a Business

  1. Businesses in Railz are your customers. You can create new businesses using the POST /businesses endpoint. For testing purposes, you can use the sample request below and paste it into the request body.
{
  "businessName": "Railz Test Business"
}
  1. Upon successful execution of the API, you will get a response code of 200 and the response body will contain details of the new business. Copy the businessName. You will need it to complete the next steps.
{
    "businessUUID": "BIZ-67679345-ab8e-4880-b22a-f6ac59183d24",
    "businessName": "Railz Test Business",
    "status": "new",
    "createdAt": "2021-10-11T05:50:10.091Z"
}

Initializing Railz Connect™

  1. Once logged into the Railz Dashboard™, click the Connect section on the sidebar to get your code snippet. Copy the snippet and add it to your application.
Railz Connect Setup Page. Click to Expand.Railz Connect Setup Page. Click to Expand.

Railz Connect Setup Page. Click to Expand.

❗️

Railz always publishes non-breaking updates and improvements to Railz Connect™. To ensure that you're using the latest version of Railz Connect™, do not download and host the railz-connect.js file within your app.

  1. To the snippet copied above, add the businessName parameter with the business name you created above as a value. Once added, your code snippet should look like this:

📘

Refer to the customize Railz Connect™ section for more information.

<!-- Insert this div where you want Railz Connect to be initialized -->
<div id="railz-connect"></div>


<!-- Start of Railz Connect script -->
<script src="https://connect.railz.ai/v1/railz-connect.js"></script>
<script>
  var widget = new RailzConnect();
  widget.mount({
    parentElement: document.getElementById('railz-connect'),
    widgetId: 'YOUR_WIDGET_ID',
    businessName: 'Railz Test Business'
  });
</script>
<!-- End of Railz Connect script -->

📘

You can skip adding a business via the API if you want to create a business directly through Railz Connect™ by providing a businessName parameter or letting Railz generate a unique business name based on the businessUUID. To create a better user flow, we recommend using the POST /businesses endpoint to create a new business, then using it as a value for the businessName parameter.

Create a business connection in Sandbox

With Railz Connect™ installed and a new business created, you can now connect it to the Railz Sandbox service provider. Railz Sandbox is our dummy accounting service provider for you to test happy paths and edge cases while experimenting with different functionalities. Railz Sandbox contains dummy accounting data generated especially for the purpose of your testing. While we have tried to make this data as varied as possible, please bear in mind it is mostly generated by our team and we cannot guarantee its completeness or accuracy.

Open the URL of your application that contains the Railz Connect™ code snippet. This is the URL your business customers will access when your application is live. You will be prompted to connect to the Sandbox and create a new connection.

Railz Connect - the business customers view when connecting their service providers to Railz.Railz Connect - the business customers view when connecting their service providers to Railz.

Railz Connect - the business customers view when connecting their service providers to Railz.

Once the business authorizes the connection, its status under GET /businesses changes to active.

{
  "businessName": "Railz Test Business",
  "status": "active",
  "createdAt": "2021-09-21T19:46:29Z",
  "updatedAt": "2021-09-21T19:47:12Z",
  "connections":
  [
    {
      "connectionId": "CON-be7493d9-392d-403c-a604-d79de0eb78d9",
      "status": "active",
      "firstRecordDate": "2021-07-04T00:00:00.000Z",
      "serviceName": "sandbox",
      "createdAt": "2021-09-21T19:46:32Z",
      "updatedAt": "2021-10-11T04:51:03Z"
    }
  ]
}

Synchronizing business financial data

Before you can see the data of the connected business in the Railz Dashboard or API, they need to be synchronized. When your business customer authorizes connection to their business data, Railz automatically retrieves all the supported data types. Please see synchronizing data before your to proceed to the next step.


Did this page help you?