Requests

The 9Spokes API organizes data in a RESTful manner. This means data resources are organized hierarchically, with the company object being the topmost resource in most cases.

Responses

All API responses adhere to a strict JSON data format making it easy for app developers to parse success & error responses. The content-type is always application/json and the response body is always an object containing, at the very least, a status key. The value of status is either ok for successes or err for errors.

HTTP status codes are used to further categorize the response. The table below denotes all the supported HTTP response codes.

HTTP CodeMeaningCorrective Action
200 OKThe request was processed successfully.
400Bad RequestThe request is invalid. Check the format of your request and try again.
401UnauthorizedThe API key is not accepted.
403ForbiddenThe request is denied, however the API key may be valid.
404Not FoundThe specified resource does not exist.
405Method Not AllowedOnly the documented HTTP verbs are supported.
429Too Many RequestsYou have hit a rate limit. Reduce your request rate.
500Internal Server ErrorAn internal error has occurred processing your request.
503Service UnavailableThe API is temporarily unavailable.

Success Response

Successful responses yield a HTTP status code of 200 and a JSON body similar to the structure below:

The status key is set to ok and the details key is present.

📘

Depending on the context of the request, the value of details could either be an object or an array.

Error Response

API requests that could not be processed will carry a HTTP code that is greater than 399 and a body similar to the structure shown here.

Correlation ID

A correlationId is included in both successful and error response. Please provide this ID if you are contacting 9Spokes support regarding an issue.