Several concepts and terms are used throughout this documentation for our product. Let's check the upSWOT core concepts!

Company

In upSWOT, the company entity represents an SMB who shares access to their business data. Each company can have multiple data connections to different data sources (services), such as Quickbooks for accounting data, external bank accounts, or Shopify for E-commerce data.

Companies are uniquely identified by their company ID, denoted by companyId.

When you create a company, you need to specify a company name, and the unique ID will be automatically generated for that company. You can also specify additional company information. Learn more.

🚧
The maximum length for the company name is 200 symbols.

Company API

Use these Base API endpoints to manage company entities:

Get all companies - GET /normalized-data/companies
Create a new company - POST normalized-data/company
Update existing company information - PUT normalized-data/companies/{companyId}

Service

A service represents a third-party data source to which you can connect a company (using a data connection) to access the company's business data.

You can connect the company's business accounts of various services, such as accounting, CRM, marketing, payroll, e-commerce, and banking platforms, as nearly every business app that SMBs use is a service where data can be retrieved through the upSWOT API.

Each service has its unique identifierserviceId used to connect and get business data based on a specific third-party app.

Service API

To receive all available services with additional information, use the List services endpoint.

Here is the response example:

{
    "pageNumber": 1,
    "pageSize": 500,
    "count": 99,
    "data": [
        {
            "id": "dafef06f-69bb-4dc5-a88b-6ae8250622ab",
            "isEnabled": true,
            "logoUrl": "https://app.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=dafef06f-69bb-4dc5-a88b-6ae8250622ab",
            "name": "Zoom",
            "title": "Zoom",
            "parentId": null,
            "parentName": null,
            "description": "Zoom is a communications platform that allows users to connect with video, audio, phone, and chat.",
            "categoryId": "870a9b8c-7065-4b3d-8ec4-a07f8babade3",
            "category": "Video Conferencing",
            "supportedEntities": {
                "get": [],
                "post": [
                    {
                        "title": "Meetings",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meetings/dafef06f-69bb-4dc5-a88b-6ae8250622ab",
                        "description": "Create Zoom meeting",
                        "id": "68d1af41-f832-11ef-8840-0242ac120005"
                    }
                ],
                "put": [
                    {
                        "title": "Meetings",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meetings/dafef06f-69bb-4dc5-a88b-6ae8250622ab",
                        "description": "Update Zoom meeting",
                        "id": "68d1afd2-f832-11ef-8840-0242ac120005"
                    }
                ],
                "raw": [
                    {
                        "title": "User",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/user/dafef06f-69bb-4dc5-a88b-6ae8250622ab/raw",
                        "description": "Get user raw data",
                        "id": "8196fa10-ea1d-11ef-8840-0242ac120005"
                    },
                    {
                        "title": "Meetings",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meetings/dafef06f-69bb-4dc5-a88b-6ae8250622ab/raw/{meetingId}",
                        "description": "Get meeting details",
                        "id": "8196fa8f-ea1d-11ef-8840-0242ac120005"
                    },
                    {
                        "title": "Meetings",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meetings/dafef06f-69bb-4dc5-a88b-6ae8250622ab/raw",
                        "description": "Get meetings raw data",
                        "id": "8196faef-ea1d-11ef-8840-0242ac120005"
                    },
                    {
                        "title": "Meeting Participants",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meeting-participants/dafef06f-69bb-4dc5-a88b-6ae8250622ab/raw/{meetingId}",
                        "description": "Get past meeting participants",
                        "id": "8196fb52-ea1d-11ef-8840-0242ac120005"
                    },
                    {
                        "title": "Meeting Recordings",
                        "uri": "/api/v1/normalized-data/{companyId}/vc/meeting-recordings/dafef06f-69bb-4dc5-a88b-6ae8250622ab/raw/{meetingId}",
                        "description": "Get meeting recordings",
                        "id": "8196fc42-ea1d-11ef-8840-0242ac120005"
                    }
                ]
            }
        },
        {
            "id": "2ce0167e-5f6c-11e9-b797-080027653e25",
            "isEnabled": false,
            "logoUrl": "https://app.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=2ce0167e-5f6c-11e9-b797-080027653e25",
            "name": "Xero",
            "title": "Xero",
            "parentId": null,
            "parentName": null,
            "description": "Online accounting software offering invoicing, bank reconciliation, and financial reporting for small businesses.",
            "categoryId": "2cc07dc1-5f6c-11e9-b797-080027653e25",
            "category": "Accountancy",
            "supportedEntities": {
                "get": [
                    {
                        "title": "ProfitAndLoss Cash",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/profit-and-loss-cash/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company profitandloss cash",
                        "id": "8c0d8734-35c7-11ee-8010-0242ac1e0015"
                    },
                    {
                        "title": "Balance Sheet Cash",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/balance-sheet-cash/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company balance sheet cash",
                        "id": "8c0dc448-35c7-11ee-8010-0242ac1e0015"
                    },
                    {
                        "title": "Contacts",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/contacts/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company contacts",
                        "id": "95391fc9-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Company Info",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/company-info/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company company info",
                        "id": "95392c67-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Employees",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/employees/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company employees",
                        "id": "95392db3-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Invoices",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/invoices/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company invoices",
                        "id": "95392e52-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Bills",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/bills/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company bills",
                        "id": "95392ef0-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Credit Notes",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/credit-notes/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company credit notes",
                        "id": "95392f73-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Documents",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/documents/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company documents",
                        "id": "95393050-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Recurring documents",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/recurring-documents/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company recurring documents",
                        "id": "953930d7-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Payments",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/payments/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company payments",
                        "id": "95393161-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Items",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/items/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company items",
                        "id": "953931e0-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Accounts",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/accounts/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company accounts",
                        "id": "95393275-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Transactions",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/transactions/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company transactions",
                        "id": "9539330e-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Balance Sheet Accrual",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/balance-sheet-accrual/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company balance sheet accrual",
                        "id": "953933a2-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "ProfitAndLoss Accrual",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/profit-and-loss-accrual/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company profitandloss accrual",
                        "id": "95393573-f97c-11ed-8f57-0242ac1e001b"
                    },
                    {
                        "title": "Taxes",
                        "uri": "/api/v1/normalized-data/{companyId}/accountancy/taxes/2ce0167e-5f6c-11e9-b797-080027653e25",
                        "description": "Get all company taxes",
                        "id": "9539365b-f97c-11ed-8f57-0242ac1e001b"
                    }
                ],
                "post": [],
                "put": [],
                "raw": []
            }
        }
    ]
}

📘
If"isEnabled": falsethe servise is not ready to be used in the system.
Use"supportedEntities"array to understand entities/actions offered by a given service.

Data Connection

A data connection entity shows the company's connection to the data source and allows you to pull data from that source. Using upSWOT API, you can check the list of available data connections, create new ones, and monitor the status of available connections. One company can have multiple data connections with multiple services.

Data connection tracking

upSWOT API provides two main ways how you can track the service connections process:

API driven: Use track status to get the list of company data connection statuses for all connected services.

Here is the response example:

{
    "pageNumber": 1,
    "pageSize": 100,
    "count": 2,
    "data": [
        {
            "serviceName": "Xero",
            "serviceId": "2ce0167e-5f6c-11e9-b797-080027653e25",
            "statusName": "AuthorizationTimedOut",
            "statusCode": 20,
            "lastUpdatedOn": "2023-05-09T11:30:46.191007",
            "updateScheduledOn": "2023-03-10T14:21:30"
        },
        {
            "serviceName": "Shopify",
            "serviceId": "2cec6431-5f6c-11e9-b797-080027653e25",
            "statusName": "Synced",
            "statusCode": 19,
            "lastUpdatedOn": "2023-05-09T11:20:53.430184",
            "updateScheduledOn": "2023-05-10T11:20:53"
        }
    ]
}

Webhook tracking: Subscribe for webhook (Example: NormalizedData) Events to be notified about specific actions to be received at your callback URL. The webhook payload contains metadata, event data, and signature.

Check out the payload example:

 {
 "Class": "DataConnection",
 "MessageType": "NormalizedData",
 "Identifier": "NormalizedData.f8e75a2b-4364-42f5-b52e-3e6505309196",
 "Data": {
 "SessionShareId": "f8e75a2b-4364-42f5-b52e-3e6505309196",
 "CompanyId": "93e05dd4-6b87-4793-8975-38b81f5a1db6",
 "AccountExternalId": null,
 "ApplicationId": null,
 "ServiceId": "2cec6431-5f6c-11e9-b797-080027653e25",
 "ServiceName": "Shopify",
 "CategoryName": "eCommerce",
 "CategoryId": "2cc08e47-5f6c-11e9-b797-080027653e25",
 "Email": "example@upswot.com",
 "IssuedAs": "Manual",
 "ModifiedOn": "2023-11-11T20:12:53.419897"
 },
 "Signature":
"00dba385e120d0c221cf372077a5f55f371a0bd403f1b4b97aa5dd49886909d4"
 }