API Documentation
How to call the API
Here's what to expect with these 5 fields:
status
Will always be either success or failure. This is sort of a low-res alias for error, in that a value of success guarantees that error is 0, and a value of failure guarantees that error is some number greater than 0.
result
This is a succinct symbol describing what happened with the call, and can be useful in differentiating result cases for certain API calls.
Here are the values that can be returned for result:
- added - the item you were looking to add was indeed added
- duplicateSkipped - the item you were looking to add was detected as duplicate, and so returned the ID of the existing item instead
- duplicateAdded - the item you were looking to add was detected as duplicate, and a new one was added anyway
- updated - the item you were looking to update was indeed updated
- noop - i.e. "no op", the change you were looking to make had no effect (e.g. deactivating a client who's already deactivated)
- deleted - the item you were looking to delete was indeed deleted
- loaded - the item or items you were fetching by "get" call were returned as you would expect
- empty - the item or items you were fetching turned out to be an empty set (e.g. fetching Actions for a client who has none)
- sent - the message or notification you were looking to send was indeed sent
return
This is an array of the value or values returned by the call.
For "add" functions this is most often a single name-value pair, like { "ClientID": 7 } for a successful call to Client.add.
Some functions have more than one return value, like Action.add, which indicates not only the ID of the newly added Action but also the ID of the ActionProject to which it was added: { "ActionID": 22, "ActionProjectID": 3 }.
For "get" functions this is always an array of zero, or more elements who are themselves associative arrays.
error
This is always an integer value of which error if any occured with the API call. When there was no error,error always has the value of numeric zero (0).
message
This is a generally human friendly message about what happened with the call, whether successful or in error. They are useful for logging purposes, certainly for error cases and perhaps even for successful ones.
The messages you can get are NOT one-to-one with error codes, as in for the same error code you can get different error messages (so do string matching on message for your error handling logic at your own risk!).
You might've noticed in the above there's a sixth field in the JSON object, timezone. Let's talk about that.
timezone
timezone ONLY appears in successful API call results. timezone is simply an echoing out of the timezone that has been set as the "preferred" one for intereactions in the API. Including this is for the benefit of those calls which return date/time values (e.g. the times of Appointments scheduled for a given client), to make it unambiguously clear in which timezone those times are in.
In general you should be able to presume you know which timezone you have set for your API account settings, but in case you've got other people potentially mucking around with the configuration, the inclusion of timezone enables you to always correctly interpret times you get back from the API.