Request Dev Account
API Reference

First Call

Make your first REST API call in less than 3 minutes

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

The process requires taking these simple steps:

  1. Request an access token using your dev account credentials.
  2. Generate service connection link.
  3. Use upSWOT API to retrieve SMB data once the service is connected.

Prerequisites

Before you begin, make sure the following prerequisites are met:

  • Your upSWOT sandbox developer account is set up. You can request a sandbox developer account for free. Learn more about getting one.

Step 1. Get JWT Token

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

  • Send a POST request to the Get Token endpoint.
  • Set the Content-Type header to the application/json value.
  • Add an HTTP body containing the email and password.
curl --request POST \
     --url https://sandbox.upswot.com/admin/api/v1/auth/login \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "password": "string"
}
'

The response will return an access token. 

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

You can use the obtained Token through all the following API calls.

Step 2. Generate Connection Link

📘

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

We want to connect all QuickBooks accounts to the company for this example. According to the API Reference, the endpoint needs the business's company ID and the QuickBooks Service ID.

To create the service connection link, by calling the Service connection link endpoint, use your companyId and Quickbooks serviceId to generate the link. Your API call must include the access token we have just generated using the Authorization header as follows:

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

Note:

To obtain companyId use All companies endpoint.

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

API will return the following JSON response. 

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

You will receive the connection link leading to the Quickbooks auth window.

Step 3. Get Business Accounts Data

When the SMB owner connects their Quickbooks account, we are ready to get all normalized data. Let's use the Accounts by service endpoint to get all Quickbooks accounts for a given user.

📘

How do we understand when the data is ready to be used?

You can track the status of each connection related to the company, the following ways:

  1. Call GET All connection statuses and wait for "Structured" status if normalized data is obtained.
  2. 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://sandbox.upswot.com/admin/api/v1/normalized-data/{companyId}/accountancy/accounts/{serviceId} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc...'

If performed correctly, the API will return 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 upSWOT API.