Pushing Data

Overview

Railz has enabled financial institutions and FinTechs to access normalized and structured accounting data from different accounting service providers. However, SMEs today demand a better level of integration between the different financial and operations tools they use on daily basis. That's why it's important to deliver an end-to-end solution by providing our users with the ability to push data back into a businesses' accounting service provider.

📘

Before you can update a business' accounting data using the Railz API, you will need an active business connection (see our documentation on creating a new connection).

Railz currently supports the ability to create a record in a business' accounting service provider (POST) only, and it is implemented as follows.

1. Review Data Model

Before pushing data into an accounting service provider, you need to review how each provider likes the data to be inserted. This includes referencing objects which are often handled differently between different accounting service providers. A good example of this is specifying whether an invoice should reference an account ID or nominal code.

Railz was designed to provide users and developers with the flexibility to push objects independent of the format each accounting service provider expect. Please review the Railz Accounting Data Model in combination with our API Reference, which highlights the required parameters for a specific connection and the optional ones that may be selected.

2. Query Referenced Object

Some push endpoints require referencing other objects in their request body.

For example, pushing an invoice requires you to reference a customerRef. To do so, you would need to query the Customers object.

3. Pushing an Object

🚧

Pushing data not referenced in Data Model

If you attempt to push an object using parameters that are not documented in the Data Model mapping for that accounting service provider, the additional data may not be pushed and you may receive validation errors in response to your "push" request.

All push endpoints have the following format: POST /{dataType} (e.g. Invoices )

Each push endpoint expects a JSON object conforming to the endpoint's structure and data model as a request body.

The response from each push endpoint is a push response object, which is structured as follows:

{
  "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
  "serviceName": "quickbooks",
  "pushCommunicationId": "60473b57f0cdd1683ca71f60",
  "requestedOn": "2021-03-09T08:15:22.035Z",
  "status": "pending",
  "data": {
    "customerRef": "132",
    "postedDate": "2021-03-29",
    "dueDate": "2021-03-29",
    "currency": "CAD",
    "currencyRate": 1.13,
    "lines": [
      {
        "description": "Services rendered.",
        "unitAmount": 100.5,
        "quantity": 3,
        "subTotal": 301.5,
        "taxAmount": 20.5,
        "totalAmount": 322,
        "taxRef": "24",
        "itemRef": "240",
        "accountRef": "145"
      }
    ],
    "memo": "Example invoice memo."
  }
}
  • businessName: The business name provided in the push request.
  • serviceName: The accounting service name provided in the push request.
  • pushCommunicationId: A unique identifier generated by Railz to represent this single push request. This identifier can be used to track the status of the push, and should be persisted.
  • requestedOn: The datetime (in UTC) when the push was requested.
  • status: The status of the push request, which can be pending, failed, or success.
  • data: The object which was pushed.

🚧

Asynchronous Push

All push endpoints are implemented to work asynchronously so you will receive a pending push status in response to your push request.

4. Monitoring Push Status

You may want to build a process that will provide an update on the final push status so that the results of the push can be communicated to the user, or further actions can be taken by your app.

Railz supports two methods for monitoring the status of push requests: polling and webhooks.

📘

Monitoring Push Status on Sandbox

  • Polling the push status using the API will always return pending as a status.
  • Push status webhook events are not available on Sandbox.

Polling

The Railz API provides an endpoint for monitoring the status of all push requests, identified by the pushCommunicationId returned when you requested the push.

You can list all push requests for a business using GET /data/pushStatus

You can also filter the results by including serviceName or pushCommunicationId in your GET /data/pushStatus request.

📘

We recommend using pushCommunicationId to get the status of a single push request.

Webhooks

A second option for monitoring push requests is to subscribe to the "Push Status" event. This can be setup by following the instructions in our documentation for Events & Webhooks.

See Push Status event for more details.


Read Next

Before data can be retrieved or pushed using Railz, you will need to create a new connection and wait for a successful data synchronization.

Did this page help you?