Introduction

Welcome to Q°emotion API! You can use our API to access Q°emotion ressources, which include:

See all your projects
See a specific project
Add a verbatim to an existing project
Add many verbatims to an existing project
Get thematic classification for a verbatim

You can download here a Postman collection with all available queries.

If you have any question, do not hesitate to send an email to the support: support-team[at]qemotion.com

Rate limit

The maximum allowed rate is 100 requests per second. By exceeding it you will receive a response with 429 status code (Too many requests). Please contact the support team at support-team[at]qemotion.com if an extended rate limit is needed.

Authorization

To authorize, use this code:

curl -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" https://api-integration.cxinsights.io

Make sure to replace your_token_here with your API key.

Q°emotion API uses keys to authorize access. Ask the support to provide your api key.

The API key should be included in all request hearders like the following:

Authorization: Bearer your_token_here

You must replace your_token_here with your personal API key.

Projects

Get All Projects

This endpoint returns all the account's projects.

curl --location --request GET 'https://api-integration.cxinsights.io/projects' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here'

require "uri"
require "net/http"

url = URI("https://api-integration.cxinsights.io/projects")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer your_token_here"

response = http.request(request)
puts response.read_body

import requests
import json

url = "https://api-integration.cxinsights.io/projects"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer your_token_here'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "name": "Qemotion Website",
    "language": "en",
    "config_integrations":
    [
      {
        "id": 1,
        "name": "Configuration name one",
        "questions": []
      },
      {
        "id": 2,
        "name": "Configuration name two",
        "questions": ["Where is Brian?"]
      }
    ],
    "filters":
    [
      "Filter1",
      "Filter2"
    ]
  }
]

HTTP Request

GET https://api-integration.cxinsights.io/projects

Query Parameters

None

Response

An array of :

Key	Description	Type
id	The project id	Integer
name	The project name	String
config_integrations	An array of hash of configurations available on the project. With `id`, `name` and list of available `questions` (if the source is Survey). The `id` is mandatory to add a new verbatim to the project (see Verbatims section)	Array of JSON objects
filters	An array of existing filters on the project	Array of objects

Get a Specific Project

curl --location --request GET 'https://api-integration.cxinsights.io/projects/{{ProjectID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here'

require "uri"
require "net/http"

url = URI("https://api-integration.cxinsights.io/{{ProjectID}}")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer your_token_here"

response = http.request(request)
puts response.read_body

import requests
import json

url = "https://api-integration.cxinsights.io/{{ProjectID}}"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer your_token_here'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

The above command returns JSON structured like this:

{
    "id": 1,
    "name": "Qemotion Website",
    "language": "en",
    "config_integrations":
    [
      {
        "id": 1,
        "name": "Configuration name one",
        "questions": []
      },
      {
        "id": 2,
        "name": "Configuration name two",
        "questions": ["Where is Brian?"]
      }
    ],
    "filters":
    [
      "Filter1",
      "Filter2"
    ]
  }

Return a specific project. The user must have access to the project to be able to see it.

HTTP Request

GET https://api-integration.cxinsights.io/projects/<ID>

URL Parameters

Key	Description	Type
ID	The ID of the project to retrieve	Integer

Response

The project details :

Key	Description	Type
id	The project id	Integer
name	The project name	String
config_integrations	An array of hash of configurations available on the project. With `id`, `name` and list of available `questions` (if the source is Survey). The `id` is mandatory to add a new verbatim to the project (see Verbatims section)	Array of Objects
filters	An array of existing filters on the project	Array of Objects

Verbatims

Add a Verbatim

curl --location --request POST 'https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here' \
--data-raw '{
    "text": "This is an example",
    "lang": "en",
    "creation_date": "2021-01-01",
    "author": "client",
    "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
    "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
    "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
    "configuration_id": "23",
    "callback_url": "www.exemple.com",
    "filters": {
        "filter_1": "value_1",
        "filter_2": "value_2"
    },
    "sat": 5,
    "ces": 5,
    "reco": 10,
    "informations": {
        "information_1": "value_1",
        "information_2": "value_2"
    }
}
'

require "uri"
require "net/http"

url = URI("https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer your_token_here"
request.body = {
  "text": "This is an example",
  "lang": "en",
  "creation_date": "2021-01-01",
  "author": "client",
  "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
  "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
  "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
  "configuration_id": "23",
  "callback_url": "www.exemple.com",
  "filters": {
    "filter_1": "value_1",
    "filter_2": "value_2"
  },
  "sat": 5,
  "ces": 5,
  "reco": 10,
  "informations": {
      "information_1": "value_1",
      "information_2": "value_2"
  }
}


response = http.request(request)
puts response.read_body

import requests
import json

url = "https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims"

payload = json.dumps({
  "text": "This is an example",
  "lang": "en",
  "creation_date": "2021-01-01",
  "author": "client",
  "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
  "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
  "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
  "configuration_id": "23",
  "callback_url": "www.exemple.com",
  "filters": {
    "filter_1": "value_1",
    "filter_2": "value_2"
  },
  "sat": 5,
  "ces": 5,
  "reco": 10,
  "informations": {
    "information_1": "value_1",
    "information_2": "value_2"
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer your_token_here'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

The above command returns JSON object structured like this:

{
    "uuid": "33893246-ce83-4a13-983a-9fbf194837a6"
}

If something went wrong, you will receive the an error message with an HTTP error status and a JSON object like this :

{
    "errors": [
        "Error message"
    ]
}

Add a new verbatim to a project. Return the uuid of the newly created verbatim if created. We need time to process the verbatim and add it to the web application, please use callback url to get feedback.

The uuid verbatim is the unique identifier.

HTTP Request

POST https://api-integration.cxinsights.io/projects/<ID>/verbatims/

Body parameters

Parameter	Mandatory	Description	Type
text	true	The `content of your verbatim`. Can't be longer than 10 000 characters	String
lang	true	The language of your verbatim. Can be `fr` or `en`	String
creation_date	true	The date of creation of your verbatim. Can be `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS:SSS`. e.g '2023-02-17', '2023-02-17T10:47:00.852Z'	String
conversation_id	false	The `id of the group/conversation` the verbatim belongs to.	String
author	false	The `author` of the verbatim. e.g: Agent, Bot ... Defaults to 'Client'. Needed especially for verbatims authors different of the client(customer).	String
customer_external_id	false (true if conversation_id is set)	The `customer id in your system`.	String
verbatim_external_id	false (true if conversation_id is set)	The `verbatim id in your system`.	String
configuration_id	true	The `id of the configuration id` (see Projects section).	Integer
callback_url	false	The `url` where you want to receive the result of the verbatim processing.	String
filters	false	The `filters` you want for your verbatim, with their values (See example below). The filters can't be different from those already created for the verbatim's project.	JSON Object
sat	false	`Satisfaction` of the verbatim.	Integer
ces	false	`Customer Effort Success` of the verbatim.	Integer
reco	false	`Recommendation` of the verbatim.	Integer
informations	false	`Informations` about the verbatim. Can't have more than 20.	JSON object

Warning — If you have a configuration with a question, you must add question in the filters. Warning — For author field we suggest you to set a value when the verbatim comes from someone(something) different of the Client.

Response

Key	Description	Type
uuid	The verbatim uuid	String

Callback Response

If you provide the callback parameter while adding the verbatim, you will get the following data posted to the callback url when the processing job completes:

Key	Description	Type
uuid	The verbatim uuid	String
status	The processing status	String
error	Error message (If the status != 200)	String

Add many verbatims

curl --location 'https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here' \
--data '[
    {
      "text": "This is an example",
      "lang": "en",
      "creation_date": "2021-01-01",
      "author": "client",
      "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
      "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
      "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
      "configuration_id": "23",
      "callback_url": "www.exemple.com",
      "filters": {
          "filter_1": "value_1",
          "filter_2": "value_2"
      },
      "sat": 5,
      "ces": 5,
      "reco": 10,
      "informations": {
          "information_1": "value_1",
          "information_2": "value_2"
      }
    },
    {
      "text": "This is an example",
      "lang": "en",
      "creation_date": "2021-01-01",
      "author": "client",
      "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
      "verbatim_external_id": "4a3651a2-6c9d-49ff-815d-f6c105c286ae",
      "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
      "configuration_id": "23",
      "callback_url": "www.exemple.com",
      "filters": {
          "filter_1": "value_1",
          "filter_2": "value_2"
      },
      "sat": 5,
      "ces": 5,
      "reco": 10,
      "informations": {
          "information_1": "value_1",
          "information_2": "value_2"
      }
    }
]'

require "uri"
require "json"
require "net/http"

url = URI("https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims/bulk")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer your_token_here"
request.body = JSON.dump([
                           {
                             "text": "This is an example",
                             "lang": "en",
                             "creation_date": "2021-01-01",
                             "author": "client",
                             "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
                             "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
                             "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
                             "configuration_id": "23",
                             "callback_url": "www.exemple.com",
                             "filters": {
                               "filter_1": "value_1",
                               "filter_2": "value_2"
                             },
                             "sat": 5,
                             "ces": 5,
                             "reco": 10,
                             "informations": {
                               "information_1": "value_1",
                               "information_2": "value_2"
                             }
                           },
                           {
                             "text": "This is an example",
                             "lang": "en",
                             "creation_date": "2021-01-01",
                             "author": "client",
                             "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
                             "verbatim_external_id": "4a3651a2-6c9d-49ff-815d-f6c105c286ae",
                             "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
                             "configuration_id": "23",
                             "callback_url": "www.exemple.com",
                             "filters": {
                               "filter_1": "value_1",
                               "filter_2": "value_2"
                             },
                             "sat": 5,
                             "ces": 5,
                             "reco": 10,
                             "informations": {
                               "information_1": "value_1",
                               "information_2": "value_2"
                             }
                           }
])

response = https.request(request)
puts response.read_body

import requests
import json

url = "https://api-integration.cxinsights.io/projects/{{ProjectID}}/verbatims/bulk"

payload = json.dumps([
  {
    "text": "This is an example",
    "lang": "en",
    "creation_date": "2021-01-01",
    "author": "client",
    "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
    "verbatim_external_id": "9ffff82b-0220-493b-9a0a-f0f4b5255358",
    "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
    "configuration_id": "23",
    "callback_url": "www.exemple.com",
    "filters": {
      "filter_1": "value_1",
      "filter_2": "value_2"
     },
    "sat": 5,
    "ces": 5,
    "reco": 10,
    "informations": {
     "information_1": "value_1",
     "information_2": "value_2"
    }
  },
  {
    "text": "This is an example",
    "lang": "en",
    "creation_date": "2021-01-01",
    "author": "client",
    "customer_external_id": "cd41971a-cdfd-49de-a65c-742432f8ba54",
    "verbatim_external_id": "4a3651a2-6c9d-49ff-815d-f6c105c286ae",
    "conversation_id": "83fed13a-e1ff-4ad9-ad41-55b2330dda31",
    "configuration_id": "23",
    "callback_url": "www.exemple.com",
    "filters": {
      "filter_1": "value_1",
      "filter_2": "value_2"
    },
    "sat": 5,
    "ces": 5,
    "reco": 10,
    "informations": {
     "information_1": "value_1",
     "information_2": "value_2"
    }
  }
])
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer your_token_here'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Add new verbatims to a project.

Returns informations about newly created verbatims.

For each verbatim you get a callback on the web endpoint specified by the callback_url parameter.

If one verbatim in the batch fails to meet validations, the whole batch will not be accepted. You will then get a 422 response with the invalid verbatims.

HTTP Request

POST https://api-integration.cxinsights.io/projects/<ID>/verbatims/bulk

Body parameters

The body is a json array where each element has the following parameters:

Parameter	Mandatory	Description	Type
text	true	The `content of your verbatim`. Can't be longer than 10 000 characters	String
lang	true	The language of your verbatim. Can be `fr` or `en`	String
creation_date	true	The date of creation of your verbatim. Can be `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS:SSS`. e.g '2023-02-17', '2023-02-17T10:47:00.852Z'	String
conversation_id	false	The `id of the group/conversation` the verbatim belongs to.	String
author	false	The `author` of the verbatim. e.g: Agent, Bot ... Defaults to 'Client'. Needed especially for verbatims authors different of the client(customer).	String
customer_external_id	false (true if conversation_id is set)	The `customer id in your system`.	String
verbatim_external_id	false (true if conversation_id is set)	The `verbatim id in your system`.	String
configuration_id	true	The `id of the configuration id` (see Projects section).	Integer
callback_url	false	The `url` where you want to receive the result of the verbatim processing.	String
filters	false	The `filters` you want for your verbatim, with their values (See example below). The filters can't be different from those already created for the verbatim's project.	JSON Object
sat	false	`Satisfaction` of the verbatim.	Integer
ces	false	`Customer Effort Success` of the verbatim.	Integer
reco	false	`Recommendation` of the verbatim.	Integer
informations	false	`Informations` about the verbatim. Can't have more than 20.	JSON object

Response

The response is an json array where each element has the following parameters

Key	Description	Type
id	The verbatim id in Qemotion system	Integer
uuid	The verbatim uuid in Qemotion system	String
verbatim_external_id	The verbatim id in your system	String
creation_date	The date of creation of your verbatim	String

Additional information on questions

A question should be precized and is expected for any comment / Verbatim coming from a source Survey. A question is not expected for any comment / Verbatim coming from any other source(s).

When being processed, verbatim with specific questions will be analysed more precisely. You will get a higher degree of accuracy particularly :

for the emotional analysis process
for negative or positive questions

Last interest: For Survey comment, you will also be able to filter the response by question on the platform.

Kindly find enclosed a default listing below to apply negative (vs. positive connotation):

Questions with a negative connotation:

Idioma	Accepted questions with negative connotation
🇺🇸	Why are you unsatisfied?
🇺🇸	Please explain why you wouldn't be ready to recommend us?
🇫🇷	Pourquoi êtes-vous insatisfait(e)?
🇫🇷	Pourquoi ne souhaitez-vous pas recommander?

NB: For any other specific questions with negative connotation, please contact us to know the precise questions that have been configured or add new ones for your project(s).

Questions with a positive connotation:

Idioma	Accepted questions with positive connotation
🇺🇸	Why are you satisfied?
🇺🇸	Please explain why you would be ready to recommend us?
🇫🇷	Pourquoi êtes-vous satisfait(e) ?
🇫🇷	Pourquoi seriez-vous prêt(e) à recommander ?

NB: For any other specific questions with positive connotation, please contact us to know the precise questions that have been configured or add new ones for your project(s).

Thematic analysis

You can get thematic classification from a text using a project thematic model

Send a verbatim for analysis

curl --location 'https://api-integration.cxinsights.io/projects/{{ProjectID}}/thematics' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here' \
--data '{
    "text": "This is an example",
    "lang": "en"
}'

require "uri"
require "json"
require "net/http"

url = URI("https://api-integration.cxinsights.io/projects/{{ProjectID}}/thematics")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer your_token_here"
request.body = JSON.dump({
                           "text": "This is an example",
                           "lang": "en"
                         })

response = https.request(request)
puts response.read_body

import requests
import json

url = "https://api-integration.cxinsights.io/projects/{{ProjectID}}/thematics"

payload = json.dumps({
  "text": "This is an example",
  "lang": "en"
})
headers = {
  'Content-Type': 'application/json'
  'Authorization': 'Bearer your_token_here'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

HTTP Request

POST https://api-integration.cxinsights.io/projects/<ID>/thematics/

Body parameters

Parameter	Mandatory	Description	Type
text	true	The `content of your verbatim`. Can't be longer than 10 000 characters	String
lang	true	The language fo the verbatim. Must be either 'fr' or 'en'	String

Response

The response is an json array where each element is a subtext from the text and the analysis results associated

Key	Description	Type
subtext_id	A generated id for the subtext	string
subtext	The subtext content	String
thematic_computing_results	Results of analysis. Each result is composed by these keys: - thematic - subthematic - subsubthematic - result_confidence_level	json array

Errors

The API uses the following error codes:

Error code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- You don't have necessary permissions for the resource.
415	Unsupported Media Type -- Content type must be 'application/json'.
422	Request could not be processed.
429	Too Many Requests -- Rate limit 100 requests per seconds.
500	Internal Server Error -- We had a problem with our server. Please try again later or contact the support team.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later or contact the support team.