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": 50,
"count": 3,
"data": [
{
"id": "de61da52-7b67-11eb-90e4-0242ac120006",
"isEnabled": true,
"logoUrl": "https://sandbox.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=de61da52-7b67-11eb-90e4-0242ac120006",
"name": "Bank Aggregator",
"title": "Connect Your Bank",
"parentId": null,
"parentName": null,
"description": "{\"en-US\": \"Data aggregation and data analytics platform powering dynamic, cloud-based innovation for digital financial services.\"}",
"categoryId": "22afb716-4814-4fad-a685-a43fa2694266",
"category": "Banking",
"supportedEntities": [
"Transactions",
"Accounts"
]
},
{
"id": "2ce0167e-5f6c-11e9-b797-080027653e25",
"isEnabled": true,
"logoUrl": "https://sandbox.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=2ce0167e-5f6c-11e9-b797-080027653e25",
"name": "Xero",
"title": "Xero",
"parentId": null,
"parentName": null,
"description": "{\"en-US\": \"Xero online accounting software for businesses connects to banks, accountants, bookkeepers, and other business apps.\"}",
"categoryId": "2cc07dc1-5f6c-11e9-b797-080027653e25",
"category": "Accountancy",
"supportedEntities": [
"ProfitAndLoss Cash",
"Balance Sheet Cash",
"Contacts",
"Company Info",
"Employees",
"Invoices",
"Bills",
"Credit Notes",
"Documents",
"Recurring documents",
"Payments",
"Items",
"Accounts",
"Transactions",
"Balance Sheet Accrual",
"ProfitAndLoss Accrual",
"Taxes"
]
},
{
"id": "09ef0996-278a-416a-838c-80599276a97e",
"isEnabled": true,
"logoUrl": "https://sandbox.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=09ef0996-278a-416a-838c-80599276a97e",
"name": "Ebay",
"title": "Ebay",
"parentId": null,
"parentName": null,
"description": "{\"en-US\": \"eBay is a global e-commerce platform that eases sales between consumers and businesses via its website.\"}",
"categoryId": "2cc08e47-5f6c-11e9-b797-080027653e25",
"category": "eCommerce",
"supportedEntities": [
"Products",
"Orders",
"Companies Info",
"Marketing events",
"Customers",
"Refunds",
"Transactions"
]
}
]
}
If
"isEnabled": falsethe servise is not ready to be used in the system.Use
"supportedEntities"array to understand normalized entities 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": "[email protected]",
"IssuedAs": "Manual",
"ModifiedOn": "2023-11-11T20:12:53.419897"
},
"Signature":
"00dba385e120d0c221cf372077a5f55f371a0bd403f1b4b97aa5dd49886909d4"
}