How to Make Your First Call with upSWOT API

This tutorial shows an example of how to get your first response with normalized accounting data.
You're in the right place if you've never worked with the Business Health API before. Welcome, let's get started!

The process takes three simple steps:

Request an access token using your account credentials.
Generate a service connection link.
Use the Business Health API to retrieve SMB data once the service is connected.

Prerequisites

Before you begin, make sure the following prerequisite is met:

You have valid Business Health API credentials (email and password).

Step 1: Get JWT Token

To request the access token, use your account's email and password.

Send a POST request to the Get Token endpoint.
Set the Content-Type header to application/json.
Add an HTTP body containing the email and password.

curl --request POST \
     --url https://app.upswot.com/admin/api/v1/auth/login \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "password": "string"
}
'

The response returns an access token.

{
    "access_token": "eyJhb...",
    "username": "Test dev account",
    "redirect_url": "/dashboard",
    "refreshToken": "j8KuCVwh...",
    "twoStepVerify": false
}

Use this token for all the following API calls.

Step 2: Generate Connection Link

📘
Skip this step if the user has already connected the business app.

This example connects a QuickBooks account to the company. According to the API reference, the endpoint needs the business's company ID and the QuickBooks service ID.

To create the service connection link, call the Service connection link endpoint with your companyId and QuickBooks serviceId. Your API call must include the access token you just generated, in the Authorization header:

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/company/{companyId}/data-connection/{serviceId}/link \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc.....'

Note:

To obtain companyId, use the All companies endpoint.

To get the list of available services for connection and their IDs, use the All services endpoint.

The API returns the following JSON response:

{
    "link": "https://app.upswot.com/admin/api/Data/Auth?serviceId={serviceId}&instanceId={instanceId}&accountId={companyId}"
}

This connection link leads to the QuickBooks auth window.

Step 3: Get Business Accounts Data

Once the SMB owner connects their QuickBooks account, you're ready to get all normalized data. Use the Accounts by service endpoint to get all QuickBooks accounts for a given user.

📘
How do you know when the data is ready to use?
You can track the status of each connection related to the company in two ways:

Call All connection statuses and wait for "Structured" status once normalized data is obtained.

Subscribe to the "NormalizedData" event to track the normalized data call.

Learn more about data connection statuses.

Use companyId and QuickBooks serviceId in the URI:

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/{companyId}/accountancy/accounts/{serviceId} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc...'

If performed correctly, the API returns the following JSON response:

{
    "data": [
        {
            "serviceId": "2ce011f0-5f6c-11e9-b797-080027653e25",
            "serviceName": "QuickBooks",
            "lastUpdatedOn": "2023-08-14T17:48:11.918339",
            "id": "6d71f433-cc13-424a-9584-723f53885131",
            "origId": "57",
            "number": "",
            "name": "Workers Compensation",
            "currency": "USD",
            "description": "",
            "classApp": "Expense",
            "classSystem": "Expense",
            "typeApp": "Expense",
            "typeSystem": "Expenses",
            "subTypeApp": "Insurance",
            "subTypeSystem": "Insurance",
            "statusApp": "ACTIVE",
            "statusSystem": "ACTIVE"
        },
        {
            "serviceId": "2ce011f0-5f6c-11e9-b797-080027653e25",
            "serviceName": "QuickBooks",
            "lastUpdatedOn": "2023-08-14T17:48:11.918339",
            "id": "4d9ee7e8-0e56-4f50-8159-0fad3aac54d8",
            "origId": "42",
            "number": "",
            "name": "Visa",
            "currency": "USD",
            "description": "",
            "classApp": "Liability",
            "classSystem": "Liability",
            "typeApp": "Credit Card",
            "typeSystem": "CurrentLiabilities",
            "subTypeApp": "CreditCard",
            "subTypeSystem": "CreditCards",
            "statusApp": "ACTIVE",
            "statusSystem": "ACTIVE"
        },
        {
            "serviceId": "2ce011f0-5f6c-11e9-b797-080027653e25",
            "serviceName": "QuickBooks",
            "lastUpdatedOn": "2023-08-14T17:48:11.918339",
            "id": "32265876-b797-455a-851a-75c6b68d202b",
            "origId": "24",
            "number": "",
            "name": "Utilities",
            "currency": "USD",
            "description": "",
            "classApp": "Expense",
            "classSystem": "Expense",
            "typeApp": "Expense",
            "typeSystem": "Expenses",
            "subTypeApp": "Utilities",
            "subTypeSystem": "Utilities",
            "statusApp": "ACTIVE",
            "statusSystem": "ACTIVE"
        }
      ],
     "pagination": {
        "pageNumber": 1,
        "pageSize": 100,
        "count":3
    }
}

🎉 Congratulations! You received your first normalized data using the Business Health API.