ThoughtFarmer REST API Documentation

ThoughtFarmer REST API Documentation

The ThoughtFarmer API is RESTful, so that the API is entirely HTTP-based. This means that methods that retrieve data from the ThoughtFarmer API require a GET request. Methods that submit, change, or destroy data require a POST, PATCH, PUT or DELETE.

API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method. HTTP Response Codes are meaningful. Each API method lists the HTTP Response codes that indicate an error. A response code of 200 (OK) means success.

Making API calls


Any request to the API requires an authentication token to be passed along with it. To get a token, first you need to make a call to either the /authenticate or /impersonate API endpoints along with a valid username, password and application id (and user id for impersonation if required). For a successful call, you are returned the token value to be used in all subsequent requests.

The application id is a unique identifier that lets ThoughtFarmer know that this API request is coming from a trusted client. Valid application ids can be found in the Administration panel > Advanced options section > Configuration settings page under api.applicationCodes. You can use any listed identifier as your application id.

Secure Requests

By default, ThoughtFarmer expects calls to its API to be made via https. This means that any API call coming into ThoughtFarmer must be a secure call; if not, the call will fail with a 505 - HttpVersionNotSupported error. This can be configured by going to the Administration panel Advanced options section > Configuration settings page under api.mustUseHttps and setting this value to false.

Responses (XML/JSON)

By default, responses from the API are returned as JSON. You can also request data in XML format, in which case you should add the following header to your HTTP request: Accept: application/xml