Understand how to push data to service providers using the Railz API
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:
{
"connectionUuid": "CON-396d5daa-26b2-4979-89b6-cafb2c298155",
"pushCommunicationId": "60473b57f0cdd1683ca71f60",
"requestedOn": "2021-03-09T08:15:22.035Z",
"status": "pending",
"data": {
"invoiceNumber": "INV-10546",
"postedDate": "2021-03-29",
"dueDate": "2021-03-29",
"currency": "CAD",
"currencyRate": 1.13,
"memo": "Example invoice memo.",
"customerRef": {
"id": "124"
},
"lines": [
{
"description": "Services rendered.",
"quantity": 3,
"discountPercentage": 30,
"taxRateRef": {
"id": "12"
},
"accountRef": {
"id": "200"
},
"inventoryRef": {
"id": "32"
},
"trackingCategoryRefs": [
{
"id": "4040",
"type": "class"
}
],
"unitAmount": 100.5
}
],
"subsidiaryRefs": [
{
"id": "4"
}
]
}
}
connectionUuid
: The connection unique id.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 bepending
,failed
orsuccess
.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.