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.
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 Code||Meaning||Corrective Action|
|200||OK||The request was processed successfully.|
|400||Bad Request||The request is invalid. Check the format of your request and try again.|
|401||Unauthorized||The API key is not accepted.|
|403||Forbidden||The request is denied, however the API key may be valid.|
|404||Not Found||The specified resource does not exist.|
|405||Method Not Allowed||Only the documented HTTP verbs are supported.|
|429||Too Many Requests||You have hit a rate limit. Reduce your request rate.|
|500||Internal Server Error||An internal error has occurred processing your request.|
|503||Service Unavailable||The API is temporarily unavailable.|
Successful responses yield a HTTP status code of
200 and a JSON body similar to the structure below:
status key is set to
ok and the
details key is present.
Depending on the context of the request, the value of
detailscould either be an object or an array.
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.
correlationId is included in both successful and error response. Please provide this ID if you are contacting 9Spokes support regarding an issue.