Pushing Data

Overview

The Railz API allows you to push data to create and update transactions in a businesses' accounting service provider using the Railz data model

Types of Push

Railz currently supports the ability to create new records (POST) and update existing ones (PUT) in a business' accounting service provider and it is implemented as follows.

Create and update operations behave similarly, with both having an options endpoint and returning a pushCommunicationId as described in the sections below to allow you to monitor the state of the push. Railz enforces some additional rules when updating to help ensure the business' data integrity.

1. Review Data Model

Railz was designed to allow users and developers to push objects independently of the format each accounting service provider expects. Please review the Railz Accounting Data Model in 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

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

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 the serviceName or pushCommunicationId in your GET /data/pushStatus request.

📘

Use pushCommunicationId

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 Webhooks.

See Push Status event for more details.