Kashoo API Documentation

Introduction

Kashoo provides a comprehensive API for integrating Kashoo with your other applications and processes.

General Advice and Key Concepts

The Kashoo SOAP API is deprecated. The endpoints remain live and the documentation is posted for reference. If you are beginning a new project using the Kashoo API please use the REST API.

Whether accessing the API using a REST client or a SOAP client, there are some useful guidelines to follow.

First of all, the best source of example data is creating a business and manually entering whatever it is you
want to create in the system. Follow that example as a template for creating additional entities

SOAP API Conventions

The Kashoo SOAP API is deprecated. The endpoints remain live and the documentation is posted for reference. If you are beginning a new project using the Kashoo API please use the REST API.

In the SOAP API you typically add new objects by saving something with the id fields all null/absent.
The system fills in the ids and returns a copy of the object.

In the SOAP API you often remove an object by saving it with a field removed=true. In this case the object lives
on the database because it might be in use by historical records or audit logs. But it will disappear from lists that
it is in.

In other cases, a specific remove method is provided for things that can be permanently removed.

The SOAP API always uses an authToken to authorize each request. You can get one of these using a
username and password passed to doLogin().

REST API Conventions

Generally you create an object using HTTP POST to a URL for the collection of that object. IDs provided
should be ignored
but don't count on that - please set any id fields in the request to make sure the thing is added instead of
getting an error back.

Entities in REST are removed using the HTTP DELETE operation, but in many cases you can remove something by
setting removed=true and saving it. Up to you.

When you create an entity in the REST API its REST URL is returned to you in the Location: header of the
response. To get its body you can GET that URL.

In the REST API numeric ids of related objects are provided in fields of the data, and links to the related objects
are included in a <link> element specifying the relationship, the related entity's media type, and the
URI of the related entity.

When saving, the system will use the id provided in a field, if present. If not, it will look for a link element
and use that. So, if you are creating objects you can use the URI provided in the Location: header of the response
in a link element for a related object instead of fetching the system ID for that object.

Authentication

NOTE: Kashoo has converted all API access to use OAuth2. The HTTP Basic Auth and authToken mechanisms are still
enabled but have been deprecated. We recommend all new integrations plan to launch with OAuth2 to avoid additional development work when they
are disabled.

The REST API supports Auth Basic for testing purposes (only). Use it to test but don't save anyone's password
on disk, that's just bad security practices.

To get an auth token from a username/password, POST to /authTokens with the username and password filled into
the Auth Basic information, or on the URL

The output of an operation is sometimes affected by the HTTP Accept: header, so be sure to provide an appropriate value
for this to make sure your client is future proof if additional output types are provided in the future.

To use an authToken in a request, pass an Authorization: header with the value set to TOKEN json:{...}
where {...} is the JSON-encoded form of the auth token returned from your POST to /authTokens. You can
pass this string exactly as you received it (no need to serialize/deserialize unless you are curious about the contents)

You can also convert an auth token into a UUID for easier transport via copy/paste or in an email. To use this for
an authorization header put TOKEN uuid:... where the ... is the UUID you got.

502 and 503 Status Codes

If the server is returning a 502 or 503 status code, it might be rebooting or undergoing maintenance. You should be
prepared to retry and operation later if you get these status codes.

REST

This API supports a Representational State Transfer (REST)
model for accessing a set of resources through a fixed set of operations. The following resources are accessible through the RESTful model:

The SOAP API is also accessible by client-side libraries that can be downloaded from the download page.

Data

All endpoints act on a common set of data. The data can be represented in different data formats (i.e. MIME types), depending on the endpoint
that consumes and/or produces the data. The data can described by XML Schema, which definitively
describes the XML representation of the data, but is also useful for describing the other formats of the data, such as
JSON.

This document will describe the data using terms based on XML Schema.
Data can be grouped by namespace, with a schema document describing the elements and types of the namespace.
Generally speaking, types define the structure of the data and elements are instances of a type. For example,
elements are usually produced by (or consumed by) a REST endpoint, and the structure of each element is described by
its type.