e-satisfaction

The #1 Humanized Marketing Platform

How to read our API

Follow

Getting Started

e-satisfaction has a service API which is available to all the users of the platform to perform a set of pre-defined actions.

Read below on this document how to read our API specification and how to interact with it.

This guide is suitable for getting started with e-satisfaction API so that it can be used in cases like manual questionnaire distribution or data retrieval.

RESTful API

e-satisfaction API is designed taking into consideration the REST principles and is trying to get as closer as possible to the specifications.

Request Methods

The API makes use of all http methods that the REST specification defines based on the operation each time.For that reason, this document makes use of the following methods:

POST, PATCH, GET, DELETE

Payload Structure

The payload of each request can be provided using two formats:

  • key-value pairs, either in the url (for GET requests) or on the request body (for POST, PATCH or DELETE methods)
  • json, on the request body, for all http methods

In the context of this document, and for easier understanding of the parameters, we are going to use the json format, and this is the one we suggest for implementing API calls.

Responses

All API responses include full entities, based on the operation, according to the REST specification.

Response Fields

On each API call, you can use an extra argument called response_fields and define all the response fields that you need the API to return. No value for this parameter means that it will return all the fields of the requested resource.

You can send response_fields as an array of values, the fields you wish the API to return.

HTTP Status Codes

Based on the status of each operation, a response might have one of the following HTTP Status Codes:Normal operation codesOn a successful operation, one of the following status codes will be returned, based on the operation.

Code Description Reason
200 OK Successful Operation
201 Created Object/Entity created with success
204 No Content Successful Operation. No content provided. Usually in DELETE operations

On an error, one of the following status codes will be returned, based on the error.

The following codes will be documented on each request explicitily.

Code Description Reason
400 Bad Request In cases where the input is invalid
404 Not Found If the referenced entity/object does not exist
409 Conflict If the operation performed is in conflict with another operation or with the object state

Error codes

The following error codes can be thrown on any request and thus there is no need to document them explicitily.

Error codes can be thrown almost on any request and they documented only to define an expected behavior.

Code Description Reason
401 Unauthorized If the provided jwt is not valid
403 Forbidden If no jwt is provided
500 Internal Server Error An unexpected error occurred. We are getting notifications about these errors and we should fix it ASAP
501  Not implemented In cases where the requested operation is not implemented on the entity/object

Versions - Compatibility

e-satisfaction API is structured in versions. Current version is v3.2.

Versions follow the Semantic Versioning specification, which means that all minor and lower releases will have no breaking changes.

To highlight the specification, given a version number MAJOR.MINOR.PATCH, we increment the:

  • MAJOR version when we make incompatible API changes,
  • MINOR version when we add functionality in a backwards-compatible manner, and
  • PATCH version when we make backwards-compatible bug fixes.

In our API, we are followig the MAJOR.MINOR format for our versions, where:

  • MAJOR versions are for backward incompatible changes (e.g. brand new API)
  • MINOR versions are for whole new features

All bug fixes and small improvements will be integrated silently into the latest version (starting from the one affected, if bug, and merge up).

Compression

All API responses are compressed using gzip and a response header Content-Encoding: gzip is returned always.

Although all major libraries can handle properly the above compression, keep in mind to uncompress if you are using your own custom library.

Feedback

We are always trying to keep our documentation up-to-date with all the latest changes. However, if you find any issues that might affect your implementation and this documentation should be updated, please let us know by sending a request at support@e-satisfaction.com.

In case of security vulnerabilities, please add a subject line with a prefix of [e-satisfaction API Security Vulnerability] and we will address it immediately.

Documentation

All API requests are being documented separately on the Apiary platform and you can take a look at our own documentation here: https://esatisfactionv3.docs.apiary.io

Authentication

Before starting using the API, you should read about our API Authentication in order to set yourself up properly.

How to test the API

Before getting your code to production, you can test our API freely without the need of a sandbox account. Read more about API Testing.

Was this article helpful?
0 out of 0 found this helpful

Have more questions? Submit a request