Pushing Data

Overview

The API allows you to push data to create and update transactions in a businesses' accounting service provider using the Accounting Data as a Service™ data model

Types of Push

We 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. We enforce some additional rules when updating to help ensure the business' data integrity.

1. Review Data Model

Accounting Data as a Service™ was designed to allow users and developers to push objects independently of the format each accounting service provider expects. Please review the 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. Push Options

📘

To understand in details what fields are required per Accounting Service Provider, use the GET/pushOptionsendpoint.

Prior to sending data to the API, it's crucial to have a clear grasp of the specific rules and requirements associated with each accounting service provider. To facilitate this, we highly recommend utilizing the GET/pushOptions endpoint. This endpoint provides you with essential information regarding the fields that must be provided for a particular accounting service provider, as well as the various available choices for each field. This ensures smooth integration and compliance with the unique specifications of each provider.

Below is an example response from this endpoint:

 {
            "title": "quickbooks accounts POST",
            "requestType": "accounts",
            "serviceName": "quickbooks",
            "method": "POST",
            "properties": {
                "nominalCode": {
                    "type": "string",
                    "description": "The nominal code of the account used to classify accounts by department or account type.",
                    "required": false
                },
                "name": {
                    "type": "string",
                    "description": "Name of the account.",
                    "required": true
                },
                "description": {
                    "type": "string",
                    "description": "Description of the account.",
                    "required": false
                },
                "currency": {
                    "type": "string",
                    "description": "ISO-4217 currency code of the account.",
                    "required": false
                },
                "type": {
                    "type": "string",
                    "description": "Type of an account in the accounting service, e.g. Fixed Asset.",
                    "required": true
                },
                "taxRateRef": {
                    "type": "object",
                    "description": "Reference to the default tax rate used by this account. ",
                    "required": false,
                    "properties": {
                        "id": {
                            "type": "string",
                            "description": "",
                            "required": false
                        }
                    }
                }
            }
        }

This example describes the account object for QuickBooks Online. Within the properties section you will find:

• type: It tells the type of that field
• description: Description related to that specifict field.
• required: If the field is required or not for that accounting service provider.

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

4. 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 us 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.

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

Accounting Data as a Service™ 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 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.