Skip to content

Latest commit

 

History

History
238 lines (184 loc) · 7.4 KB

api.md

File metadata and controls

238 lines (184 loc) · 7.4 KB
Raw

API

Dext Precision offers a RESTful API to extract basic data contained within your Precision account. If you would like to use the API, we would recommend that your team get in touch.

Getting Started

The current version of the API lives at: https://api.xavier-analytics.com/

The easiest way to start using our API is by finding an HTTP client online. We would recommend using Postman, or Paw as they are ready-to-use, free tools.

In our demo we are going to use Postman.

Endpoints Summary

| Endpoint | What it does | | ------------- |:-------------:| -----| | /clients | Returns a list of Clients| | /clients/{clientId} | Returns details of a specific Client| | /clients/{clientId}/activity-stats | Returns Activity Stats metrics for a specific Client|

Authentication

In order to get data out, you must pass an authorization token in the request header:

Request Header: Authorization: Bearer <your token>

To generate a token please use the following instructions:

In Precision head to "Your Settings" and under the API tab generate your token.

Generate token

::: warning Store the token securely and do not share it with anyone else! :::

For example, to use your token in Postman, select bearer token as your authentication method and copy your given token into the correct field. See below:

Add token

Rate Limits

A rate limit restricts the number of API requests a consumer can make within a given time period. If this limit is exceeded the consumer will be throttled and API requests will fail.

Precision Rate Limits are set to 60 requests / minute.

If you exceed your rate limit allowance your request will be rejected. An HTTP 429 (Too Many Requests) response will be returned.

Precision returns rate limit details in the header of API responses to allow consumers to monitor their API usage.

Example response header: | Key | Value | | ------------- |:-------------:| -----| | Date | Thu, 30 Jan 2020 16:27:15 GMT | | Content-Type | application/json| | Connection | keep-alive| | Server | cloudflare| | X-RateLimit-Limit | 60 | | X-RateLimit-Remaining | 42 |

Response Codes

200 - OK

A 200 status code indicates that the request was accepted and processed successfully.

404 - Not found

A 404 error status code indicates that the API can't map the requested URI to a resource.

429 - Too many requests

A 429 error status code is returned when an API consumer hits Precision's rate limits.

500 - Internal Server Error

A 500 error status code is a generic API server-side error response. Please contact our support team if this persists.

API Endpoints

GET /clients

The /clients endpoint returns a list of all Precision clients that the given authentication token has access to, in a summarised format.

Request: https://api.xavier-analytics.com/clients

Response Content Type: application/JSON

Response Model:

[
    {
        "id": "string",
        "name": "string",
        "practiceCode": "string",
        "providerId": "string",
        "healthScore": integer,
        "alertLevel": "string"
    }
]

Example value:

GET-Clients-Response

GET /clients/{clientId}

The /clients/{clientId} endpoint returns a detailed set of information about a particular client identified by the clientId, including some calculated metrics.

Request: https://api.xavier-analytics.com/clients/{clientId}

Response Content Type: application/JSON

Response Model:

{
    "id": "string",
    "name": "string",
    "providerId": "string",
    "practiceCode": "string",
    "organisationType": "string",
    "companyNumber": "string",
    "healthScore": integer,
    "alertLevel": "string",
    "hmrcStatus": "string",
    "yearEnd": "string",
    "vatDetails": {
        "scheme": "string",
        "number": "string",
        "reportingCycle": "string",
        "periodStart": "string",
        "periodEnd": "string"
    },
    "metrics": {
        "debtorBalance": float,
        "avgDebtorDays": integer,
        "oneDayImpact": integer,
    },
    "bankReconciliation" : {
        "bankAccounts": integer,
        "manualFeeds": integer
    }
}

Example value:

GET-Clients/{clientId}-Response

GET /clients/{clientId}/activity-stats

The /clients/{clientId}/activity-stats endpoint returns the rolling annual and monthly-average Activity Stats for a particular client, identified by the clientId.

Request: https://api.xavier-analytics.com/clients/{clientId}/activity-stats

Response Content Type: application/JSON

Response Model:

{
    "annual": {
        "start": "string",
        "end": "string",
        "turnover": float,
        "salesCount": integer,
        "billsCount": integer,
        "creditsCount": integer,
        "manualJournalsCount": integer,
        "bankTransactionsCount": integer,
        "totalCount": integer,
        "turnoverChangeYoY": integer,
        "salesChangeYoY": integer,
        "billsChangeYoY": integer,
        "creditsChangeYoY": integer,
        "manualJournalsChangeYoY": integer,
        "bankTransactionsChangeYoY": integer,
        "totalChangeYoY": integer
    },
    "monthlyAverage": {
        "start": "string",
        "end": "string",
        "turnover": float,
        "salesCount": integer,
        "billsCount": integer,
        "creditsCount": integer,
        "manualJournalsCount": integer,
        "bankTransactionsCount": integer,
        "totalCount": integer,
        "turnoverChangeYoY": integer,
        "salesChangeYoY": integer,
        "billsChangeYoY": integer,
        "creditsChangeYoY": integer,
        "manualJournalsChangeYoY": integer,
        "bankTransactionsChangeYoY": integer,
        "totalChangeYoY": integer
    },
    "quarterlyAverage": {
        "start": "string",
        "end": "string",
        "turnover": float,
        "salesCount": integer,
        "billsCount": integer,
        "creditsCount": integer,
        "manualJournalsCount": integer,
        "bankTransactionsCount": integer,
        "totalCount": integer,
        "turnoverChangeMoM": integer,
        "salesChangeMoM": integer,
        "billsChangeMoM": integer,
        "creditsChangeMoM": integer,
        "manualJournalsChangeMoM": integer,
        "bankTransactionsChangeMoM": integer,
        "totalChangeMoM": integer,
        "turnoverChangeYoY": integer,
        "salesChangeYoY": integer,
        "billsChangeYoY": integer,
        "creditsChangeYoY": integer,
        "manualJournalsChangeYoY": integer,
        "bankTransactionsChangeYoY": integer,
        "totalChangeYoY": integer
    }
}

Example value:

GET-Clients/{clientId}/activity-stats-Response