NAV
shell javascript

9Spokes Open

Overview

Welcome! 9Spokes Open APIs are categorized by a growing list of data sources like Accounting, Banking, POS and others.

Under each data category, the following pieces are listed:

Authentication

To authorize, use this code:

# The example below assumes you have the API_ROOT and API_KEY environment variables set
curl https://${API_ROOT}/ -H "Authorization: ${API_KEY}"
import 9spokes from 'nsp';

const api = 9spokes.authorize(process.env.API_KEY);

The example above assumes the API_KEY is defined as an environment variable.

All requests to any 9Spokes API require a valid API key. API keys are 64-byte strings and should be attached to each request using the HTTP Authorization header.

Do not specify a scheme (such as basic or bearer) and do not base64-encode your key. Instead, use your API key directly in the Authorization header.

Authorization: 63TX2kPSahV...xk7MKge9ut

Environments

Sandbox

All app developers must begin their journey by first integrating with our sandbox environment. The sandbox environment allows you to safely test your application without worrying about scopes, rate limits, or other production features.

You may generate up to 2 Sandbox API keys, the first of which is automatically generated and sent to you by email.

Production

Once your app development is complete, you may request Production API keys to interact with the live environment. Production APIs are identical to their Sandbox counterparts with the exception of the root URL.

API Structure

Requests

The 9Spokes API organizes data in a RESTful manner. This means data resources are organized hierarchically, with the company object being the topmost resource in most cases.

Responses

All API responses adhere to a strict JSON data format making it easy for app developers to parse success & error responses. The content-type is always application/json and the response body is always an object containing, at the very least, a status key. The value of status is either ok for successes or err for errors.

HTTP status codes are used to further categorize the response. The table below denotes all the supported HTTP response codes.

HTTP Code Meaning Corrective Action
200 OK The request was processed successfully.
400 Bad Request The request is invalid. Check the format of your request and try again.
401 Unauthorized The API key is not accepted.
403 Forbidden The request is denied, however the API key may be valid.
404 Not Found The specified resource does not exist.
405 Method Not Allowed Only the documented HTTP verbs are supported.
429 Too Many Requests You have hit a rate limit. Reduce your request rate.
500 Internal Server Error An internal error has occurred processing your request.
503 Service Unavailable The API is temporarily unavailable.

Success Response

Successful responses yield a HTTP status code of 200 and a JSON body similar to the structure below:

A typical success response

{
  "status": "ok",
  "correlationId": "daf07c66-c954-4853-ab5d-01c7b29b80a9",  
  "details": {
    // data
  }
}

The status key is set to ok and the details key is present.

Error Response

API requests that could not be processed will carry a HTTP code that is greater than 399 and a body similar to the structure shown here.

An error response. message contains the error string

{
  "status": "err",
  "correlationId": "daf07c66-c954-4853-ab5d-01c7b29b80a9",
  "message": "This connection does not exist"
}

Correlation ID

A correlationId is included in both successful and error response. Please provide this ID if you are contacting 9Spokes support regarding an issue.

Querying

The 9Spokes API uses OData (Open Data Protocol) format to filter response data.

Filter ($filter)

The $filter query option allows you to filter data sets based on the properties available.

Operator Description
eq Equal
ne Not equal
gt Greater than
ge Greater than or equal
lt Less than
le Less than or equal
and Logical and
or Logical or

/companies/{companyId}/connections/{connectionId}/data/invoices?$filter=data.transaction_status eq 'UNPAID'

/companies/{companyId}/connections/{connectionId}/data/invoices?$filter=data.transaction_date eq 2021-08-11

Orderby ($orderby)

The $orderBy query option allows you to order data sets based on the property name provided.

/companies/{companyId}/connections/{connectionId}/data/invoices?$orderBy=data.transaction_date

Select ($select)

The $select query option allows you to request a specific set of properties.

At least 2 property names must be provided.

/companies/{companyId}/connections/{connectionId}/data/invoices?$select=data.transaction_date,data.transaction_status

Pagination

The 9Spokes API default page is set to size 10, however this can be modified. A response will have total property showing a specified number of results.

A typical success response of data

{
  "results": [...],
  "total": 50,
}

/companies/{companyId}/connections/{connectionId}/data/invoices?$top=5

/companies/{companyId}/connections/{connectionId}/data/invoices?$top=5&$skip=5

Using Postman

For convenience, you may download a copy of a pre-defined Postman collection to help you get started quickly.

You will need to input your own API key by choosing the folder-level Authorization (9Spokes Open > Authorization) and inputing a key in the Value field.

Configuring Authorization

The collection is grouped logically by object type. Each object type (e.g. Organization, Companies, Connections, ...etc) is kept in its own folder.

Object Types

Organization

The organization endpoint is used to manage settings & preferences for your account.

Managing Redirect URL

Get Redirect URL

Update the redirect URL using a PUT request

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/organization/redirect_url \
    -X PUT \
    -d "redirect_url=https://example.com/callback" \
    -H "Content-type: application/x-www-form-urlencoded" \    
    -H "Authorization: ${API_KEY}"

The response indicates whether the update was successful or not.

{
    "status": "ok",
    "details": "The redirect URL was set successfully"
}

/organization/redirect_url

This endpoint is used to configure the URL where your users are redirected to after completing a consent flow. Whether the flow succeeds or not, the redirect_url will be used to redirect the user agents back to your platform.

The redirect_url must be an absolute URL and it must be URL-encoded.

Field Location Type Description
redirect_url Body string The URL where users are sent after a consent flow

Set Redirect URL

Retrieve the current redirect URL using a GET request

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/organization/redirect_url \
    -H "Authorization: ${API_KEY}"

The details.redirect_url key contains the current redirect URL

{
    "status": "ok",
    "details": {
        "redirect_url": "https://example.com/callback"
    }
}

/organization/redirect_url

This endpoint is used to retrieve the currently configured redirect URL.

Managing Apps

List Apps

Use a GET request to fetch the list of apps configured

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/organization/apps \
    -H "Authorization: ${API_KEY}"

The details key contains an array of apps and their status

{
    "status": "ok",
    "details": [
        {
            "name": "xero",
            "status": "enabled",
            "client_id": "91E5715...BC1648",
            "client_secret": "4e7747ce...0775166c5f",
            "recurring": true
        },
        ...
    ]
}

/organization/apps

This endpoint is used to retrieve the status of all supported apps for your account.

Enable App

Enable an app by providing the OAuth2 client credentials in the body

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/organization/apps/xero \
    -X PUT \
    -d "client_id=91E5715...BC1648&client_secret=4e7747ce...0775166c5f&recurring=true" \
    -H "Content-type: application/x-www-form-urlencoded" \
    -H "Authorization: ${API_KEY}"

The response indicates whether the update was successful or not.

{
    "status": "ok",
    "details": "The Xero app credentials were updated successfully"
}

/organization/apps/{app}

This endpoint is used to enable an app integration and updating the OAuth2 client credentials. The client_id and client_secret are required whereas the recurring field defaults to false if omitted.

Field Location Type Description
app Path string The app to update
client_id Body string The OAuth2 client ID
client_secret Body string The OAuth2 client secret
recurring Body bool Whether to continuously pull data for this connection or not, defaults to false

Disable App

Disable an app by issuing a DELETE request

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/organization/apps/xero \
    -X DELETE \
    -H "Authorization: ${API_KEY}"

The response is always positive, even if the app is not previously enabled

{
    "status": "ok",
    "details": "The Xero app was successfully removed"
}

/organization/apps/{app}

This endpoint is used to disable an app integration. The API call always succeeds.

Field Location Type Description
app Path string The app to update

Companies

A Company object represents a real business or organization. Companies are the most fundamental data container whereby all connections and all their associated data must belong to a company object.

Create New Company

Create a new company by providing a company name

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies \
    -X POST \
    -d "name=9Socks" \
    -H "Content-type: application/x-www-form-urlencoded" \
    -H "Authorization: ${API_KEY}"

The response includes the new connection ID under the id key and the authorize_url require to activate the connection.

{
    "status": "ok",
    "details": {
        "id": "97436a79-0293-485e-8aad-eb629f5c9dfd",
        "name": "9Socks",
        "created": "2020-12-09T22:26:59.999Z",
        "updated": "2020-12-09T22:27:00Z",
    }
}

/companies

Creating a new company is done using a POST request to the companies endpoint.

Field Location Type Description
name Form string The name of the Company to create

List Companies

Fetch all companies

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies \
    -H "Authorization: ${API_KEY}"

The details key is an array of companies

{
    "status": "ok",
    "details": [
        {
            "id": "97436a79-0293-485e-8aad-eb629f5c9dfd",
            "name": "9Socks",
            "created": "2020-12-09T22:26:59.999Z",
            "updated": "2020-12-09T22:27:00Z",
        }
    ]
}

/companies

Retrieving all the companies is done using a GET request to the companies endpoint.

Get a Company

Retrieves a single company with ID 97436a79-0293-485e-8aad-eb629f5c9dfd

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/97436a79-0293-485e-8aad-eb629f5c9dfd \
    -H "Authorization: ${API_KEY}"

The details key is the connection object

{
    "status": "ok",
    "details": {
        "id": "97436a79-0293-485e-8aad-eb629f5c9dfd",
        "name": "9Socks",
        "created": "2020-12-09T22:26:59.999Z",
        "updated": "2020-12-09T22:27:00Z",
    }
}

/companies/{company}

Retrieving a specific company record is done using a GET request specifying the company as path parameters.

Field Location Type Description
company Path string The ID of the company to retrieve

Remove a Company

Delete a company with ID 97436a79-0293-485e-8aad-eb629f5c9dfd

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/97436a79-0293-485e-8aad-eb629f5c9dfd \
    -X DELETE \
    -H "Authorization: ${API_KEY}"

The operation status is either ok or err

{
    "status": "ok",
    "details": "Company deleted successfully"
}    

/companies/{company}

Removing a company is done by issuing a DELETE request and specifying the company ID in the path.

Field Location Type Description
company Path string The ID of the company to remove

Connections

A connection represents a link to a data provider. Connections belong to companies and they are mutually exclusive from one another. Only a single connection of any type can belong to any given company.

Connections transition through several preset stages as the end-user creates, consents to, and terminates a connection to a given app. The supported connection states are listed below.

Connection Lifecycle

State Description
NEW The connection was created and has not yet been authorized
ACTIVE The connection has been authorized and data is flowing
NOT_CONNECTED The connection to the app provider has been lost and user intervention is required
REMOVED The connection has been disabled and is pending removal

Create New Connection

Create a new connection of type sage for company ID 9091a260-1292-4874-bbe5-3693a341d332

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/9091a260-1292-4874-bbe5-3693a341d332/connections \
    -X POST \
    -d "app=sage" \
    -H "Content-type: application/x-www-form-urlencoded" \
    -H "Authorization: ${API_KEY}"

The response includes the new connection ID under the id key and the authorize_url require to activate the connection.

{
    "status": "ok",
    "details": {
        "id": "087cd170-ec96-4898-bf97-2ecf82ab7cc1",
        "created": "2021-05-11T10:46:39.589Z",
        "modified": "2021-05-11T11:00:04.415Z",
        "osp": "sage",
        "status": "NEW",
        "authorize_url": "https://cb.9spokes.io/redirect?q=4QICwWaXTrrRG%2FVOABjOuQqKNbuoQv3x2n6qyfVpPuIVxAmSZwIQOw3idGUATLJ9VBgomwzm7il40fG5ElywgW5lKXOHT54FJqG5h5vGtBWWLEjxpQaM7eCPDps3aPD62OTk2mU03ZtfYCdzLj40SXrT3k5YyQqrX91ZUuZLIrIt%2BaIRB4NiNLlDYMhY%2FZHtsB5F19NqqL7TeXu5r14vz4Uh8f3%2BXrRQG1sAViQOR1PW7ZU7w2PrQzK77sm7%2BUmejFTuUqfWBZfS8dASQ3i51yWX%2Fbu0lD1IUimI4KsUfmaHXldydDhj41%2B1sFJG7dNk9GwHpHFPag4SKHbIV49nRYZUQJAxRqVfHYDihHrYOgQEwx6b2KJQhFPYDg60OnMdJLVEx7mn0ElK40IWYQ5omYbNxea9jhGifcGqRzKAZGWlUmY0ETK7GQD3DGZdMC2X4YtfgGp9gKF5mfMMIBWr8w%3D%3D"
    }
}    

/companies/{company}/connections

Creating a new connection for a given company is done using a POST request to the connections endpoint for that company.

Field Location Type Description
company Path string The ID of the company
app Form string The name of the app to connect

The authorize_url key in the response should be used to redirect the user agent.

List Connections

Fetch all connections for company ID 9091a260-1292-4874-bbe5-3693a341d332

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/9091a260-1292-4874-bbe5-3693a341d332/connections \
    -H "Authorization: ${API_KEY}"

The details key is an array of connections

{
    "status": "ok",
    "details": [
        {
            "id": "087cd170-ec96-4898-bf97-2ecf82ab7cc1",
            "created": "2021-05-11T10:46:39.589Z",
            "modified": "2021-05-11T11:00:04.415Z",
            "osp": "sage",
            "status": "ACTIVE",
            "authorize_url": "https://cb.9spokes.io/redirect?q=4QICwWaXTrrRG%2FVOABjOuQqKNbuoQv3x2n6qyfVpPuIVxAmSZwIQOw3idGUATLJ9VBgomwzm7il40fG5ElywgW5lKXOHT54FJqG5h5vGtBWWLEjxpQaM7eCPDps3aPD62OTk2mU03ZtfYCdzLj40SXrT3k5YyQqrX91ZUuZLIrIt%2BaIRB4NiNLlDYMhY%2FZHtsB5F19NqqL7TeXu5r14vz4Uh8f3%2BXrRQG1sAViQOR1PW7ZU7w2PrQzK77sm7%2BUmejFTuUqfWBZfS8dASQ3i51yWX%2Fbu0lD1IUimI4KsUfmaHXldydDhj41%2B1sFJG7dNk9GwHpHFPag4SKHbIV49nRYZUQJAxRqVfHYDihHrYOgQEwx6b2KJQhFPYDg60OnMdJLVEx7mn0ElK40IWYQ5omYbNxea9jhGifcGqRzKAZGWlUmY0ETK7GQD3DGZdMC2X4YtfgGp9gKF5mfMMIBWr8w%3D%3D"
        }
    ]
}

/companies/{company}/connections

Retrieving all the connections for a given company is done using a GET request to the connections endpoint for that company.

Field Location Type Description
company Path string The ID of the company

Get a Connection

Retrieves a single connection with ID 087cd170-ec96-4898-bf97-2ecf82ab7cc1

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/9091a260-1292-4874-bbe5-3693a341d332/connections/087cd170-ec96-4898-bf97-2ecf82ab7cc1 \
    -H "Authorization: ${API_KEY}"

The details key is the connection object

{
    "status": "ok",
    "details": {
        "id": "087cd170-ec96-4898-bf97-2ecf82ab7cc1",
        "created": "2021-05-11T10:46:39.589Z",
        "modified": "2021-05-11T11:00:04.415Z",
        "osp": "sage",
        "status": "ACTIVE",
        "authorize_url": "https://cb.9spokes.io/redirect?q=4QICwWaXTrrRG%2FVOABjOuQqKNbuoQv3x2n6qyfVpPuIVxAmSZwIQOw3idGUATLJ9VBgomwzm7il40fG5ElywgW5lKXOHT54FJqG5h5vGtBWWLEjxpQaM7eCPDps3aPD62OTk2mU03ZtfYCdzLj40SXrT3k5YyQqrX91ZUuZLIrIt%2BaIRB4NiNLlDYMhY%2FZHtsB5F19NqqL7TeXu5r14vz4Uh8f3%2BXrRQG1sAViQOR1PW7ZU7w2PrQzK77sm7%2BUmejFTuUqfWBZfS8dASQ3i51yWX%2Fbu0lD1IUimI4KsUfmaHXldydDhj41%2B1sFJG7dNk9GwHpHFPag4SKHbIV49nRYZUQJAxRqVfHYDihHrYOgQEwx6b2KJQhFPYDg60OnMdJLVEx7mn0ElK40IWYQ5omYbNxea9jhGifcGqRzKAZGWlUmY0ETK7GQD3DGZdMC2X4YtfgGp9gKF5mfMMIBWr8w%3D%3D"
    }
}

/companies/{company}/connections/{connection}

Retrieving the connection record for a given company is done using a GET request specifying both the connection and the company as path parameters.

The result contains the state of the connection (see connection lifecycle) as well as the data extraction status for each underlying data source.

Field Location Type Description
company Path string The ID of the company
connection Path string The ID of the connection to retrieve

Remove a Connection

Delete a connection for company ID 9091a260-1292-4874-bbe5-3693a341d332 with ID 087cd170-ec96-4898-bf97-2ecf82ab7cc1

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/9091a260-1292-4874-bbe5-3693a341d332/connections/087cd170-ec96-4898-bf97-2ecf82ab7cc1 \
    -X DELETE \
    -H "Authorization: ${API_KEY}"

The operation status is either ok or err

{
    "status": "ok",
    "details": "Connection deleted successfully"
}    

/companies/{company}/connections/{connection}

Removing a connection for a given company is done by issuing a DELETE request and specifying both the connection and company in the path.

Field Location Type Description
company Path string The ID of the company
connection Path string The ID of the connection to remove

Get Connection Data Status

Get a connection data status for company ID: 9091a260-1292-4874-bbe5-3693a341d332 with connection ID: 087cd170-ec96-4898-bf97-2ecf82ab7cc1

# The example below assumes you have the API_ROOT and API_KEY environment variables set
$ curl https://${API_ROOT}/companies/9091a260-1292-4874-bbe5-3693a341d332/connections/087cd170-ec96-4898-bf97-2ecf82ab7cc1/status \
    -X GET \
    -H "Authorization: ${API_KEY}"

The operation status is either ok or err

{
    "status": "ok",
    "correlationId": "e9138503-c8a3-412e-8f68-403adc547b1e",
    "details": [
        {
            "datasource": "products",
            "total": 1,
            "completed": 1,
            "last_updated": "2021-09-16T23:41:36.814Z"
        },
        {
            "datasource": "bank_accounts",
            "total": 1,
            "completed": 1,
            "last_updated": "2021-09-22T12:00:45.327Z"
        },
        {
            "datasource": "invoices",
            "total": 395,
            "completed": 395,
            "last_updated": "2021-09-23T04:00:41.429Z"
        },
        {
            "datasource": "bills",
            "total": 395,
            "completed": 395,
            "last_updated": "2021-09-23T04:00:41.403Z"
        },
        {
            "datasource": "trial_balance",
            "total": 96,
            "completed": 96,
            "last_updated": "2021-09-22T13:45:45.575Z"
        },
        {
            "datasource": "business",
            "total": 1,
            "completed": 1,
            "last_updated": "2021-09-16T23:41:35.973Z"
        }
    ]
} 

/companies/{company}/connections/{connection}/status

Getting data status of a connection for a given company is done by issuing a GET request and specifying both the connection and company in the path.

Field Location Type Description
company Path string The ID of the company
connection Path string The ID of the connection to remove

Accounting

The following apps are currently supported

Bills

Following is the data specification for a bill that is extracted from accounting/POS OSPs

Retrieving the list of bills for a connection is done by querying the bills endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/bills \
    -H "Authorization: ${API_KEY}"

The response is an array of bills as seen below.

{
  "results": [
    {
      "data": {
        "transaction_outstanding_amount": 1026.13,
        "currency_rate": 0.589596,
        "transaction_date": "2021-01-22T00:00:00.000Z",
        "transaction_due_date": "2021-02-20T12:00:00.000Z",
        "transaction_status": "UNPAID",
        "transaction_reference": "00001482",
        "related_reference": "6df6db72-77d6-4505-8fb6-b4594e057855",
        "party_identifier": "806ecb77-eece-47ac-9dd5-6a1f208681c7",
        "transaction_currency": "NZD",
        "transaction_gross_value": 1026.13,
        "transaction_net_value": 1026.13,
        "line_items": [
          {
            "product_name": "Plate",
            "system_id": "e54a0375-a275-4224-b71b-71afacae7213",
            "item_identifier": "N/A",
            "item_category": "N/A",
            "item_type": "N/A",
            "item_net_unit_sale_value": 1017.645981,
            "item_net_unit_discount_value": 1017.645981,
            "item_unit_tax_value": 1017.645981,
            "item_price_list_reference": "N/A",
            "item_total_gross_value": 1017.65,
            "item_total_net_value": 1017.65,
            "item_total_tax_value": 1017.65
          },
          {
            "product_name": "Packaging",
            "system_id": "e1924f89-55db-475c-bd50-ed0873b6d047",
            "item_identifier": "N/A",
            "item_category": "N/A",
            "item_type": "N/A",
            "item_net_unit_sale_value": 8.480383,
            "item_net_unit_discount_value": 8.480383,
            "item_unit_tax_value": 8.480383,
            "item_price_list_reference": "N/A",
            "item_total_gross_value": 8.48,
            "item_total_net_value": 8.48,
            "item_total_tax_value": 8.48
          }
        ]
      },
      ...
    }
  ]
}


/companies/{company}/connections/{connection}/data/bills

The bills endpoint for a connection returns an array of bills. The data is the key for a bill.

Individual line items can be found for each bill under the line_items key.

Bill

Field Data Type Description
transaction_outstanding_amount number Total outstanding bill amount
currency_rate number Currency rate between the currency of the bill and the base currency of the business
transaction_date date Date on which the bill was issued
transaction_due_date date Date on which the bill is due
transaction_status string Status of the bill (Paid, Unpaid)
transaction_reference string Unique identifier of the bill on OSP's end
related_reference string Unique reference related to the transaction
party_identifier string Unique identifier for the third party
transaction_currency string Currency in which the bill was issued
transaction_gross_value number Total bill amount
transaction_net_value number Bill subtotal
tax_amount number Total applied tax amount
line_items LineItem[] An array of line items as defined below

Line Item

Field Data Type Description
product_name string Name of the product or service being sold
system_id string Unique identifier of the line item on 9Spokes' end
item_identifier string Unique identifier of the line item on the app's end
item_category string Account category under which the transaction item was originally listed
item_type string 'bill' when the osp is an accouting app and 'good-service' when the osp is a point of sale app
item_net_unit_sale_value number Net sale value per item
item_net_unit_discount_value number Net discount value per item
item_unit_tax_value number Tax value per item
item_price_list_reference string Reference to any pre-set discounting based upon specific price lists (specials, happy hour, etc.)
item_total_gross_value number Total gross value of the item (before tax)
item_total_net_value number Net value of the item (after tax)
item_total_tax_value number Total tax value applied to the item

Invoices

Following is the data specification for a invoice that is extracted from accounting OSPs

Retrieving the list of invoices for a connection is done by querying the invoices endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/sales \
    -H "Authorization: ${API_KEY}"

The response is an array of invoices as seen below.

{
  "results": [
    {
      "data": {
        "currency_rate": 1.0,
        "transaction_gross_value": 17765.0,
        "transaction_net_value": 17000.0,
        "transaction_tax_value": 765.0,
        "transaction_date": "2021-04-05T00:00:00.000Z",
        "transaction_due_date": "2021-05-05T00:00:00.000Z",
        "transaction_reference": "070",
        "transaction_currency": "NZD",
        "transaction_status": "PAID",
        "line_items": [
          {
            "product_name": "Samsung Galaxy S6 10.5* Tab",
            "item_category": "revenue-transaction",
            "item_type": "invoice",
            "item_quantity": 10,
            "item_identifier": "Samsung Galaxy S6 10.5* Tab",
            "item_net_unit_sale_value": 1700.0,
            "item_total_net_value": 16235.0,
            "item_total_tax_value": 765.0,
            "item_total_gross_value": 17000.0,
            "system_id": "132516"
          }
        ]
      }
    },
    ...
  ]

}

/companies/{company}/connections/{connection}/data/invoices

The invoices endpoint for a connection returns an array of invoices. The data is the key for an invoice.

Individual line items can be found for each invoice under the line_items key.

Invoice

Field Data Type Description
transaction_outstanding_amount number Total outstanding invoice amount
currency_rate number Currency rate between the currency of the invoice and the base currency of the business
transaction_date date Date on which the invoice was issued
transaction_due_date date Date on which the invoice is due
transaction_status string Status of the invoice (Paid, Unpaid)
transaction_reference string Unique identifier of the invoice on OSP's end
transaction_currency string Currency in which the invoice was issued
transaction_gross_value number Total invoice amount
transaction_net_value number invoice subtotal
line_items LineItem[] An array of line items as defined below

Line Item

Field Data Type Description
product_name string Name of the product or service being sold
system_id string Unique identifier of the line item on 9Spokes' end
item_identifier string Unique identifier of the line item on the app's end
item_category string Account category under which the transaction item was originally listed
item_type string 'invoice' when the osp is an accouting app and 'good-service' when the osp is a point of sale app
item_net_unit_sale_value number Net sale value per item
item_net_unit_discount_value number Net discount value per item
item_unit_tax_value number Tax value per item
item_price_list_reference string Reference to any pre-set discounting based upon specific price lists (specials, happy hour, etc.)
item_total_gross_value number Total gross value of the item (before tax)
item_total_net_value number Net value of the item (after tax)
item_total_tax_value number Total tax value applied to the item

Product

This is the specification for Product Items. It is in JSON formam. Following is the data specification for products as extracted from accounting apps

Retrieving the products data for a connection is done by querying the products endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/data/products \
    -H "Authorization: ${API_KEY}"

The response is an array of Product data as seen below.

{
  "results": [
    {
      "data": {
        "inventory_product_quantity": 70,
        "product_cost": 50,
        "product_cost_value": 3500,
        "product_group": "Gaming",
        "product_id": "7683bc1e9ad34b099220bdc895bbc2c4",
        "product_name": "S70 Mouse",
        "product_variant": ["white", "black"],
        "product_net_price": 70,
        "product_sale_value": 4900
      }
    },
    ...
  ]
}

/companies/{company}/connections/{connection}/data/products

Data

Below is the content of the data object used with product.

Field Data Type Description
product_name string The specific product name retrieved
product_id string Specific ID related to the product
product_group string Specific group related to the product
product_variant string[] Specific variant related to the product
product_cost number The unit cost of the product
product_net_price number The unit net price of the product
inventory_product_quantity number The units of product available for sale
product_cost_value number The total cost value of the product (product cost x quantity)
product_sale_value number The total sale value of the product (product net price x quantity)

Contacts

A contact is a person or organization that is associated with your business. Following is the data specification for contacts extracted from accounting/POS OSPs

Retrieving the list of contacts for a connection is done by querying the contacts endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/contacts \
    -H "Authorization: ${API_KEY}"

The response is an array of contacts as seen below.

{
    "results": [
        {
            "contact": {
                "id": "295c0eb6-7844-4ee7-a2ed-6c1a69fa9424",
                "company_name": "Lifestyle Design",
                "contact_name": "James",
                "email": "j.dg@example.com",
                "first_name": "James",
                "last_name": "De Grasse",
                "phone": "(021) 120 00000",
                "type": "customer and supplier",
                "addresses": [
                    {
                        "city": "Auckland",
                        "country": "NZ",
                        "line1": "12 Scott Road",
                        "line2": "Onehunga"
                    },
                    {
                        "city": "Auckland",
                        "country": "NZ",
                        "line1": "28 Esplanade Street",
                        "line2": "Papakura"
                    }
                ],
            }
        }
    ]
}

/companies/{company}/connections/{connection}/contacts

Contact

Below is the content of the contact object.

Field Data Type Description
type string The contact type, either:
  • customer
  • customer and supplier
id string The unique identifier for the contact in the platform
first_name string Name of the contact
last_name string Name of the contact
company_name string Website of the contact
phone string Phone number of the contact
email string Email address of the contact
website string Website of the contact
vatin string VAT number of the contact

address

Field Data Type Description
country string Country
city string City
line1 string Address, line 1
line2 string Address, line 2
postal_code string Postal code
type string Type of the address

Trial Balance

A timeline/trial balance is a list of all the general ledger accounts contained in the ledger of a business.

/companies/{company}/connections/{connection}/data/trial_balance


{
  "results": [
    {
      "balance_date": "2021-08-08T00:00:00Z",
      "data": [
        {
          "account_status": "ACTIVE",
          "account_type": "bank",
          "account_currency": "NZD",
          "account_category": "assets",
          "account_name": "Petty Cash",
          "value_type": "debit",
          "total_value": 261396.00,
          "account_identifier": "959af5f4-9925-44e8-b283-7ddf4b427238",
          "account_code": "1000"
        },
        {
          "account_status": "ACTIVE",
          "account_type": "sales",
          "account_currency": "NZD",
          "account_category": "revenue",
          "account_name": "Sales",
          "value_type": "credit",
          "total_value": 23000.0,
          "account_identifier": "859af5f4-9925-34e8-b283-7ddf4b427237",
          "account_code": "4000"
        },
        {
          "account_status": "ACTIVE",
          "account_type": "tax",
          "account_currency": "NZD",
          "account_category": "liability",
          "account_name": "gst",
          "value_type": "credit",
          "total_value": 1500.0,
          "account_identifier": "759af5f4-9925-44e8-b283-7ddf4b427236",
          "account_code": "2005"
        }
      ]
    },
    ...
  ]
}

Data Schema

Field Data Type Description
account_identifier string Account ID
account_name string Account name
account_code string The chart of account codes
account_type string The account type (bank, current, equity, fixed, overheads, payroll, sales, tax, term, current_accounts_receivable.current_account_payable)
account_category string The account category (assets, equity, expense, liability, revenue)
account_currency string Currency of the account
account_status string Whether the account is active or not
value_type string Debit/Credit
total_value number The value of the account

Business

This is the specification for the business of a user. It is in JSON format and the metadata allow the resolvers to identify the type of data required and the related fields to transform.

/companies/{company}/connections/{connection}/data/business

Field Description

Below is the schema definition for a business record

{
    "result": {
        "business": {
            "addresses": [
                {
                    "country": "New Zealand",
                    "line1": "AECOM House Level 5/8 Mahuhu Crescent",
                    "line2": "CBD Auckland",
                    "postal_code": "1010",
                    "type": "billing"
                }
            ],
            "currency": "NZD",
            "financial_year": {
                "end_day": 31,
                "end_month": 3
            },
            "id": "b1d9725d-43dd-47c9-87f9-d2f2a2bdbdd5",
            "name": "9SpokesTech",
            "registration_number": "187845566",
            "tax": {
                "id": "ceeb248e-9cc8-46b1-937a-b1fd2084e9bc",
                "name": "GST"
            },
            "view_id": "4471d27e06ac724b5dd676bee05854be"
        }
    }
}

Business

Below is the content of the business object.

Field Data Type Description
id string Business identifier
addresses []address An array of addresses as defined below
currency string Subscription state date
financial_year financial_year financial_year object
name string Business name
registration_number string Business registration number
tax tax tax object
view_id string Reference of the company selected from accounting platform

financial_year

Field Data Type Description
end_day number financial year end day
end_month number financial year end month

tax

Field Data Type Description
id string tax identifier
end_month string name of the tax

address

Field Data Type Description
country string country
line1 string address line 1
line2 string address line 2
postal_code string postal code
type string type of the address

Banking

Bank Accounts

A list of bank accounts from a connected app platform for the associated business. Following is the data specification for a bank account that is extracted from banking or accounting apps

Retrieving the list of bank accounts for a connection is done by querying the bank_accounts endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/bank_accounts \
    -H "Authorization: ${API_KEY}"

The response is an array of bank accounts as seen below.

{
    "results": [
        {
            "balance_date": "2020-11-02T00:00:00.000Z",
            "data": [
                {
                    "account_id": "59",                  
                    "account_name": "My Savings",
                    "account_active": true,
                    "account_balance": 10951677.31,
                    "account_currency": "GBP"
                },
                {
                    "account_id": "69",                
                    "account_name": "PayPal Funds Transfer Account",
                    "account_active": true,
                    "account_balance": 231232.90,
                    "account_currency": "GBP" 
                }
            ]
        },
        ...
    ]
}

/companies/{company}/connections/{connection}/data/bank_accounts

Data Schema

Field Data Type Description
balance_date date The date when the bank accounts were recorded
data array Array of accounts
account_id string The unique identifier for the account in the platform
account_name string Name of the bank account in the platform
account_active bool true or false if the account is active or not
account_balance number The total balance of the bank account as of balance_date

HR and Payroll

The following Apps are currently supported

Leaves

A leave is time-off requested to a company by an employee. Following is the data specification for a leave record that is extracted from HR/Payroll OSPs

Retrieving the list of leaves for a connection is done by querying the leaves endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/leaves \
    -H "Authorization: ${API_KEY}"

The response is an array of leaves as seen below.

{
  "results": [
    {
      "leave": {
        "id": "314117",
        "type": "SICK",
        "status": "PENDING",
        "start_date": "2021-01-15T00:00:00.000Z",
        "end_date": "2021-01-19T00:00:00.000Z",
        "application_url": "https://www.talenox.com/apps/leave/applications/314117",
        "employee_id": "176772",
        "employee_name": "Kia Solo",
        "dates": [
          "2021-01-15T00:00:00.000Z",
          "2021-01-16T00:00:00.000Z",
          "2021-01-17T00:00:00.000Z",
          "2021-01-18T00:00:00.000Z",
          "2021-01-19T00:00:00.000Z"
        ]
      }
    },
    {
      "leave": {
        "id": "252826",
        "type": "PAID",
        "status": "APPROVED",
        "start_date": "2020-07-31T00:00:00.000Z",
        "end_date": "2020-08-03T00:00:00.000Z",
        "application_url": "https://www.talenox.com/apps/leave/applications/252826",
        "employee_id": "176772",
        "employee_name": "Obigud Kenobee",
        "dates": [
          "2020-07-31T00:00:00.000Z",
          "2020-08-01T00:00:00.000Z",
          "2020-08-02T00:00:00.000Z",
          "2020-08-03T00:00:00.000Z"
        ]
      }
    }
  ]
}


/companies/{company}/connections/{connection}/leaves

Data Schema

Field Data Type Description
id string Unique identifier of the leave request in the platform
type string The leave type, either:
  • SICK
  • PAID
  • UNPAID
  • OTHER
status string The leave status, either:
  • PENDING
  • DECLINED
  • APPROVED
  • OTHER
start_date date Start date of the leave request
end_date date End date of the leave request
application_url string URL to the leave application in the platform
employee_id string Unique identifer of the employee who applied for the leave
employee_name string Name of the employee who applied for the leave
dates array of dates Dates of the leave request

Pay Run Summary

Summarized pay run of different periods. Following is the data specification for pay run summary as extracted from HR/Payroll OSPs

Retrieving pay run summary for a connection is done by querying the payRunSummary endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/payRunSummary \
    -H "Authorization: ${API_KEY}"

The response is an array of pay run summary as seen below.

{
  "results": [
    {
      "pay_run_summary": {
        "pay_period": "Semi-monthly",
        "start_date": "2019-10-14T00:00:00.000Z",
        "end_date": "2019-10-29T00:00:00.000Z",
        "hours": 120.0,
        "gross_pay": 7000.0
      }
    },
    {
      "pay_run_summary": {
        "pay_period": "Semi-monthly",
        "start": "2019-09-30T00:00:00.000Z",
        "end": "2019-10-13T00:00:00.000Z",
        "hours": 120.0,
        "gross_pay": 9000.0
      }
    }
  ]
}

/companies/{company}/connections/{connection}/payRunSummary

Data Schema

Field Data Type Description
pay_period string Recurring period over which employee time is recorded and paid
  • Weekly
  • Bi-weekly
  • Quarterly
  • Monthly
  • Semi-monthly
start_date date Start date of the pay period
end_date date End date of the pay period
hours number Total number of work hours recorded for that period
gross_pay number The amount of money paid to employees for that period

Staff Wages

Staff wages is the record of pay run categorized by employment type. Following is the data specification for staff wages as extracted from HR/Payroll OSPs

Retrieving staff wages for a connection is done by querying the staffWages endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/staffWages \
    -H "Authorization: ${API_KEY}"

The response is an array of staff wages as seen below.

{
  "results": [
    {
      "staff_wages": {
        "employment_type": "FULL-TIME",
        "gross_pay": 19000.0,
        "date": "2017-10-31T00:00:00.000Z"
      }
    },
    {
      "staff_wages": {
        "employment_type": "CONTRACTOR",
        "gross_pay": 2450.0,
        "date": "2017-10-31T00:00:00.000Z"
      }
    },
    {
      "staff_wages": {
        "employment_type": "PART-TIME",
        "gross_pay": 420.0,
        "date": "2017-10-31T00:00:00.000Z"
      }
    }
  ]
}


/companies/{company}/connections/{connection}/staffWages

Data Schema

Field Data Type Description
employment_type string Types of employment
  • FULL-TIME
  • PART-TIME
  • CONTRACTOR
  • INTERN
  • OTHER
gross_pay string The amount of money paid
date date Payment date

Point of sale

The following apps are currently supported

Products

This is the specification for Product Items. It is in JSON format and the metadata allow the resolvers to identify the type of data required and the related fields to transform. Following is the data specification for products as extracted from POS OSPs

Retrieving the products data for a connection is done by querying the products endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/products \
    -H "Authorization: ${API_KEY}"

The response is an array of Product data as seen below.

{
  "results": [
    { 
      "data": {
        "product_name": "Dining Chair",
        "product_id": "5287889d-c45b-4a65-9ef6-68494d4fdeb0",
        "product_group": "Furniture",
        "product_variant": ["white", "black"],
        "product_handle": "dining-chair",
        "product_sku": "142350",
        "created_at": "2018-11-04T21:24:23.873Z",
        "updated_at": "2020-11-03T21:24:23.906Z",
        "deleted_at": null,
        "product_cost": 100,
        "product_net_price": 280,
        "product_gross_price": 300,
        "inventory_product": true,
        "inventory_product_quantity": 3,
        "product_cost_value": 300,
        "product_sale_value": 840
      }
    }
    ...
  ]
}

/companies/{company}/connections/{connection}/data/products

Data Schema

Below is the content of the data object used with product.

Field DataType Description
product_name string The specific product name retrieved
product_id string Specific ID related to the product
product_group string Specific group related to the product
product_variant string[] Specific variant related to the product
product_handle string Specific handle related to the product
product_sku string SKU of the product
created_at date Original creation time of the product in the app
updated_at date Last modified time of the product in the app
deleted_at date Time of deletion of the product, if removed from the app
product_cost number The unit cost of the product
product_net_price number The unit net price of the product
product_gross_price number The unit gross price of the product
inventory_product boolean If the product has stock values, the inventory is tracked
inventory_product_quantity number The units of product available for sale
product_cost_value number The total cost value of the product (product cost x quantity)
product_sale_value number The total sale value of the product (product net price x quantity)

Sales

Following is the data specification for a sale that is extracted from POS OSPs

Retrieving the list of sales for a connection is done by querying the sales endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/sales \
    -H "Authorization: ${API_KEY}"

The response is an array of invoices as seen below.

{
  "results": [
    {
      "data": {
        "currency_rate": 1.0,
        "transaction_gross_value": 3000.0,
        "transaction_net_value": 2800.0,
        "transaction_tax_value": 200.0,
        "transaction_date": "2021-04-05T00:00:00.000Z",
        "transaction_due_date": "2021-05-05T00:00:00.000Z",
        "transaction_reference": "070",
        "transaction_currency": "NZD",
        "transaction_status": "PAID",
        "line_items": [
          {
            "product_name": "Dining Chair",
            "item_category": "sales-revenue",
            "item_type": "goods-service",
            "item_quantity": 10,
            "item_identifier": "Dining Chair 1029",
            "item_net_unit_sale_value": 280.0,
            "item_total_net_value": 2800.0,
            "item_total_tax_value": 200.0,
            "item_total_gross_value": 3000.0,
            "system_id": "5287889d-c45b-4a65-9ef6-68494d4fdeb0"
          }
        ]
      }
    },
    ...
  ]

}

/companies/{company}/connections/{connection}/data/sales

The sales endpoint for a connection returns an array of sales. The data is the key for a sale.

Individual line items can be found for each sale under the line_items key.

Invoice

Field Data Type Description
transaction_outstanding_amount number Total outstanding invoice amount
currency_rate number Currency rate between the currency of the invoice and the base currency of the business
transaction_date date Date on which the invoice was issued
transaction_due_date date Date on which the invoice is due
transaction_status string Status of the invoice (Paid, Unpaid)
transaction_reference string Unique identifier of the invoice on OSP's end
transaction_currency string Currency in which the invoice was issued
transaction_gross_value number Total invoice amount
transaction_net_value number invoice subtotal
line_items LineItem[] An array of line items as defined below

Line Item

Field Data Type Description
product_name string Name of the product or service being sold
system_id string Unique identifier of the line item on 9Spokes' end
item_identifier string Unique identifier of the line item on the app's end
item_category string Account category under which the transaction item was originally listed
item_type string 'invoice' when the osp is an accouting app and 'good-service' when the osp is a point of sale app
item_net_unit_sale_value number Net sale value per item
item_net_unit_discount_value number Net discount value per item
item_unit_tax_value number Tax value per item
item_price_list_reference string Reference to any pre-set discounting based upon specific price lists (specials, happy hour, etc.)
item_total_gross_value number Total gross value of the item (before tax)
item_total_net_value number Net value of the item (after tax)
item_total_tax_value number Total tax value applied to the item

Social Marketing

The following apps are currently supported

Social Marketing

Social Marketing data is gathered from apps like Facebook, LinkedIn and Instagram. Use this data to analyze how your social media campaigns are performing

{
  "data": [
    {
      "views_to_actions": 3.0,
      "page_fans": 50.0,
      "page_followers": 20.0,
      "overall_impressions": 23.0,
      "engagement_overviews": 25.0
    }
  ]
}

Data Schema

Field Data Type Description
views_to_actions number Number of user views that resulted in an action
page_fans number Number of page fans
page_followers number Number of page followers
overall_impressions number Number of overall impressions
engagement_overviews number Number of engagements overall

Email Marketing

The following apps are currently supported

Campaigns

Campaign data simplifies the analysis of email campaign performance. Following is the data specification for Campaign as extracted from Email Marketing OSPs

Retrieving the Campaigns data for a connection is done by querying the campaigns endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/campaigns \
    -H "Authorization: ${API_KEY}"

The response is an array of campaign data as seen below.

{
  "results": [
    {
        "campaign_id" : "f5c755c5-2352-4ee0-8c21-9acef700b2ca",
        "created_at" : "2021-04-14T22:51:58.000Z",
        "updated_at" : "2021-04-15T08:36:09.000Z",
        "sent_time" : "2021-04-15T08:36:10.000Z",
        "status" : "Done",
        "name" : "New Test Campaign",
        "type" : "NEWSLETTER",
        "campaign_report" : {
            "sends" : 22,
            "abuse_reports":0,
            "opens" : 22,
            "bounces" : 4,
            "clicks" : 3,
            "deliveries" : 2,
            "deliveries_unopened" : 2
        }
    },
    {
        "campaign_id" : "3a9d454f-b723-415e-a302-9dcc8fded602",
        "created_at" : "2021-04-14T22:46:43.000Z",
        "updated_at" : "2021-04-14T22:47:28.000Z",
        "sent_time" : "2021-04-14T22:47:29.000Z",
        "status" : "Done",
        "name" : "Test Campaign 15/04",
        "type" : "NEWSLETTER",
        "campaign_report" : {
            "opens" : 22,
            "abuse_reports":0,
            "bounces" : 4,
            "clicks" : 3,
            "sends" : 2,
            "deliveries" : 2,
            "deliveries_unopened" : 2
        }
    }
  ]
}

/companies/{company}/connections/{connection}/data/campaigns

Data Schema

Field Data Type Description
campaign_id string Campaign ID (App-wide unique ID)
created_at date Campaign creation date
updated_at date Campaign last updated date
sent_time date Campaign sent time
status string Campaign status
name string Campaign name
type string Campaign type
campaign_report object Report on the campaign
opens int Total number of opens
clicks int Total number of clicks
sends int Total number of sends
abuse_reports int Total number of abuse_reports
bounces int Total number of bounces
deliveries int Total number of deliveries
deliveries_unopened int Total number of deliveries_unopened

Growth history

Growth history data is the analysis of month-by-month growth activity for list/audience. Following is the data specification for growth history as extracted from Email Marketing OSPs

Retrieving the growth history data for a connection is done by querying the growth_history endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/data/growth_history \
    -H "Authorization: ${API_KEY}"

The response is an array of Email Marketing data as seen below.

{
  "results": [
    {
      "list_id": "69b1d36343",
      "list_name": "List 1",
      "list_date_created": "2017-05-17T04:47:45.000Z",
      "growth_history": [
        {
          "reconfirm": 0.0,
          "deleted": 0.0,
          "existing": 0.0,
          "imports": 0.0,
          "subscribed": 10.0,
          "cleaned": 1.0,
          "pending": 0.0,
          "transactional": 0.0,
          "month": "2021-08-10T00:00:00.000Z",
          "optins": 0.0,
          "unsubscribed": 0.0
        },
        {
          "reconfirm": 0.0,
          "deleted": 0.0,
          "existing": 0.0,
          "imports": 0.0,
          "subscribed": 10.0,
          "cleaned": 1.0,
          "pending": 0.0,
          "transactional": 0.0,
          "month": "2021-07-10T00:00:00.000Z",
          "optins": 0.0,
          "unsubscribed": 0.0
        }
        ...
      ]
    },
    ...
  ]
}

/companies/{company}/connections/{connection}/data/growth_history

Data Schema

Field Data Type Description
list_id string List ID (App-wide unique ID)
list_name string List name
list_date_created string List creation date
growth_history array Array of growth_history object
reconfirm float Number of reconfirm
deleted float Number of deleted
existing float Number of existing
imports float Number of imports
subscribed float Number of subscribed
cleaned float Number of cleaned
pending float Number of pending
transactional float Number of transactional
month date record's month
optins float Number of optins
unsubscribed float Number of unsubscribed

Web Analytics

The following apps are currently supported

Web Analytics

The data in this section allows you to anaylze user behavior around your website pages and gain insights on the revenue generated by different ad sources. Following is the data specification for web analytics as extracted from web analytics OSPs

Retrieving the web analytics data for a connection is done by querying the webAnalytics endpoint for that connection

$ curl https://${API_ROOT}/companies/69894a02-9c03-40ac-a06a-ee6e4b38c6fb/connections/52684382-abff-45fa-a3f2-ced175adfe61/webAnalytics \
    -H "Authorization: ${API_KEY}"

The response is an array of web analytics data as seen below.

{
  "data": [
    {
      "ads_revenue": "$45,000.00",
      "bounce_rate": "33%",
      "exit_rate": "50%",
      "avg_time_on_page": "3m2s",
      "total_page_view": "135",
      "source_of_visitor": "Facebook"
    }
  ]
}

/companies/{company}/connections/{connection}/webAnalytics

Data Schema

Field Data Type Description
ads_revenue string Total revenue generated by an ad for the given time duration
bounce_rate string Percentage of single-page sessions out of the total sessions on a site
exit_rate string Percentage of the number of exists out of the number of page views for a page
avg_time_on_page string Time spent by the users on a page, averaged over the given time duration
total_page_view string Total number of views on a page over the given time duration
source_of_visitor string Advertisement source