Kashoo API Documentation

Introduction

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

General Advice and Key Concepts

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

Next, be sure to take advantage of tools like soapUI to explore the API a bit, generate sample requests and responses, and make test calls. For the REST API you can of course use curl or some other command-line thing but soapUI is very powerful and useful for getting started using an API (regardless of whether you are using java)

SOAP API Conventions

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.

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:

There is also a WADL document describing the REST API.

SOAP

This API is exposed through a set of WSI Basic Profile -compliant SOAP v1.1 endpoints. The API supports XML-binary Optimized Pacakging (XOP) and SOAP Message Transmission Optimization Mechanism (MTOM) for transmission of binary data. The SOAP API is fully described by the following endpoints:

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.

Data Schemas

id namespace schema file
ns0 Default Namespace ns0.xsd

XML Data Elements

XML Data Types

Home

REST Endpoints

SOAP Services

XML Data Elements

XML Data Types