This page covers the core concepts and terms used throughout this documentation.
Company
In Business Health, the company entity represents an SMB that shares access to its 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 a unique ID is generated automatically 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 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 that a company can connect to (using a data connection) to access its business data.
You can connect a company's accounts across various services — accounting, CRM, marketing, payroll, e-commerce, and banking platforms among them. Nearly every business app an SMB uses is available as a service, with its data retrievable through the Business Health API.
Each service has its own unique identifier, serviceId, 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": false, the service is not ready to be used in the system.Use the
supportedEntitiesarray to understand which entities/actions a given service offers.
Data Connection
A data connection entity represents the company's connection to a data source, and allows you to pull data from that source. Using the Business Health API, you can check the list of available data connections, create new ones, and monitor the status of existing connections. One company can have multiple data connections across multiple services.
Data Connection Tracking
The Business Health API provides two main ways to track the service connection 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 events (example:
NormalizedData) to be notified about specific actions at your callback URL. The webhook payload contains metadata, event data, and a 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"
}