API Documentation (1.0.0)

Kashoo API Documentation (1.0.0)

Download OpenAPI specification:Download

API documentation for the Kashoo platform.

Introduction

The API reference lists all available endpoints for products Kashoo Cloud Accounting and TrulySmall Accounting. The endpoints are divided topically and have references on the product to make it easier for you to navigate through the docs.

Getting Started

A Kashoo or TrulySmall user account is needed to use the api. The quickest way to get started is to sign up for a free trial with one of our applications. This will create an account for you, along with a user and a business. You can then use your credentials to obtain an authentication token and start using the api.

The application is centered around businesses, one of which will be created for you when you sign up for an account. Most endpoints accept a business id to identify who the operation is for. For example, a business will have its own contacts, taxes, transactions, accounts, and so on.

To allow for multi-user businesses, a user account is also assigned a user id. The user id can be associated with more than one business. The authentication token will only allow access to the business data for which the user has been granted access to. The user id is also used for user-specific operations such as purging a user account.

Subscriptions are centered around businesses. Each business must pay for its own subscription. A user can access any businesses that they have access to as long as the business is on an active subscription. When developing an api client, you may ask to be put on a free subscription plan so that your business and its data stay accessible over the course of your development.

Product identification markers

This API supports two of our products: Kashoo Cloud Accounting and TrulySmall Accounting. You can sign up for either application at https://kashoo.com/. The API for the two products is essentially the same with a couple important differences:

  • TSA supports opening balances for accounts while Kashoo has to do this with adjustments.
  • The tax system is different between the two products. The TSA tax system is more structured and constrained.
  • TSA supports a shoebox items api for staging transactions before they are posted to the ledger.
  • Kashoo supports basic inventory items while TSA does not.

The API endpoints indicate which of our products they are meant for using one or both of the following product markers.

kashooKashoo Cloud Accounting (Our classic platform) tsaTrulySmall Accounting (Our leading-edge platform)

Note that the applicatinos are hosted under different domains. This is mostly cosmetic, since they map to the same backend, but is worth following. The Kashoo api is hosted at https://app.kashoo.com/api while the TSA api is at https://app.trulysmall.com/api.

Authentication

Kashoo allows for two categories of authentication: first-party and third-party. First-party authentication is simple but meant for first-party development since it requires the user's password. Third-party authentication is for external developers who wish to integrate with TrulySmall, but it takes more time to get running.

First-party Authentication

There are two ways to log the user in directly: standard user-password login or through single-sign-on providers such as Google.

The endpoints for first-party authentication are under the /authTokens path. See the ebdpoints below for more information.

When a first-party login completes successfully, the api returns a json token. For example, a login call to POST https://api.kashoo.com/authTokens with an accept header of json will return the following:

{
"authenticationCode":"asdasdasdasdasdadasdasdasda",
"expiryDate":1698789858551,
"locale":"default",
"myUserId":1231232,
"restriction":null,
"site":"app.kashoo.com"
}

This json can then be used within Authorization headers using the format:

Authorization: TOKEN json:{"authenticationCode":"asdasdasdasdasdadasdasdasda","expiryDate":1698789858551,"locale":"default","myUserId":1231232,"restriction":null,"site":"app.kashoo.com"}

These tokens are valid for a limited but relatively long time. Once they expire, the user must log in again.

Create token

Creates an auth token for accessing the api on behalf of a user. This endpoint is used for first-party login with basic auth. The caller can supply the email and password using form params. The endpoint also accepts sso login such as Google using the provider and authCode form params. Callers will usually want to accept json to return a format easy to use in an Authorization header.

Request Body schema: */*
site
string
lc
string
Default: "en_US"
duration
integer <int64>
Default: 86400000
restriction
string
email
string
password
string
mfaCode
string
provider
string
authCode
string
type
string

Responses

Response samples

Content type
{
  • "myUserId": 0,
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "restriction": "string",
  • "site": "string",
  • "locale": "string",
  • "authenticationCode": "string"
}

Verify token privileges

This endpoint is used to verify that the request's authorization information is permitted to perform the specified restriction.

query Parameters
restriction
string

Responses

OAuth2

First-party login requires the user to enter their password, which is not suitable for third-parties since the password should only be shared with Kashoo. For this purpose, Kashoo provides an OAuth2 service that allows third-parties to redirect users to Kashoo to log in and then redirects them back to the third party app with an auth code that can be exchanged for an access token. The third party can then use the access token to make api calls to Kashoo on the user's behalf.

An explanation of OAuth2 is beyond the scope of this document. There are many resources online that explain the protocol, for example this one.

To get started, a third-party developer must register their app with Kashoo. This is done manually and requires contacting Kashoo to provide the application's name and its redirect URLs for the OAuth2 flow. Note that there currently can only be one redirect url per client id. Once the app is registered, the developer will receive their client id and secret to use in the OAuth2 flow.

Here is a brief outline of the flow:

  1. A single page app (SPA) redirects the browser/user to the Kashoo OAuth2 authorization endpoint.

    // client side code
    
    // generate a random state token to prevent cross-site request forgery
    const state = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15)
    
    // store the state somewhere to verity it upon the response (this part is simplified here)
    sessionStorage.setItem('sign-in-state', state)
    
    window.location.href = 'https://app.kashoo.com/oauth2/authorize?' +
       'client_id=' + yourClientId +
       '&response_type=code' +
       '&scope=full-access' +
       '&redirect_uri=' + encodeURIComponent(yourRedirectUrl) +
       '&state=' + state
    
  2. The user logs in to Kashoo on the OAuth2 application and is sent to the redirect URL with an authorization code.

    https://redirect-uri?code=... the authorization code ...&state=... the state ...

  3. The redirect url should be handled by a server-side handler because it will need the client secret. It will use the authorization code and client secret to obtain an access token from Kashoo.

    // server side code
    
    // send the following as form data
    let formData = new URLSearchParams()
    formData.append('code', ... received authorization code ...)
    formData.append('grant_type', 'authorization_code')
    formData.append('redirect_uri', yourRedirectUrl)
    
    // make a call to the OAuth2 server to exchange the code for an access token using form encoded data
    // and the client id and secret as a basic-auth Authorization header
    axios.post('https://app.kashoo.com/oauth2/token', formData, {
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            auth: {
            username: yourClientId,
            password: yourClientSecret
        }
    })
    .then(response => {
            // parse the response data into tokens and user id
            this.bearerToken = response.data.access_token
            this.refreshToken = response.data.refresh_token
            this.expiresIn = response.data.expires_in
            this.tokenType = response.data.token_type
            this.userId = response.data.userId
    
  4. The server-side handler should store the bearer and refresh tokens for the user and use them to make api calls to Kashoo.

Start auth process

Send the user to this url with the required query parameters to begin the OAuth2 authorization process. The endpoint will send the user to the OAuth2 app to log in with their Kashoo account and authorize the client app to access their data.

query Parameters
client_id
required
string

Your OAuth2 client id

response_type
required
string

The oauth response type, for example 'code'

redirect_uri
required
string

The uri to redirect the user to after authorization

state
string

An optional state parameter that will be returned to you in the redirect

Responses

Create or refresh token

When the OAuth2 app returns control to the application along with an auth code, use this endpoint to exchange the auth code for an access token. In this case, set the grant_type to 'authorization_code'. This grant type requires code and redirect_uri parameters to be sent in the request. When refreshing a token, set the grant_type to 'refresh_token' and include the refresh token in the request.

header Parameters
Authorization
required
string

A basic auth header with the client id and secret as username and password

Request Body schema: application/x-www-form-urlencoded
required
code
string

The auth code returned from the OAuth2 app, for the 'authorization_code' grant type

grant_type
required
string

The grant type, for example 'authorization_code' or 'refresh_token'

redirect_uri
string

The uri to redirect the user to after authorization, for the 'authorization_code' grant type

refresh_token
string

The refresh token to use when refreshing a token, for the 'refresh_token' grant type

Responses

Response samples

Content type
application/json
{
  • "access_token": "example-access-token",
  • "expires_in": 3600,
  • "refresh_token": "example-refresh-token",
  • "token_type": "bearer",
  • "userId": "12355"
}

Multifactor Authentication

Users can enable multi-factor authentication (MFA) on their account. When MFA is enabled, the user must use another authentication method in addition to their password to complete their login and receive an authentication token. The api supports only sms as a second factor at this time.

Perform SMS MFA verification

This endpoint is used both for requesting the mfa verification process to begin and to verify a response from the user. If the code is not present, then a new code will be sent to the user's phone. If the code is present, then it will be verified. There is no response body for this endpoint, only a status code.

Request Body schema: */*
code
string

Responses

Enable SMS MFA for a user

Assuming the code is correct, this will enable SMS MFA on the user account. The user will then need to complete SMS MFA whenever logging in. If the code passed in is incorrect, a Forbidden response will be returned.

Request Body schema: */*
code
string

Responses

Disable SMS MFA for the user

The user will no longer need to complete SMS MFA when logging in. This endpoint requires a valid auth token for the user and returns either a Forbidden or a No Content response.

Responses

List user's enabled mfa methods

Lists the enabled mfa methods for a user. If there are none, then mfa is not required for logging in. Otherwise, one of the listed mfa methods is required to complete login.

Responses

Response samples

Content type
[
  • {
    }
]

Users

kashootsaContains endpoints to manage users, groups, and roles in a business.

Create a new user

Adds a new user to our system. This is an unverified user, meaning that we are not yet certain that they own the associated credentials. To make sure of this, a verification email is sent to user and permanent access is only granted if they click on the associated link.

Request Body schema: */*
first
string
last
string
email
string
password
string
additionalParams
string
Default: ""
site
string
lc
string
Default: "en_US"
duration
integer <int64>
Default: 86400000

Responses

Creates a verified user

Adds a new user to the system. This is a verified user, which means that we assume that they are the owner of the passed in user credentials, and we do not need to send a verification email to them to make sure. This is useful in cases like iOS, Square, and oauth2, where the users have already verified with the associated provider.

Request Body schema: */*
first
string
last
string
email
string
password
string
provider_name
string
provider_access_token
string
invite
string
additionalParams
string
Default: ""
mfaCode
string
site
string
lc
string
Default: "en_US"
duration
integer <int64>
Default: 86400000

Responses

Link OAuth Accounts

Link OAuth accounts with existing user logins.

Request Body schema: */*
provider_access_token
string
provider_name
string
lc
string
Default: "en_US"

Responses

Get information about the logged in user

Responses

Response samples

Content type
No sample

Updates user

Request Body schema:
id
integer <int64>
object (ContactInformationInfo)
staff
boolean
betaTester
boolean
accountingProfessional
boolean
expireSessions
boolean
useHighContrastStyle
boolean
readOnly
boolean
removed
boolean
active
boolean
verified
boolean
object (TransferDate)
object (TransferDate)
object (TransferDate)
lastLogin
string <date-time>
serviceProvider
integer <int64>
serviceProviderAdmin
boolean
allowSelectionOfNonStandardAccounts
boolean
inviteCode
string
email
string
name
string
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Deletes user records and their businesses

Completetly deletes a user and their businesses from the database and all other third-part systems such as Intercom.

query Parameters
confirm
string

Responses

User Businesses

Activate a user's business

Request Body schema: application/x-www-form-urlencoded
campaign
string
site
string

Responses

Get the list of businesses the user has access to

query Parameters
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 0

Responses

Roles

kashootsa

Gets the roles of a users

query Parameters
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Businesses

kashootsa

Returns the groups defined for the business.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0
type
string
Value: "CONTACT"

Responses

Response samples

Content type
No sample

Add a group to the business

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
name
string
removed
boolean
type
string
contacts
Array of integers <int64> [ items <int64 > ]

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Add an account to the business

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
name
string
type
string
Enum: "ACCOUNTS_RECEIVABLE" "ACCOUNTS_PAYABLE" "BANK" "COST_OF_GOODS_SOLD" "CREDIT_CARD" "EQUITY" "EXPENSE" "FIXED_ASSET" "INCOME" "GAIN_OR_LOSS_ON_EXCHANGE" "LONG_TERM_LIABILITY" "OTHER_CURRENT_ASSET" "OTHER_CURRENT_LIABILITY" "OTHER_ASSET" "TAXES" "CASH" "RETAINED_EARNINGS" "PREPAID_EXPENSE" "CLIENT_CREDIT" "INVENTORY" "PAYROLL_TAX"
description
string
number
string
standardTerms
string
object (TransferDate)
object (TransferDate)
removed
boolean
feed
integer <int64>
readOnly
boolean
taxNumber
integer <int64>
taxAuthorityCode
string
archived
boolean
normalBalanceCredit
boolean
system
boolean
parent
integer <int64>
nameAndNumber
string
lastModified
integer <int64>
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

List taxes associated with the business

Providing version == 2 will return a TaxCompositeInfo, else a LegacyTaxInfo

path Parameters
business_id
required
integer <int64>
query Parameters
version
integer <int32>

Responses

Response samples

Content type
[
  • {
    }
]

List taxes associated with the business

path Parameters
business_id
required
integer <int64>
Request Body schema:
string

Responses

Request samples

Content type
No sample

Response samples

Content type
[
  • {
    }
]

Subscription

kashootsa

Get subscription of a business

path Parameters
business_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Gets the logged in user's subscription

Responses

Add a subscription

Request Body schema: */*
text
string

Responses

Gets a Subscription

Gets a Subscription using an subscription ID or userID (fusionauth)

query Parameters
id
string

ID of subscriptions

subscriberId
string

Subscriber ID

header Parameters
Authorization
required
string

Example: Bearer foo

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Create a Subscription

Creates a Subscription

Request Body schema: application/json
required

Create Subscription Request

appId
string
originalId
string
platformProductId
string
purchaseToken
string
purchasedExplicitlyInApp
boolean
store
required
string
subscriberId
string
subscriptionApplication
string
userEmail
string
userId
string

Responses

Request samples

Content type
application/json
{
  • "appId": "string",
  • "originalId": "string",
  • "platformProductId": "string",
  • "purchaseToken": "string",
  • "purchasedExplicitlyInApp": true,
  • "store": "string",
  • "subscriberId": "string",
  • "subscriptionApplication": "string",
  • "userEmail": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Creates a new chargebee checkout window

Creates a new chargebee checkout window

header Parameters
Authorization
required
string

Example: Bearer foo

Request Body schema: application/json
required

New Checkout

couponId
Array of strings
object (serverpb.ChargeBeeCustomer)
subscriberId
required
string
subscriptionApplication
required
string
subscriptionPlanId
required
string
userId
string

Responses

Request samples

Content type
application/json
{
  • "couponId": [
    ],
  • "customer": {
    },
  • "subscriberId": "string",
  • "subscriptionApplication": "string",
  • "subscriptionPlanId": "string",
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "checkoutInfo": [
    ],
  • "content": [
    ],
  • "createdAt": 0,
  • "embed": true,
  • "expiresAt": 0,
  • "failureReason": "string",
  • "id": "string",
  • "object": "string",
  • "passThruContent": "string",
  • "resourceVersion": 0,
  • "state": "string",
  • "type": "string",
  • "updatedAt": 0,
  • "url": "string"
}

Creates a new chargebee portal session

Creates a new chargebee portal session

header Parameters
Authorization
required
string

Example: Bearer foo

Request Body schema: application/json
required

New portal session

subscriptionId
string

Responses

Request samples

Content type
application/json
{
  • "subscriptionId": "string"
}

Response samples

Content type
application/json
{
  • "accessUrl": "string",
  • "createdAt": 0,
  • "customerId": "string",
  • "expiresAt": 0,
  • "id": "string",
  • "loginAt": 0,
  • "loginIpAddress": "string",
  • "logoutAt": 0,
  • "logoutIpAddress": "string",
  • "object": "string",
  • "redirectUrl": "string",
  • "status": "string",
  • "token": "string"
}

Business Plans

kashootsa

Inspect the business' current subscription plan with Kashoo.

path Parameters
business_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Updates a business plan

path Parameters
business_id
required
integer <int64>
query Parameters
inviteCode
string
Request Body schema:
id
integer <int64>
name
string
description
string
currency
string
monthlyPrice
integer <int32>
annualPrice
integer <int32>
taxCode
string
upgradePaymentAmount
integer <int32>
selectable
boolean
externalDescription
string
numOfAdditionalUsers
integer <int32>
expiryDays
integer <int32>
free
boolean
freeTrial
boolean
paymentProcessorType
string
Enum: "NONE" "BEANSTREAM" "APPLE"
billingPlatform
string
Enum: "D_BILLING" "ITUNES" "SQUARE" "AMAZON" "OFFLINE" "CHARGEBEE" "TRULYSMALL"
delayOfInitialPaymentInDays
integer <int32>

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Cancel a business plan

path Parameters
business_id
required
integer <int64>

Responses

Lists invoices on a plan

Lists the invoices that have been made on the business's current contract (plan).

path Parameters
business_id
required
integer <int64>
query Parameters
object (TransferDate)
object (TransferDate)
offset
integer <int32>
limit
integer <int32>
Default: 50

Responses

Response samples

Content type
No sample

Get a list of available plans for the business.

path Parameters
business_id
required
integer <int64>
query Parameters
inviteCode
string

Responses

Response samples

Content type
No sample

Contacts

kashootsa

Gets contact activity report

path Parameters
contact_id
required
integer <int64>
query Parameters
object (TransferDate)
object (TransferDate)
memo
string

Responses

Response samples

Content type
No sample

Gets contact statement

path Parameters
contact_id
required
integer <int64>
query Parameters
object (TransferDate)
memo
string

Responses

Response samples

Content type
No sample

Returns the subcontacts of this contact

path Parameters
contact_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Returns the invoices and bills that involve this contact.

path Parameters
contact_id
required
integer <int64>
query Parameters
object (TransferDate)
object (TransferDate)
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 100
sortColumn
string
sortOrder
string
amountLe
integer <int64>
amountGe
integer <int64>
type
Array of strings
Items Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
search
string

Responses

Response samples

Content type
No sample

Returns the contact information.

path Parameters
contact_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Updates an existing contact.

path Parameters
contact_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
type
string
Enum: "CUSTOMER" "VENDOR" "PARTNER" "OWNER" "GOVERNMENT" "OTHER" "EMPLOYEE"
object (ContactInformationInfo)
linkedBusiness
integer <int64>
receivableAccount
integer <int64>
payableAccount
integer <int64>
incomeOrExpenseAccount
integer <int64>
defaultTaxCode
string
paymentAccount
integer <int64>
paymentTerms
string
currency
string
comments
Array of strings
collaborationContext
integer <int64>
prefix
string
removed
boolean
archived
boolean
organization
boolean
parent
integer <int64>
groups
Array of integers <int64> [ items <int64 > ]
phoneNumbers
string
email
string
address
string
name
string
lastModified
integer <int64>

Responses

Request samples

Content type
No sample

Remove a contact

path Parameters
contact_id
required
integer <int64>

Responses

Receipts

kashootsa

Submit a receipt

path Parameters
business_id
required
integer <int64>
Request Body schema: */*
text
string

Responses

Items

kashooEndpoints for managing inventory items for Kashoo classic businesses. These inventory items can be used as line items in transactions and can track quantities and costs.

Gets the inventory items for the business

path Parameters
business_id
required
integer <int64>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates an inventory item

path Parameters
business_id
required
integer <int64>
Request Body schema: application/json
id
integer <int64>
itemId
string
business
integer <int64>
name
string
sku
string
description
string
defaultTaxCode
string
defaultDiscountCode
string
defaultBuyRate
number
defaultSellRate
number
defaultNote
string
inventoryAccount
integer <int64>
cogsAccount
integer <int64>
creditAccount
integer <int64>
debitAccount
integer <int64>
category
integer <int64>
readOnly
boolean
removed
boolean
tracked
boolean
archived
boolean
effectiveId
object
lastModified
integer <int64>
Array of objects (LinkInfo)

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "itemId": "string",
  • "business": 0,
  • "name": "string",
  • "sku": "string",
  • "description": "string",
  • "defaultTaxCode": "string",
  • "defaultDiscountCode": "string",
  • "defaultBuyRate": 0,
  • "defaultSellRate": 0,
  • "defaultNote": "string",
  • "inventoryAccount": 0,
  • "cogsAccount": 0,
  • "creditAccount": 0,
  • "debitAccount": 0,
  • "category": 0,
  • "readOnly": true,
  • "removed": true,
  • "tracked": true,
  • "archived": true,
  • "effectiveId": { },
  • "lastModified": 0,
  • "links": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "itemId": "string",
  • "business": 0,
  • "name": "string",
  • "sku": "string",
  • "description": "string",
  • "defaultTaxCode": "string",
  • "defaultDiscountCode": "string",
  • "defaultBuyRate": 0,
  • "defaultSellRate": 0,
  • "defaultNote": "string",
  • "inventoryAccount": 0,
  • "cogsAccount": 0,
  • "creditAccount": 0,
  • "debitAccount": 0,
  • "category": 0,
  • "readOnly": true,
  • "removed": true,
  • "tracked": true,
  • "archived": true,
  • "effectiveId": { },
  • "lastModified": 0,
  • "links": [
    ]
}

Gets an inventory item for the business by its item id.

path Parameters
id
required
integer <int64>
business_id
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "itemId": "string",
  • "business": 0,
  • "name": "string",
  • "sku": "string",
  • "description": "string",
  • "defaultTaxCode": "string",
  • "defaultDiscountCode": "string",
  • "defaultBuyRate": 0,
  • "defaultSellRate": 0,
  • "defaultNote": "string",
  • "inventoryAccount": 0,
  • "cogsAccount": 0,
  • "creditAccount": 0,
  • "debitAccount": 0,
  • "category": 0,
  • "readOnly": true,
  • "removed": true,
  • "tracked": true,
  • "archived": true,
  • "effectiveId": { },
  • "lastModified": 0,
  • "links": [
    ]
}

Updates an existing inventory item

path Parameters
id
required
integer <int64>
business_id
required
integer <int64>
Request Body schema: application/json
id
integer <int64>
itemId
string
business
integer <int64>
name
string
sku
string
description
string
defaultTaxCode
string
defaultDiscountCode
string
defaultBuyRate
number
defaultSellRate
number
defaultNote
string
inventoryAccount
integer <int64>
cogsAccount
integer <int64>
creditAccount
integer <int64>
debitAccount
integer <int64>
category
integer <int64>
readOnly
boolean
removed
boolean
tracked
boolean
archived
boolean
effectiveId
object
lastModified
integer <int64>
Array of objects (LinkInfo)

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "itemId": "string",
  • "business": 0,
  • "name": "string",
  • "sku": "string",
  • "description": "string",
  • "defaultTaxCode": "string",
  • "defaultDiscountCode": "string",
  • "defaultBuyRate": 0,
  • "defaultSellRate": 0,
  • "defaultNote": "string",
  • "inventoryAccount": 0,
  • "cogsAccount": 0,
  • "creditAccount": 0,
  • "debitAccount": 0,
  • "category": 0,
  • "readOnly": true,
  • "removed": true,
  • "tracked": true,
  • "archived": true,
  • "effectiveId": { },
  • "lastModified": 0,
  • "links": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "itemId": "string",
  • "business": 0,
  • "name": "string",
  • "sku": "string",
  • "description": "string",
  • "defaultTaxCode": "string",
  • "defaultDiscountCode": "string",
  • "defaultBuyRate": 0,
  • "defaultSellRate": 0,
  • "defaultNote": "string",
  • "inventoryAccount": 0,
  • "cogsAccount": 0,
  • "creditAccount": 0,
  • "debitAccount": 0,
  • "category": 0,
  • "readOnly": true,
  • "removed": true,
  • "tracked": true,
  • "archived": true,
  • "effectiveId": { },
  • "lastModified": 0,
  • "links": [
    ]
}

Removes an inventory item by its item id

path Parameters
id
required
integer <int64>
business_id
required
integer <int64>

Responses

Accounts

kashootsa

Get account opening balances

path Parameters
account_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Get journal entries

Get the journal entries made against an account. Returns all journal entries by default but can be filtered by date, amount, and search term. The results can be paginated and sorted.

path Parameters
account_id
required
integer <int64>
query Parameters
object (TransferDate)
object (TransferDate)
Example: endDate=2024-02-02
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 100
sortColumn
string
Example: sortColumn=date

The column to sort by

sortOrder
string
Example: sortOrder=desc

Whether to sort ascending or descending

amountLe
integer <int64>
amountGe
integer <int64>
search
string

Responses

Response samples

Content type
No sample

Get account transactions

path Parameters
account_id
required
integer <int64>
query Parameters
object (TransferDate)
object (TransferDate)
type
Array of strings
Items Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
offset
integer <int32>
Default: 0
limit
integer <int32>
Default: 100
sortColumn
string
sortOrder
string
amountLe
integer <int64>
amountGe
integer <int64>
search
string
contactId
integer <int64>

Responses

Get account balances

path Parameters
account_id
required
integer <int64>
query Parameters
object (TransferDate)
primary
boolean

Responses

Gets an account

path Parameters
account_id
required
integer <int64>
query Parameters
fields
string

Responses

Response samples

Content type
No sample

Updates an account

path Parameters
account_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
name
string
type
string
Enum: "ACCOUNTS_RECEIVABLE" "ACCOUNTS_PAYABLE" "BANK" "COST_OF_GOODS_SOLD" "CREDIT_CARD" "EQUITY" "EXPENSE" "FIXED_ASSET" "INCOME" "GAIN_OR_LOSS_ON_EXCHANGE" "LONG_TERM_LIABILITY" "OTHER_CURRENT_ASSET" "OTHER_CURRENT_LIABILITY" "OTHER_ASSET" "TAXES" "CASH" "RETAINED_EARNINGS" "PREPAID_EXPENSE" "CLIENT_CREDIT" "INVENTORY" "PAYROLL_TAX"
description
string
number
string
standardTerms
string
object (TransferDate)
object (TransferDate)
removed
boolean
feed
integer <int64>
readOnly
boolean
taxNumber
integer <int64>
taxAuthorityCode
string
archived
boolean
normalBalanceCredit
boolean
system
boolean
parent
integer <int64>
nameAndNumber
string
lastModified
integer <int64>
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

Removes an account

path Parameters
account_id
required
integer <int64>

Responses

Get bank accounts for a business

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Return a list of accounts associated with this business.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0
type
Array of strings unique
Items Enum: "ACCOUNTS_RECEIVABLE" "ACCOUNTS_PAYABLE" "BANK" "COST_OF_GOODS_SOLD" "CREDIT_CARD" "EQUITY" "EXPENSE" "FIXED_ASSET" "INCOME" "GAIN_OR_LOSS_ON_EXCHANGE" "LONG_TERM_LIABILITY" "OTHER_CURRENT_ASSET" "OTHER_CURRENT_LIABILITY" "OTHER_ASSET" "TAXES" "CASH" "RETAINED_EARNINGS" "PREPAID_EXPENSE" "CLIENT_CREDIT" "INVENTORY" "PAYROLL_TAX"
archived
boolean

Responses

Response samples

Content type
No sample

Account Types

kashootsa

Get credit card accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get equity accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get expense accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get fixed asset accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get income accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get other current asset accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get cash accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Get inventory accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get used accounts

Gets the accounts for the business that have at least one journal entry assigned to them.

path Parameters
business_id
required
integer <int64>

Responses

Response samples

Content type
No sample

Get accounts receivable accounts.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get accounts payable accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get COGS accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get gain/loss on exchange accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get long term liability accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get other current asset accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get other current liability accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get taxes and remittances accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Get retained earnings accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Get prepaid expenses accounts

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 0

Responses

Response samples

Content type
No sample

Records

kashootsa

Gets record sequence numbers

Returns the next sequence number for each record type. This is important for invoices and bills where the sequence number is used to generate the invoice number.

path Parameters
record_type
required
string
Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
business_id
required
integer <int64>

Responses

Response samples

Content type
[
  • {
    }
]

Get business records

Returns all the records for a business. Records can be of several types, including:

  • Bills
  • Invoices
  • Adjustments
  • Transfers
path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 50
object (TransferDate)
object (TransferDate)
type
Array of strings
Items Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
search
string
amountGe
integer <int64>
amountLe
integer <int64>
exclude
string
status
string
object (TransferDate)
sortColumn
string
sortOrder
string
includeRemoved
boolean

Only non-removed records are included by default.

modifiedSince
integer <int64>
Example: modifiedSince=1716999647879

Include only records modified since this unix timestamp, in milliseconds.

contactId
integer <int64>

Responses

Response samples

Content type
[
  • {
    }
]

Add a record to a business

path Parameters
business_id
required
integer <int64>
Request Body schema:

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Add a set of records to a business

Add a set of records in one operation. All records must belong to the same business.

path Parameters
business_id
required
integer <int64>
Request Body schema:
Array

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Import records from an outside source

Imports records from an outside source. Right now this only supports ofx/qbo files.

path Parameters
business_id
required
integer <int64>
Request Body schema:
uuid
string
url
string
filename
string
account
integer <int64>
preview
boolean

Responses

Request samples

Content type
No sample

Response samples

Content type
No sample

Update a set of records

Updates a batch of records in one operation. All records must belong to the same business. This can take a long time because records still have to be added serially due to limitations in the books engine.

Request Body schema:
Array

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Unprocess a set of records

Unprocess a batch of records and returns them to the inbox. This operation is used for TrulySmall Accounting.

Request Body schema:
Array

Responses

Request samples

Content type
[
  • {
    }
]

Response samples

Content type
[
  • {
    }
]

Get a record

Gets a record by its record id.

path Parameters
record_id
required
integer <int64>

Responses

Response samples

Content type
application/json
No sample

Update a record

Updates a record with the provided data.

path Parameters
record_id
required
integer <int64>
Request Body schema:

Responses

Request samples

Content type
No sample

Remove a record

Removes a record. This is a soft delete and the recodd can be restored.

path Parameters
record_id
required
integer <int64>

Responses

Invoices

kashootsa

List invoice payments associated with this business.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 50
object (TransferDate)
object (TransferDate)
search
string
amountGe
integer <int64>
amountLe
integer <int64>
sortColumn
string
sortOrder
string
includeRemoved
boolean
modifiedSince
integer <int64>
contactId
integer <int64>

Responses

Response samples

Content type
No sample

Add an invoice payment to a business.

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
description
string
memo
string
exchangeRate
number <double>
contact
integer <int64>
currency
string
account
integer <int64>
object (TransferDate)
collaborationContext
integer <int64>
number
string
contactName
string
removed
boolean
readOnly
boolean
homeCurrency
string
project
integer <int64>
projectName
string
creation
string <date-time>
lastModified
string <date-time>
inboxReference
string
unallocatedAmount
integer <int64>
Array of objects (PaymentAllocationOut)
creditAccount
integer <int64>
method
string
amount
integer <int64>
byCheck
boolean
type
string
Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
foreignCurrency
boolean
Array of objects (RecordAttachmentInfo)
allowZeroAmounts
boolean
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

List invoices associated with this business.

This is the same as accessing records with type=INVOICE.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 50
object (TransferDate)
object (TransferDate)
search
string
amountGe
integer <int64>
amountLe
integer <int64>
exclude
string
status
string
object (TransferDate)
sortColumn
string
sortOrder
string
includeRemoved
boolean
modifiedSince
integer <int64>
contactId
integer <int64>

Responses

Response samples

Content type
No sample

Add an invoice to a business.

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
description
string
memo
string
exchangeRate
number <double>
contact
integer <int64>
currency
string
account
integer <int64>
object (TransferDate)
collaborationContext
integer <int64>
number
string
contactName
string
removed
boolean
readOnly
boolean
homeCurrency
string
project
integer <int64>
projectName
string
creation
string <date-time>
lastModified
string <date-time>
inboxReference
string
Array of objects (PaymentAllocationIn)
terms
string
object (TransferDate)
poNumber
string
Array of objects (LegacyTaxEntryInfo)
totalDue
integer <int64>
balanceDue
integer <int64>
paid
boolean
exchangePayment
boolean
keepInOriginalCurrency
boolean
balanceDueFormatted
string
totalDueFormatted
string
totalBeforeTaxes
integer <int64>
Array of objects (RecordTaxAmount)
totalLocalDue
integer <int64>
type
string
Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
paidInvoice
boolean
totalPaidImmediately
integer <int64>
totalPaidLater
integer <int64>
totalPaid
integer <int64>
income
boolean
foreignCurrency
boolean
Array of objects (RecordAttachmentInfo)
allowZeroAmounts
boolean
Array of objects (LineItemInfo)
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

Email an invoice for a record

Sends an invoice email for the record to the specified email address. If preview is true, the invoice is not sent, but a preview is returned.

path Parameters
record_id
required
integer <int64>
Request Body schema:
required
to
string
cc
string
bcc
string
message
string
processor
string
preview
boolean
previewType
string
attachments
Array of strings
template
string

Responses

Request samples

Content type
No sample

Bills

kashootsa

List bill payments associated with this business.

This is the same as accessing records with type=BILL_PAYMENT.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 50
object (TransferDate)
object (TransferDate)
search
string
amountGe
integer <int64>
amountLe
integer <int64>
sortColumn
string
sortOrder
string
includeRemoved
boolean
modifiedSince
integer <int64>
contactId
integer <int64>

Responses

Response samples

Content type
No sample

Add a bill payment to a business.

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
description
string
memo
string
exchangeRate
number <double>
contact
integer <int64>
currency
string
account
integer <int64>
object (TransferDate)
collaborationContext
integer <int64>
number
string
contactName
string
removed
boolean
readOnly
boolean
homeCurrency
string
project
integer <int64>
projectName
string
creation
string <date-time>
lastModified
string <date-time>
inboxReference
string
unallocatedAmount
integer <int64>
Array of objects (PaymentAllocationOut)
creditAccount
integer <int64>
method
string
amount
integer <int64>
byCheck
boolean
Array of objects (CheckRegistryInfo)
type
string
Enum: "INVOICE" "TRANSFER" "ADJUSTMENT" "BILL" "BILL_PAYMENT" "INVOICE_PAYMENT" "YEAR_END_ADJUSTMENT" "OPENING_BALANCE"
foreignCurrency
boolean
Array of objects (RecordAttachmentInfo)
allowZeroAmounts
boolean
Array of objects (LinkInfo)

Responses

Request samples

Content type
No sample

List bills associated with this business.

This is the same as accessing records with type=BILL.

path Parameters
business_id
required
integer <int64>
query Parameters
offset
integer <int32>
limit
integer <int32>
Default: 50
object (TransferDate)
object (TransferDate)
search
string
amountGe
integer <int64>
amountLe
integer <int64>
exclude
string
status
string
object (TransferDate)
sortColumn
string
sortOrder
string
includeRemoved
boolean
modifiedSince
integer <int64>
contactId
integer <int64>

Responses

Response samples

Content type
No sample

Add a bill to a business.

path Parameters
business_id
required
integer <int64>
Request Body schema:
id
integer <int64>
business
integer <int64>
description
string
memo
string
exchangeRate
number <double>
contact
integer <int64>
currency
string
account
integer <int64>
object (TransferDate)
collaborationContext
integer <int64>
number
string
contactName
string
removed
boolean
readOnly
boolean
homeCurrency
string
project
integer <int64>