Complete API Documentation

Introduction

eKomi product eco system consists of multiple applications that all work together to enable customers to collect, aggregate, manage and market customer feedback. This document is designed to allow customers to implement eKomi application via APIs. 

Essentially eKomi product consists of following four key topics:

  1. Feedback as seller ratings: This is the customer feedback that's pushed to Google as seller ratings.
  2. Feedback as product ratings: This is the customer feedback collected on specific products and can be displayed on the websites as well as pushed to Google and other search engines as reviews in Shopping Ads.
  3. Feedback as Net Promoter Score or CSAT: This is customer feedback collected to create NPS benchmarks. 
  4. Market research: This is general customer feedback that's meant primarily for internal purposes just as regular surveys. 

All of the above can be done across any moment-of-truth (e.g. transaction, customer support etc) or any touch point (e.g. email, sms, mobile devices etc). Regardless of the use case, the implementation flow is always the same:

Step 1: Define how data comes in the system

Step 2: Set up the feedback forms

Step 3: Define and setup how the feedback would be collected e.g. Email, SMS, Mobile devices or direct telephone calls. This can also be via manual survey forms that are then entered manually in the system or via QR codes etc. 

Step 4: Manage the feedback. This covers both management by eKomi Customer Feedback Management team as well as what the businesses can do themselves. Business may need to close-the-loop with their reviews, address their points of concerns as well as comment on their feedback privately or publicly. The eKomi system also provides the ability to create workflows so that the feedback can be forwarded to any channel defined such as via eMail or pushing directly to social media. 

Step 5: Publish the feedback across different marketing channels. This includes eKomi widgets that allow creation and publishing of feedback via embeddable widgets. These are rich snippets as well as Google Knowledge Panel compliant and publishing feedback to Google Seller Ratings as well as Google Shopping Ads etc. The feedback can also be exported so that the businesses can work with the feedback directly within their own business intelligence systems.  Other than publishing the insights are also possible to be setup with eKomi Pulse or InsurBI tool. 

This document covers the API based implementation methods. 

Basic API Principles

The entire eKomi eco system is setup as micro services. All apps expose their own APIs and only some of those APIs are available for general customer usage. The APIs can be accessed by either:

  1. Access tokens provided via eKomi oAuth based system, eKomi Connect. OR
  2. Interface ID and password: All eKomi accounts have interface id and passwords and almost all APIs support this. Note that for test purposes you can use interface id: 665 & password: FMJuyuC8uEbo3WxRa5aG for all API calls below.  

App Eco System

Following are the core relevant apps

1. Data

2. Feedback Forms

3. Request feedback

4. Manage feedback

5. Publishing feedback

CSV

Automated Review Import

SmartForms

SmartReviewRequest

QuickFeedback

  • Manual Review Request
  • Point of Sale

Feedback Engagement App

Workflow

Smart Widgets

DataOut

Other than these, there are:

  1. Voice of Employees which is used as a solution for collecting feedback from Employees. 
  2. eKomi Lite which was previously called Reputami. Since it aggregates all feedback from even third party and allows businesses to use them in combined widgets, it's also important to know the API. 

Basic Use Cases

In general, the following are the primary use cases:

  1. Sending data to eKomi so that eKomi can send out feedback requests: use AddRecipient API
  2. Get all widgets created for the shop. Use GetWidget
  3. If you want to just add a bcc email address and use that for sending data to eKomi. Use Mail2DB

Basic API (Previously called Core API v3)

The goal of basic API is to allow access to feedback and all the basic features of eKomi. The Basic API can be downloaded below:

1. CSV API

1.1 Security

1.1.1 POST User Login

Online Documentation: https://csv.ekomiapps.de/api/doc/3.0#post--api-3.0-security-login

Description: In order to use the user APIs, the oAuth2 user access token has to be obtained via this API.

Example Call:

curl -X "POST" -d "{\"username\":\"665\",\"password\":\"FMJuyuC8uEbo3WxRa5aG\"}" -H "Accept:\ application/json" -H "Content-type:\ application/json" /api/3.0/security/login

Method: POST

Request Parameters:

Pre-Condition

Parameter

In

Description

Example

Mandatory

Default

username

Request body

The eKomi Connect username. This may be different from core shop id

665

yes


password

Request body

The eKomi Connect user password. This may be different from core interface password

FMJuyuC8uEbo3WxRa5aG

yes


Post-Condition

Type

Status 

Response Body

Description

Success

200 OK

{"access_token":"ZjA5YzZlZjdiZDRjNzM5MzZkNGQwNDcyMTVlYzU0NDI5NmZkYTk5NWZlZTYxNmY3MDI3OTQ4OTEwNGE4YWJlZQ"}

The authorization token to be used with user APIs.

Login Failed

401 Unauthorized

[{"property_path":"invalid_grant","message":"Invalid username and password combination"}][{"property_path":"username","message":"This value should not be null."}]

The first response is a result of invalid username and password combination, and the second response is a result of missing username field.

Server error

500 Internal Server Error


In case of internal error, the response body is left empty.

Response:

The response status is identified by HTTP status code, while the response body is a JSON. In case of success, the JSON is comprised of an object holding the authorization token. In case of error, the JSON contains an array of error objects. Each error object contains property_path and message to help identify the cause of error.

1.1.2 POST User Logout

Online Documentation: https://csv.ekomiapps.de/api/doc/3.0#post--api-3.0-security-logout

Description: The oAuth2 user access token can be force-deleted by calling this API.

Example Call:

curl -X "POST" -d "{}" -H "Accept:\ application/json" -H "Content-type:\ application/json" -H "Authorization:\ ekomi\ NmM0YTk1YmY5M2ZiMzk3M2FjNjViY2U4NmE0ZDY2ODZjMmMzYTA5NTI1NmI0NGI1MzhhNjdiNzQwZjNlMjI2Yw" /api/3.0/security/logout

Method: POST

Request Parameters:

Pre-Condition

Parameter

In

Description

Example

Mandatory

Default

Authorization

Header

The authorization header comprising of the user authorization token prepended with the string "ekomi "

ekomi NmM0YTk1YmY5M2ZiMzk3M2FjNjViY2U4NmE0ZDY2ODZjMmMzYTA5NTI1NmI0NGI1MzhhNjdiNzQwZjNlMjI2Yw

yes


Response:

The response status is identified by HTTP status code. In case of success, the response body is empty. In case of error, the body contains a string with error description.

Post-Condition

Type

Status 

Response Body

Description

Success

204 No Content


The authorization token is set as expired.

Unauthorized

403 ForbiddenUsername could not be found.

In case of an invalid or expired token, the request will be considered as unauthorized.

Server error

500 Internal Server Error


In case of internal error, the response body is left empty.

1.2 Orders

1.2.1 GET Orders

Online Documentation: https://csv.ekomiapps.de/api/doc/3.0#get--api-3.0-orders

Description: This API returns all orders imported in CSV app by the user.

Example Call:

curl -X "GET" -H "Accept:\ application/json" -H "Content-type:\ application/json" -H "Authorization:\ ekomi\ MWE5MTZjMDA1ODEyZDlmNTZkMDU1Y2QyMDNkNDk1ZDU4ZTY3NjVlNzk1Nzk0Njc1Njg1YjBlN2IyZDY4OWRjZA" /api/3.0/orders?offset=0&limit=200&orderBy=created&orderDirection=ASC&withFeedbackOnly=0

Method: GET

Request Parameters:

Pre-Condition

Parameter

In

Description

Example

Mandatory

Default

Authorization

Header

The authorization header comprising of the user authorization token prepended with the string "ekomi "

ekomi NmM0YTk1YmY5M2ZiMzk3M2FjNjViY2U4NmE0ZDY2ODZjMmMzYTA5NTI1NmI0NGI1MzhhNjdiNzQwZjNlMjI2Yw

yes


customDataFilter

Request body

The filter to search orders based on columns and their values that have been set to import as Custom Title in input source settings. The parameter has to be a string containing JSON object with columns and their values as key-value pairs

{"LANG":"EN", "category": "Electronics"}

no


shopId

Request body

The core shop id against which the order was imported

665

no


offset

Request body

The records to offset from the result

10

no

0

limit

Request body

The number of records to return in one request. A value more than 200 is not allowed and will be reset to 200.

10

no

200

orderBy

Request body

The data column to order the result by. Available options are 'created', 'order_id', 'updated', 'id'

id

no

created

orderDirection

Request body

The direction to order the results in, using the orderBy column. Available options are 'ASC', 'DESC'

DESC

no

ASC

withFeedbackOnly

Request body

The boolean parameter to return orders only for which the feedback has been collected. Available options are (bool) true, false. Alternatively 1,0 can be used

true

no

false

createdFrom

Request body

The lower limit of the date range. The format should be supported by DateTime class constructor.

"yesterday", "2018-07-31T14:05:21+0000"

no


createdTill

Request body

The upper limit of the date range. The format should be supported by DateTime class constructor.

"yesterday", "2018-07-31T14:05:21+0000"

no


Response:

The response status is identified by HTTP status code, while the response body is a JSON. In case of success, the JSON is comprised of an object holding the authorization token. In case of error, the JSON contains an array of error objects. Each error object contains property_path and message to help identify the cause of error.

Post-Condition

Type

Status 

Response Body

Description

Success

200 OK

{ "data": [ { "created": "2018-07-31T14:05:21+0000", "updated": "2018-07-31T14:38:29+0000", "order_processed": true, "order_id": "q2az14cs2f-1914", "email": "xyupj@test.test", "custom_data": { "lang": "DE", "category": "Clothing" }, "register_date": "2018-07-31T14:38:29+0000", "product_ids": [ "417i" ], "shop_id": 665 } ], "offset": 0, "limit": 1, "total": 25 }

The data contains the orders as per the request. In case of no matching results the data array will be empty.

Unauthorized

403 ForbiddenUsername could not be found.

In case of an invalid or expired token, the request will be considered as unauthorized.

Server error

500 Internal Server Error


In case of internal error, the response body is left empty.

2. SmartForms API


API 2.0: Create Account

Description

Create an account in SFF and copy all of the forms of source account and set the default form as of the source account. Source account credentials are accepted in request headers and pass Destination account (new account) credentials in auth parameter.

Criteria:

  • Destination account credentials should not exist
  • Source account should exist
  • Linking between forms should be same as of source account.

Destination account credentials should be given in query parameter "auth" and source account credential should be given in request header parameter

Function Call

https://smartforms.ekomi.com/api/v2/createAccount

Call Method: POST


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters:

Parameters

Description

Example

Mandatory

Default

auth

Interface id and interface password for new account

665|FMJuyuC8uEbo3WxRa5aG

required



The Response will be in JSON.

Success Response

{       "message":"Request has been accepted for processing",        "status_code":202}

Error Response

{       "error":{                               "message":"Destination shop already exist",                               "status_code":409                       }}

RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Destination shop id is missing
  • Status Code: 422. Message: Destination shop password is missing
  • Status Code: 422. Message: Source shop id is missing
  • Status Code: 422. Message: Source shop password is missing
  • Status Code: 422. Message: Please provide correct parameters to API
  • Status Code: 404. Message: Source shop does not exist
  • Status Code: 409. Message: Destination shop already exist
  • Status Code: 500. Message: Destination shop does not exist on ekomi
  • Status Code: 202. Message: Request has been accepted for processing
  • Status Code: 202. Message: Request Status: pending
  • Status Code: 202. Message: Request Status: in progress

status_code

number

Status code of response, 202 in case of request accepted for processing. In case of error, status code will be given in "error" key.


 API 2.0: File Upload

Description

Creates an asset in SFF so that it can be linked to any question later with 'review' submission API. API consumer can create as many assets as he wants for a given shop.

Functional Call

https://smartforms.ekomi.com/api/v2/assets

Method: POST

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop password

FMJuyuC8uEbo3WxRa5aG

required



Request Parameters

Parameters

Description

Example

Mandatory

Default

form_id

Form ID against which the file is being submitted 

1234

required


form-data

Data parameters in request body

example given below in "Parameters in form-data Request body"

required


asset_type

Type of the asset (file) that is being uploaded, allowed types are ['image']

image

optional

image


Parameters in form-data Request body

Parameters

Description

Example

Mandatory

Default

file

Select "file" from request parameter dropdown and attach file that is to be uploaded, one file at a time.


required


API Response

The Response will be JSON.

Success Response Example:

Success Response

{        "message":"499d7e6a2d03e9d0961b382d0f659c75.png",        "status_code":200}


Error Response Example:

Error Response

{    "error": {     "message": "Form Id parameter is missing",     "status_code": 422    }}

RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Authorization parameters are missing
  • Status Code: 422. Message: Interface Id is missing
  • Status Code: 422. Message: Interface Password is missing
  • Status Code: 422. Message: Authorization parameters are incorrect
  • Status Code: 422. Message: Form Id parameter is missing

·       Status Code: 422. Message: Form Id does not exist

·       Status Code: 422. Message: File of this size is not allowed, please attach a file under <Config based size limit number> MB

  • Status Code: 422. Message: Asset Type provided for file upload is not allowed
  • Status Code: 422. Message: File Type provided for file upload is not allowed
  • Status Code: 422. Message: Asset Type and actual file mime type do not match

status_code

number

Status code of response, 202 in case of successful review creation. In case of error, status code will be given in "error" key.

object

JSON

In case of success, message will be given in "message" key which will contain file name of uploaded file.

·       Status Code: 202

  • Message: <filename with format>






Note:
Currently we only have one asset_type which is accepted for this API i.e. 'image', further types might be added in the future. File of size 1MB or less is allowed at the moment, the asset type image will be checked against the actual mime type of the file and if they don't match an error will be thrown. For example somebody provides an asset_type as 'image' and the actual file is a pdf then the system will notify them with an error that the file mime type doesn't match with the asset_type. Also, allowed extensions in 'image' asset_type are gif, png, jpg, jpeg and on the other side svg and bmp are NOT allowed.


 API 2.0: Get Question Details

Description

API will fetch details of a question of any form of shop given in authenticatiion and filter the result set according to the parameters.

Functional Call

https://smartforms.ekomi.com/api/v2/questions/[question_id]?format=json

Method: GET

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters

Parameters

Description

Example

Mandatory

Default

format

In which format user want to get response. For now only json format is available.

json

optional

json

expand

If user required questions with all options, child_questions or linked_questions. These values can be given in one request separated by comma (,)

options,child_questions,linked_questions

optional


The Response will be JSON.


Error Response

{    "error": {     "message": "Form does not exist",     "status_code": 404    }}


Success Response

{    "data": {        "question_id": 30833,        "question_label": "How many stars would you like to award?",        "question_type": "rating",        "parent_id": 0,        "options": [            {                "option_id": 1,                "option_label": 1,                "tool_tip": "Geen aanrader",                "linked_questions": [                    {                        "question_id": 36324,                        "question": "Rank likned",                        "question_type": "ranking_scale",                        "parent_id": 0,                        "options": [                            {                                "option_id": 1,                                "option_label": 1,                                "tool_tip": "Geen aanrader"                            },                            {                                "option_id": 2,                                "option_label": 2,                                "tool_tip": "Geen aanrader"                            },                            {                                "option_id": 3,                                "option_label": 3,                                "tool_tip": "Wel ok"                            },                            {                                "option_id": 4,                                "option_label": 4,                                "tool_tip": "Tevreden mee"                            },                            {                                "option_id": 5,                                "option_label": 5,                                "tool_tip": "Super tevreden mee"                            }                        ]                    }                ]            },            {                "option_id": 2,                "option_label": 2,                "tool_tip": "Wel ok",                "linked_questions": []            },            {                "option_id": 3,                "option_label": 3,                "tool_tip": "Tevreden mee",                "linked_questions": []            },            {                "option_id": 4,                "option_label": 4,                "tool_tip": "Super tevreden mee",                "linked_questions": []            },            {                "option_id": 5,                "option_label": 5,                "tool_tip": "",                "linked_questions": [                    {                        "question_id": 36324,                        "question": "Rank likned",                        "question_type": "ranking_scale",                        "parent_id": 0,                        "options": [                            {                                "option_id": 1,                                "option_label": 1,                                "tool_tip": "Geen aanrader"                            },                            {                                "option_id": 2,                                "option_label": 2,                                "tool_tip": "Geen aanrader"                            },                            {                                "option_id": 3,                                "option_label": 3,                                "tool_tip": "Wel ok"                            },                            {                                "option_id": 4,                                "option_label": 4,                                "tool_tip": "Tevreden mee"                            },                            {                                "option_id": 5,                                "option_label": 5,                                "tool_tip": "Super tevreden mee"                            }                        ]                    }                ]            }        ],        "child_questions": [            {                "question_id": 30838,                "question_label": "reste"            },            {                "question_id": 30839,                "question_label": "dfgdtrg"            }        ]    },    "status_code": 200}







RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Format should be json
  • Status Code: 422. Message: Invalid expand param, expand value should be options, child_questions or linked_questions.
  • Status Code: 404. Message: questions_id is invalid
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data: response data will be in "data" key


CSV

Response will be in CSV format



 API 2.0: Get Questions

Description

API will fetch all the questions of a specific form or default form for authorized shop and filter the result set according to the parameters.

Functional Call

Get result of specific form

https://smartforms.ekomi.com/api/v2/forms/[form_id]/questions?format=csv

Get result of default form

https://smartforms.ekomi.com/api/v2/forms/questions?format=json

Method:  GET

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters

Parameters

Description

Example

Mandatory

Default

form_id

Above we have two API link, If user will provide form id then he will get result of that form, if user will not provide form id means second API link then API will fetch result with respect to default form.

https://smartforms.ekomi.com/api/v2/forms/342/questions
OR
https://smartforms.ekomi.com/api/v2/forms/questions

optional

default form id of shop

format

In which format user want to get response

json or csv

optional

json

question_type

User can fetch questions with respect to question types
like question_type=short_text,stars etc

short_text, long_text, legal_text, multiple_choice, sub_rating, ranking_scale, yes_no, picture, dropdown, feedback,rating, pros_and_cons, datepicker

optional


expand

If user required questions with all options

options

optional


exclude

This param exclude question types from result set like
exclude=short_text,stars etc

short_text, long_text, legal_text, multiple_choice, sub_rating, ranking_scale, yes_no, picture, dropdown, rating, pros_and_cons, feedback, datepicker

optional







show_conditional_questions

Allows to return conditional questions in response.

Possible values: 1 or 0 

query

1

show_child_questions

Allows to return child questions in response.

Possible values: 1 or 0 


1

show_multiple_question_labels

Allows to return multiple labels of sub-ranking questions

Possible values: 1 or 0 

query

0

show_question_tags

Allows to return tags add with questions.


Possible values: 1 or 0 query

0

The Response will be CSV or JSON.

Error Response Example:

Error Response

{    "error": {     "message": "Form does not exist",     "status_code": 404    }}

Success Response Example:

Json Response

{   "data": [      {         "question_id": 30833,         "question_label": "How many stars would you like to award?",         "question_type": "rating",         "parent_id": 0,         "options": [            {               "option_id": 0,               "option_label": 0,               "linked_question_ids": []            },            {               "option_id": 1,               "option_label": 1,               "linked_question_ids": []            },            {               "option_id": 2,               "option_label": 2,               "linked_question_ids": []            },            {               "option_id": 3,               "option_label": 3,               "linked_question_ids": []            },            {               "option_id": 4,               "option_label": 4,               "linked_question_ids": []            },            {               "option_id": 5,               "option_label": 5,               "linked_question_ids": []            }         ]      },      {         "question_id": 30835,         "question_label": "Would you recommend us to your friends?",         "question_type": "yes_no",         "parent_id": 0,         "options": [            {               "option_id": 9459,               "option_label": "Yes",               "linked_question_ids": [                  30865,                  30866               ]            },            {               "option_id": 9460,               "option_label": "No",               "linked_question_ids": [                  30867,                  30868               ]            }         ]      },      {         "question_id": 30854,         "question_label": "first text question",         "question_type": "short_text",         "parent_id": 0      },      {         "question_id": 30855,         "question_label": "text area question",         "question_type": "long_text",         "parent_id": 0,         "is_conditional_question": "false"      }   ],   "status_code": 200}

CSV

question_id,question_label,question_type,parent_id,option_id,option_label,linked_question_ids
30833,"How many stars would you like to award?",rating,0,0,0,
30833,"How many stars would you like to award?",rating,0,1,1,
30833,"How many stars would you like to award?",rating,0,2,2,
30833,"How many stars would you like to award?",rating,0,3,3,
30833,"How many stars would you like to award?",rating,0,4,4,
30833,"How many stars would you like to award?",rating,0,5,5,
30833,"How many stars would you like to award?",rating,0,6,6,
30833,"How many stars would you like to award?",rating,0,7,7,
30833,"How many stars would you like to award?",rating,0,8,8,
30833,"How many stars would you like to award?",rating,0,9,9,
30833,"How many stars would you like to award?",rating,0,10,10,
30838,reste,ranking_scale,30833,0,0,
30838,reste,ranking_scale,30833,1,1,
30838,reste,ranking_scale,30833,2,2,
30838,reste,ranking_scale,30833,3,3,
30838,reste,ranking_scale,30833,4,4,
30838,reste,ranking_scale,30833,5,5,
30838,reste,ranking_scale,30833,6,6,
30838,reste,ranking_scale,30833,7,7,
30838,reste,ranking_scale,30833,8,8,
30838,reste,ranking_scale,30833,9,9,
30838,reste,ranking_scale,30833,10,10,
30839,dfgdtrg,ranking_scale,30833,0,0,
30839,dfgdtrg,ranking_scale,30833,1,1,
30839,dfgdtrg,ranking_scale,30833,2,2,
30839,dfgdtrg,ranking_scale,30833,3,3,
30839,dfgdtrg,ranking_scale,30833,4,4,
30839,dfgdtrg,ranking_scale,30833,5,5,
30839,dfgdtrg,ranking_scale,30833,6,6,
30839,dfgdtrg,ranking_scale,30833,7,7,
30839,dfgdtrg,ranking_scale,30833,8,8,
30839,dfgdtrg,ranking_scale,30833,9,9,
30839,dfgdtrg,ranking_scale,30833,10,10,
34255,"Pros cons",pros_and_cons,0,,,
30834,"Your personal feedback:",feedback,0,,,
30835,"Would you recommend us to your friends?",yes_no,0,9459,Yes,30865;30866
30835,"Would you recommend us to your friends?",yes_no,0,9460,No,30867;30868
30837,dd,dropdown,0,9461,op,
30837,dd,dropdown,0,9462,op2,
30850,"How was your overall experience?",yes_no,0,9480,"very good",
30850,"How was your overall experience?",yes_no,0,9481,"very bad",
30850,"How was your overall experience?",yes_no,0,9482,"don't want to tell",
30851,"Do you like our products?",yes_no,0,9483,Yes,
30851,"Do you like our products?",yes_no,0,9484,No,
30851,"Do you like our products?",yes_no,0,9485,"I dont know",
30851,"Do you like our products?",yes_no,0,9486,"dont want to tell you",
30852,"Würden Sie uns Weiterempfehlen ?",yes_no,0,9487,Ja,
30852,"Würden Sie uns Weiterempfehlen ?",yes_no,0,9488,Nein,
30852,"Würden Sie uns Weiterempfehlen ?",yes_no,0,9489,Vielleicht,
30853,をお勧めしますか?,yes_no,0,9490,はい,
30853,をお勧めしますか?,yes_no,0,9491,いいえ,
30853,をお勧めしますか?,yes_no,0,9492,多分,
30853,をお勧めしますか?,yes_no,0,9493,後で,
30854,"first text question",short_text,0,,,
30855,"text area question",long_text,0,,,
30856,radio,yes_no,0,9494,a,
30856,radio,yes_no,0,9495,b,
30856,radio,yes_no,0,9496,c,
30856,radio,yes_no,0,9497,d,









RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Format should be json or csv
  • Status Code: 422. Message: Invalid expand param, expand value should be options.
  • Status Code: 422. Message: Specified form is not a product review form..
  • Status Code: 404. Message: form_id is invalid
  • Status Code: 404. Message: This form does not contain [question_type] type questions
  • Status Code: 404. Message: Exclude [question_type] does not exist in system
  • Status Code: 404. Message: This form does not contain [question_type] type questions and Exclude [question_type] does not exist in system
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data: response data will be in "data" key


CSV

Response will be in CSV format

API 2.0 Get questions stats

https://smartforms.ekomi.com/api/v2/questions/{question_id}/stats

METHOD: GET


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Parameters

Description

Mandatory

Default

question_id

Question id

required

integer

product_id

Product id

optional

string

start_date

Refers to question's submission date. Date should be in YYYY-MM-DD format.

optional

string

end_date

Refers to question's submission date. Date should be in YYYY-MM-DD format.

optional

string


API 2.0 Review summary

Implementation Notes

API returns total review count, average rating and rating count for each value of specified shop or form.

Note:The result set of this particular API is being cached for a time duration of 6 hours i.e. the same data set shall be returned on the same query params for 6 hours, no real time data shall be available.

Method: GET

https://smartforms.ekomi.com/api/v2/reviews/summary?form_id=form_id

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required



parameter

Description

Mandatory

Type

form_id

Form id

required

integer

product_id

Product id

optional

string

start_date

Refers to review submission date. Date should be in YYYY-MM-DD format.

optional

string

end_date

Refers to review submission date. Date should be in YYYY-MM-DD format.

optional

string

published

Review status. 
Possible values: 0 or 1

optional

string

withdrawn

Review's withdrawn status. 
Possible values: 0 or 1

optional

string




API 2.0: Get Shop Answers

Description

API to fetch all answers of specified shop or based on review hash provided. In JSON format, results will be shown in paginated style. Pagination links will be provided in response headers (default with 20 records per page).

Functional Call

https://smartforms.ekomi.com/api/v2/answers?format=json

Method: GET


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters

Parameters

Description

Example

Mandatory

Default

format

In which format user want to get response

json or csv

optional

json

start_date

specify the date for which date records are required

2017-02-22

optional

null

end_date

specify the end limit of records date

2017-02-28

optional

null

published

If user wants to filter records by published or unpublished.

published=1 or unpublished=0

optional

all

withdrawn

If user wants to filter records by withdrawn or not withdrawn.

withdrawn=1 or not withdrawn=0

optional

all

review_hash

User can filter answers with respect to review hash

review_hash=xxxxxxxxxxxxxxxxxxxxxx

optional

all

question_type

User can fetch questions with respect to question types
like question_type=short_text,stars etc

short_text, long_text, multiple_choice, ranking_scale, yes_no, picture, dropdown, feedback,rating, pros_and_cons, constant_sum, legal_text, feedback_email, datepicker

optional

all

exclude

This param exclude question types from result set like
exclude=short_text,stars etc

short_text, long_text, multiple_choice, ranking_scale, yes_no, picture, dropdown, rating, pros_and_cons, feedback, datepicker

optional


filter

This param used to filter the positive, negative, neutral or all with respect to main rating

positive or negative or neutral or all
rating greater than 3 is positive, rating equal to 3 is neutral, rating less than 3 is negative.

optional

all

form_id

param for filter response by form id. multi form ids can be given comma (, ) separated.

1,2,3

optional

all

records_per_page

This parameter used to show number of records in one page.

Integer value can 1 to 20.

optional

20

product_id

Product id


optional


order_id

This parameter will be ignored if order_ids given in request


optional


order_ids[]

Order ids filter to get reviews for more than 1 order id. Maximum 10 number of order ids are allowed. 
example input: order_ids[]=123&order_ids[]=xyz.

example input: order_ids[]=123&order_ids[]=xyz.

optional


show_skipped_product_reviews

Parameter to show skipped products reviews. If value is 1 reviews for skipped products will also be show in result. 
Possible values: 0 or 1

Possible values: 0 or 1

optional


page

Page number.
Default: 1

1 or 2 or 3 ...

optional

1

POST-CONDITION


The Response will be CSV or JSON.

Error Response Example:

Error Response

{        "error": {               "message": "Result is not found against that shop",               "status_code": 404        }}











RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Format should be json or csv
  • Status Code: 422. Message: published should be 0 or 1
  • Status Code: 422. Message: Invalid question_type param, Question type(s) are not valid.
  • Status Code: 404. Message: Result is not found against that shop
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data: response data will be in "data" key


CSV

Response will be in CSV format


API 2.0: Get Shop Details

Description

API will fetch all details of a specific authorized shop.

Functional Call

https://smartforms.ekomi.com/api/v2/shops

Method: GET


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters

Parameters

Description

Example

Mandatory

Default

format

In which format user want to get response

json or csv

optional

json

The Response will be CSV or JSON.

Error Response

{    "error": {        "message": "Form does not exist",        "status_code": 404    }}

Success Response

{  "data": {    "shop_interface_id": 665,    "shop_interface_password": "FMJuyuC8uEbo3WxRa5aG"    "shop_submission_delay": "3"  },  "status_code": 200}



CSV

 

shop_interface_id,shop_interface_password

665,FMJuyuC8uEbo3WxRa5aG,3







RESPONSES WITH STATUS CODES


Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Format should be json or csv
  • Status Code: 404. Message: Shop forms does not found!
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data:response data will be in "data" key


"shop_submission_delay" is expressed in days.

  • -1: Unlimited
  • 0: Instant
  • 1 - 31: corresponding delay in days

31 is the max value.


CSV

Response will be in CSV format

API 2.0: Get Shop Forms

Description

API will fetch all the forms of a specific authorized shop with respect to parameters of query string.

Functional Call

https://smartforms.ekomi.com/api/v2/forms

Method: GET

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Request Parameters

Parameters

Description

Example

Mandatory

Default


format

In which format user want to get response

json or csv

optional

json


empty_forms

In case of '0' it will get all forms having at least one question, in case of '1' it will get forms which were not saved with questions and if not set it will get both.

Possible values: 0 or 1

optional



survey_status

Filter response based on survey status 

Possible values: active, inactive or default

optional



status

Filter response based on form status 

Possible values: active, soft_delete or all

optional

active


include

Allows to return additional information in response 

Possible values:callback_form_id,status

optional



survey_id

Survey id


optional



The Response will be CSV or JSON.

Error Response Example:

Error Response

{    "error": {        "message": "Form does not exist",        "status_code": 404    }}

Success Response Example:

Success Response

{        "data": [               {                       "form_id": 879,                       "name": "Image test 1 pro",                       "type": "product",                       "completion_rate": 4,                       "open_rate": 27               },        ],        "status_code": 200}

CSV

form_id,name,type,completion_rate,open_rate

  879,"Image test 1 pro",product,4,27

Responses


Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Format should be json or csv
  • Status Code: 404. Message: Shop forms does not found!
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data: response data will be in "data" key


CSV

Response will be in CSV format

API 2.0 Activity Stream

https://smartforms.ekomi.com/api/v2/forms/activity_stream

METHOD: GET

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required




Parameters

Description

Mandatory

Type


start_date

Refers to form activity stream date. Date should be in YYYY-MM-DD format.

required

string


end_date

Refers to form activity stream date. Date should be in YYYY-MM-DD format.

required

string


order_id

Order id

optional

string


records_per_page

Number of records per page.
Default: 20
Max: 50

optional

integer


page

Page number.
Default: 1

optional

integer














API 2.0 Get Child Survey Form

METHOD: GET

https://smartforms.ekomi.com/api/v2/forms/child

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required



Parameters

Description

Mandatory

Type

parent_form_id

Form id for which child form id will be returned.

required

integer

parent_question_id

Question id for which child question id will be returned.

query

integer


API 2.0 Get Question Detail

METHOD: GET

https://smartforms.ekomi.com/api/v2/questions/{question_id}

Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Parameters

Description

Mandatory

Type

question_id

Question id

required

integer

expand

Allows to return extra meta data associated with question. 
Possible values:'options' or 'child_questions'. 

Value can be multiple separated by comma(,).

optional

string

show_multiple_question_labels

Allows to return multiple labels of sub-ranking questions.
Possible values: 1 or 0 
Default value: 0

optional

string

show_question_tags

Allows to return tags add with questions.
Possible values: 1 or 0 
Default value: 0

optional

string










API 2.0: Review Status

Description

API will approve (a.k.a submission to ekomi) or reject the review of a shop.

Functional Call

https://smartforms.ekomi.com/api/v2/review/status

Method: PUT


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required



Request Parameters

Parameters

Description

Example

Mandatory

Default

review_hash

review hash on which action is going to take place

XXXXXXXXXXXXXXXXXXX

required


status

Api will change status of review approved or rejected

approved, rejected

required


The Response will be CSV or JSON.

Error Response

{    "error": {     "message": "Review does not exist",     "status_code": 404    }}

Success Response Example:

JSON

Success Response

{        "data": [               {                       "message": "Review has been successfully updated",               },        ],        "status_code": 200}

Responses

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Review hash or order id is required!
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Status should be approved or rejected
  • Status Code: 422. Message: Review hash is missing
  • Status Code: 422. Message: This review has already been published
  • Status Code: 422. Message: This review has already been rejected
  • Status Code: 404. Message: Review does not exists
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data:response data will be in "data" key

API 2.0: Thankyou Page Clicks Stats

Description

API returns stats of links clicked on thankyou page of review forms. Stats can be filter by form_id or review_hash, if no filter added, stats of default form of shop will be returned.

Functional Call

https://smartforms.ekomi.com/api/v2/thankyou/clicks

Method: GET

Parameters

Parameters

Description

Example

Mandatory

Default

form_id

Form id for which stats required

123

optional


review_hash

Review hash for which stats required

XXXXXXXXXXXXXXXXXXX

optional



Post-Condition

The Response will be CSV or JSON.

Error Response

{    "error": {        "message": "There are no records against provided inputs",        "status_code": 404    }}

Success Response

{    "data": {        "status": "success",        "result": [            {                "url": "http://www.yahoo.com",                "count": 5            },                       {                "url": "http://www.google.com",                "count": 3            }        ]    },    "status_code": 200}

RESPONSES WITH STATUS CODES


Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: review_hash or form_id is not valid.
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 404. Message: There are no records against provided inputs

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data: response data will be in "data" key


API 2.0: Update Review

Description

API is to update reviews. API will validate the review and put request in processing and update the review for given feedback id in smart forms, other wise give appropriate validation error.

Functional Call

https://smartforms.ekomi.com/api/v2/reviews/{feedback_id}

Method: PATCH


Request Headers

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop password

FMJuyuC8uEbo3WxRa5aG

required



Request Parameters

Parameters

Description

Example

Mandatory

Default

feedback_id

Id of review

1234

required


JSON

JSON object in request body

example given below in "JSON Structure and Parameters"

required



JSON Structure and Parameters

Parameters

Description

Example

Mandatory

Default

status

Status will identify the action that will be performed on given  feedback

1234

required


reviews

reviews contain array.

question_id integer value (question ID)

answer string value

Questions of the given feedback will be updated with answers given in reviews. If reviews is not given in json or empty the action given in status will be performed on feedback without making any change in feedback records

[ {  "question_id": 31813,  "answer": "test review" }, {  "question_id": 31823,  "answer": "3" }]

optional


Sample Json objects

Raw Json structure

Seller / Market reseach

{  "status": "published",  "reviews": [    {      "question_id": 37370,      "answer": "3",      "children": [        {          "question_id": 37395,          "answer": "test@testAPI.test"        }      ]    },    {      "question_id": 37371,      "answer": "another modified answer value goes here"    }  ]}

API Response

The Response will be JSON.

Success Response Example:

Success Response

{        "message":"Request has been accepted for processing",        "status_code":202}


Error Response Example:

Error Response

{    "error": {     "message": "Status is required",     "status_code": 422    }}

RESPONSES WITH STATUS CODES

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 422. Message: Something went wrong, please try again later.

  • Status Code: 409. Message: Feedback already approved.
  • Status Code: 409. Message: Feedback already delivered to Ekomi.
  • Status Code: 422. Message: This feedback is not submitted to CFM2.0 yet.

·       Status Code: 422. Message: Status should be published or rejected

·       Status Code: 409. Message: Feedback already rejected.

  • Status Code: 422. Message: Syntax error, malformed JSON.
  • Status Code: 422. Message: Feedback id is invalid.
  • Status Code: 422. Message: CFM-2.0 is not enabled for this shop.
  • Status Code: 422. Message: question_id and answer are the keys for array, given keys are not correct
  • Status Code: 422. Message: Question ID: 123 does not belong to this Form
  • Status Code: 422. Message: Option ID: 123 does not belong to this Form
  • Status Code: 422. Message: Option ID and Option value does not set properly
  • Status Code: 422. Message: Duplicate question ID found
  • Status Code: 422. Message: The given value is not according to range for question ID (123)
  • Status Code: 422. Message: The question ID (123) range is 1-5 and given value is not according to range
  • Status Code: 422. Message: Minimum 123 characters are required for question ID (123)
  • Status Code: 422. Message: The given content is not array, expected array for question ID (123)
  • Status Code: 422. Message: The given content is array, expected string for question ID (123)
  • Status Code: 422. Message: The given content keys (pros and cons) are not correct for question ID (123)
  • Status Code: 422. Message: Please add valid JSON format for product, review not found
  • Status Code: 404. Message: Shop ID authorization parameter is missing
  • Status Code: 404. Message: Shop password authorization parameter is missing
  • Status Code: 404. Message: Shop authorization parameter is missing
  • Status Code: 401. Message: Shop authorization parameter is invalid

status_code

number

Status code of response, 202 in case of successful review creation. In case of error, status code will be given in "error" key.

object

JSON

In case of success, message will be given in "message" key.

·       Status Code: 202

  • Message: Request has been accepted for processing


API 2.0: Withdraw Review

Description

API will withdraw review and generate new submission review link for new submission.

Functional Call

Get result of specific shop

https://smartforms.ekomi.com/api/v2/answers/withdraw

Method: PUT


Headers

Pre-Condition

Parameters

Description

Example

Mandatory

Default

interface-id

Interface or shop Id665

required


interface-password

Interface or shop passwordFMJuyuC8uEbo3WxRa5aG

required


Parameters

Pre-Condition

Parameters

Description

Example

Mandatory

Default

review_hash
or
order_id

review hash or order id for withdraw that review

XXXXXXXXXXXXXXXXXXX

required



Post-Condition

The Response will be CSV or JSON.

Error Response Example:

{

    "error": {

     "message": "Review does not exist",

     "status_code": 404

    }

}

Success Response Example:

JSON

{

    "data": [

                  {

                     "submission_link": http://smartforms.ekomi.com/review/[shop_id]/[review_hash]?fid=form_id,

                  },

    ],

    "status_code": 200

}

Responses with status codes


Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

·       Status Code: 500. Message: Something went wrong, please try again later.

  • Status Code: 422. Message: Review hash or order id is required!
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 404. Message: New hash is not generated for this review
  • Status Code: 404. Message: Review does not exists

status_code

number

Status code of response, 200 in case of successful creation. In case of error, status code will be given in "error" key.

data

JSON

In case of success, data will be given in "data" key.

·       Status Code: 200. Data:response data will be in "data" key

API 3.0 Get answers

https://smartforms.ekomi.com/api/v3/answers

Parameter

Description

Parameter Type

Data Type

interface-id

Shop id

header

integer

interface-password

Interface Password

header

string

format

Response output format. 
Possible values: json or csv
Default: json

query

string

form_id

Form id 
Multiple form ids can be given comma (,) separated.

query

string

product_id

Product id

query

string

start_date

Refers to review submission date. Date should be in YYYY-MM-DD format.

query

string

end_date

Refers to review submission date. Date should be in YYYY-MM-DD format.

query

string

published

Review status. 
Possible values: 0 or 1

query

string

withdrawn

Review's withdrawn status. 
Possible values: 0 or 1

query

string

order_ids[]

Order ids filter to get reviews for more than 1 order id. Maximum 10 number of order ids are allowed. 
example input: order_ids[]=123&order_ids[]=xyz.

query

Array[string]

question_type

Question type(s) to fetch in response. 
Possible values:short_text, long_text, multiple_choice, ranking_scale, yes_no, picture, dropdown, feedback,rating, pros_and_cons, constant_sum, datepicker

Multiple question types accepted separated by comma(,). like question_type=short_text,rating.

query

string

exclude

Question type(s) to exclude from response. 
Possible values:short_text, long_text, multiple_choice, ranking_scale, yes_no, picture, dropdown, feedback,rating, pros_and_cons, constant_sum, datepicker

Multiple question types accepted separated by comma(,). like exclude=short_text,rating.

query

string

filter

Filter positive, negative and neutral rating.
>3 = positive
<3 = negative
=3 = neutral

query

string

question_tag

Filter to fetch questions with specific question tag in response.

query

string

show_skipped_product_reviews

Parameter to show skipped products reviews. If value is 1 reviews for skipped products will also be show in result. 
Possible values: 0 or 1

query

string

records_per_page

Number of records per page.
Default: 20
Max: 20

query

integer

page

Page number.
Default: 1

query

integer

Parameters

Implementation Notes

API to fetch all answers of specified shop. Response will be paginated. Pagination links will be provided in response body and response headers.
Default:20 records per page.


3. SmartReviewRequest API

Add Recipient API

This API takes shop and recipient information and adds the recipient against the given shop in “Smart Review request” (SRR) system. If the given shop does not exist in SRR, it creates shop with default customer segment (Reviews) and default campaigns of type email, telephone and sms

https://srr.ekomi.com/add-recipient

Request Detail

Request Type: POST

Parameters

Description

Mandatory

recipient_type

Desired medium for taking feedback from recipient.

Possible Values: 

  • email
  • telephone
  • sms

Optional. Default is "email"

shop_id

Ekomi shop id

Required

password

Shop Password 

Required

salutation

Salutation of recipient

Optional

first_name

First name of recipient

Optional 

last_name

Last name of recipient

Optional

email

Email of recipient. If email has special characters then use URL encoded email.

Required only if the recipient_type is "email" or for AFNOR

transaction_id

Transaction id

Required

transaction_time

Transaction time in UTC. The transaction time stamp if given is passed to ekomi core via putOrder API

Allowed Formats

  • yyyy-mm-dd HH:ii:ss
  • dd-mm-yyyy HH:ii:ss

Optional (Required for AFNOR)

has_products

Flag indicating whether the products information is required or not.

  • If 0, it ignores the product information
  • If 1, it takes product information and do product reviews.

Optional. Default is 0

products_info

JSON containing products information with product id as key and product name as value

Example:

{     "33244":"test product 1",   "43t553":"test_product_2",   "s34472":"pro2"}

Cases:

  • When the product is not registered in SRR, the system will register it using put Product API on the cron execution
  • When the product is registered in SRR and no change is detected in product information, put product API is not called
  • When the product is registered in SRR and any change is detected in the product information, following scenarios are possible
    • If shop setting for update product is enabled, put Product is called with the updated product information to re-register product. Information is also updated in SRR
    • If shop setting for update product is disabled, put Product is not called.Information is not updated in SRR

Required if has_products is set to 1

telephone

Telephone of recipient. For SMS, number format should be E-164.

Required only when recipient_type is "telephone" or "sms"

sender_name

Name of a sender. Parameter is used only when the recipient is created against shop that does not already exist in SRR

  • In case of email:
    Default is "no-reply".
  • In case of sms
    • Default is eKomi
    • Maximum characters allowed by twilio is 11. If more than 11 characters are given then only first 11 characters are validated and saved as sender name.
    • Only letters, numbers and spaces are allowed but with at least one letter.

Optional

sender_email

Email of a sender. Parameter is used in default email campaign as sender email only when recipient is created against shop that does not already exist in SRR

Default for live: reviews@feedback-ekomi.com 

Default for AXA: ihreerfahrungmitaxa@ekomi.de

Optional

products_other

JSON containing product id as key and product meta as value. Product meta can contain information like product_canonical_link, product_other, etc. "product_other" is a JSON object.

Sample:

{  "65212142": {    "product_canonical_link": "google.com",    "product_other": {      "image_url": "http:\\xyz.de",      "brand_name": "xyz",      "product_ids": {        "mpn": "321",        "upc": "123",        "ean": "456456",        "isbn": "123",        "gbase": "123"      },      "links": [        {          "rel": "canonical",          "type": "text/html",          "href": "http://www.example.com/view_product-12"        },        {          "rel": "related",          "type": "image/(gif|jpg)",          "href": "http://www.example.com/images/thisProduct_fullsi\n\t\tze.gif"        },        {          "rel": "related2",          "type": "image/(gif|jpg)",          "href": "http://www.example.com/images/thisProduct_fullsi\n\t\tze.gif"        }      ],      "categories": [],      "meta_matrix": ""    }  }}

 Here 65212142 is the product id and the linked JSON is the product meta

Note:  Product id must be present in products_info JSON

Optional

project_name

Project (Customer Segment) in which the recipient needs to be added.

Optional. If empty, the recipient will be added in default customer segment i.e. "Reviews"

days_of_deletion

Number of days after which the recipient will be forcely deleted from the system if he does not give feedback

Not being used anymore.

Optional. Default is 30

meta_data

  • JSON containing meta data of recipients.
  • Key and value of JSON can not contain more than 255 characters otherwise the remaining characters will be truncated.

·       Nested JSON is also allowed but it will be stored as <parent_key>_<child_key> : <child_value>
Samples:

·       {  ·          "this":"that",·          "something":"anything",·          "blub":"bla"·       }·       {  ·          "this":"that",·          "something":"anything",·          "blub":{  ·             "this":"that",·             "something":"anything",·             "blub":"bla"·          }}
  • The nested JSON of above sample will be stored as "blub_this" => "that", "blub_something" => "anything", "blub_blub" => "bla"

Optional

client_id

Client id for recipient

Optional (Required for AFNOR)

screen_name

Screen name for recipient

Optional

is_afnor

Possible values

  • true
  • false

Cases

  • If "client_id" is given and "is_afnor" is either not given or is false, "email" and "transaction_time" becomes optional
  • If "client_id" is given and "is_afnor" is "true", "email" and "transaction_time" becomes mandatory
  • If "client_id" is not given and "is_afnor" is either not given or is false, no putClient ad assignClientOrder API is called
  • If "client_id" is not given and "is_afnor" is "true", "client_id" becomes mandatory

Optional. Default is false

Response Detail

Response Type: JSON

Parameters

Type

Values

status

string

Possible Values:

  • success
  • error

message

string

In case of success, ‘ Recipient is added successfully’ will be returned.

 In case of errors, following error message will be returned

  • Something went wrong
  • Any required parameter is missing
  • Recipient email is not valid
  • Sender email is not valid
  • Transaction timestamp is not correct
  • Value for has_products can only be 0 or 1
  • Product info should be a valid json with product id as key and product name as value
  • Id or name is missing for any product
  • Password is not correct
  • Shop is not recognized by ekomi
  • Unable to validate shop from ekomi.Try again
  • The given transaction id is already used
  • Problem registering products
  • Recipient is not added
  • Product id or name can not contain HTML or array
  • The recipient type must be email,telephone or sms
  • The meta data provided is not valid json
  • The days must be numeric and greater than zero
  • The telephone number is not valid
  • The mobile number is not valid
  • The mobile number format is not valid
  • Project with given name does not exist
  • Invalid json given for product others
  • Sender name is not valid. Only letters, Numbers and Spaces are allowed but with at least one letter, Maximum characters allowed by twilio is 11. If more than 11 characters are given then only first 11 characters are validated and saved as sender name
  • Recipient not added due to failure by rule
  • Recipient not added as the user has already unsubscribed
  • Shop is suspended. Please contact us at support@ekomi.com for further details.
  • Sms are disabled

data

array

null, in case of error.
associative array, in case of success:

  • key : srr_recipient_id,value : id of the recipient added
  • key : srr_recipient_type,value : type of the recipient added (email/telephone/sms)

key

integer

  • 00 - success,
  • 01 - general error,
  • 02 - required parameter missing,
  • 03 - recipient email is invalid,
  • 04 - transaction timestamp is not correct,
  • 05 - Password is not correct,
  • 06 - Shop not recognized by ekomi,
  • 07 - recipient not added
  • 08 - id or name missing for any product in products information
  • 09 - transaction id already used
  • 10 - all products not registered
  • 11 - invalid value for has_products flag
  • 12 - products info is not array
  • 13 - sender email is invalid
  • 14 - invalid recipient type
  • 15 - invalid meta data
  • 16 - incorrect days of deletion
  • 17 - invalid telephone/mobile number
  • 18 - given project does not exist
  • 19 - product others invalid json
  • 22 - invalid sender name in case of sms type.
  • 26 - recipient is not added due to failure by rule
  • 27 - recipient is not added as the user has already unsubscribed and as per the project settings,no further emails will be sent to the unsubscribed recipient
  • 28 - invalid parameter value type
  • 29 - wrong value of is_afnor. The value for is_afnor can be either true or false
  • 30 - sms are disabled

Response Samples

Success Response

{    "status": "success",    "data": {        "srr_recipient_id": <recipient id>,        "srr_recipient_type": <recipient type - "email" / "telephone" / "sms">    },    "key": 0,    "message": "Recipient is added successfully"}

Error Response

{     "status":"error",   "key":<custom error code>,   "message":<error message>,   "data":null}

Get Project Stats API

This API returns the last recipient added and basic stats about the specified project's campaign (if not provided then for the Default project i.e. Reviews) and the default campaign of the specified type in the relevant project. The information includes the total orders (recipients) and latest order details against the project and the total email/SMS sent,open rate and review rate against the default campaign of the specified project.

https://srr.ekomi.com/api/project-stats

Request Detail

Request type: GET

Parameters

Description

Mandatory

shop_id

Ekomi shop id

Required

project_name

Name of Project

Optional. 

Default: "Reviews"

type

Type of Campaign.

Possible Values

  • email
  • sms

Optional

Default: "email"

Response Detail

Response Type: JSON

Parameters

Type

Values

status

string

Possible Values

  • success
  • error

message

string

In case of errors, following error message will be returned

  • Something went wrong
  • Shop id is missing
  • Invalid type.It should be either email or SMS
  • Shop not found
  • Invalid Project Name
  • Shop is suspended. Please contact us at support@ekomi.com for further details.

data

json

null, in case of error.
JSON object in case of success:

  • Key: total_emails_sent, Value: Number of emails sent in the default campaign
  • Key: total_opens, Value: Number of emails opened in the default campaign
  • Key: total_reviews, Value: Number of reviews done in the default campaign
  • Key: total_orders, Value: Number of orders (recipients) in the project
  • Key: latest_order, Value: json object containing latest order information in the project like order_id, created_at, first_name, last_name, email,telephone

key

integer

  • 00 - success,
  • 01 - general error
  • 18 - given project does not exist
  • 20 - shop not found
  • 21 - invalid campaign type
  • 23 - shop id missing

Response Samples

Success Response for Email

{    "status": "success",    "key": 0,    "message": "",    "data":  {        "total_orders": 29,        "latest_order": {            "order_id": "srr-5751018-1484306121",            "created_at": "2017-01-13 11:15:21",            "first_name": "wahid",            "last_name": "",            "email": "abdul.wahid@coeus-solutions.de",            "telephone": ""        },       "total_emails_sent": 17,       "total_opens": 4,       "total_reviews": 2    }}

Success Response for SMS

{    "status": "success",    "key": 0,    "message": "",    "data": {        "total_orders": 1,        "latest_order": {            "order_id": "srr-5920827-1483615719",            "created_at": "2017-01-05 11:28:39",            "first_name": "wahid",            "last_name": "",            "email": "abdul.wahid@coeus-solutions.de",            "telephone": "+123456789"        },    "total_sms_sent": 1    }}


Error Response

{    "status": "error",    "key": <custom error code>,    "message": <error message>,    "data": null}


Get Recipient Detail API

This API will fetch detail of recipient and its meta data from given review hash or order id. If both review hash and order Id is given, review hash will be ignored.

https://srr.ekomi.com/api/v1/recipients/orders

Request Detail

Request type: GET

Parameters

Description

Example

Mandatory

Default

shop

Shop Interface id and interface password separated by pipe sign "|".

1234|123456789abc1

Required

None

order_id

URL encoded order_id of recipient.

srr-3451767-1482217875

Required if review_hash is not given

None

review_hash

URL encoded review_hash of recipient. If order_id is provided, then review_hash will be ignored.

0df0ba37a1e56e762156225e8ca3eb33

Required if order_id is not given

None

include_product_info

Boolean value to get Products information in response.

1

Optional. Products information will only be returned when this param has value 1.

None

Response Detail

Response Type: JSON

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

  • Status Code: 500. Message: Something went wrong, please try again later.
  • Status Code: 422. Message: Shop Id is missing.
  • Status Code: 422. Message: Shop Password is missing.
  • Status Code: 422. Message: Order id or Review hash is required.
  • Status Code: 404. Message:  Shop id does not exist.
  • Status Code: 404. Message:  Shop password is incorrect.
  • Status Code: 404. Message:  Recipient does not exist.
  • Status Code: 401. Message:  Shop is suspended. Please contact us at support@ekomi.com for further details.

status_code

number

Response Status code. In case of error, status code will be given in "error" key. 200 is returned in case of successful retrieval. 

Possible Values:

  • 200
  • 401
  • 404
  • 422
  • 500

data

JSON

In case of success, data will be given in "data" key.

  • Not present in case of error.

·       Status Code: 200. Data: response data will be in "data" key:

    • Key: first_name, Value: First Name of Recipient
    • Key: last_name, Value: Last Name of Recipient
    • Key: email,  Value: Email of Recipient
    • Key: telephone,  Value: Telephone of Recipient
    • Key: transaction_time,  Value: Transaction Time of Recipient
    • Key: meta_data, Value: Meta Data has client_id screen_name and other key value pair of recipient meta data
    • Key: products_info, Value: Products Info has key value pairs. Product Ids as keys and Product Names as values
    • Key: products_other, Value: Products Other has other available information. Keys are Products Ids and value contains information.

Response Samples

Success Response

{     "data":{        "first_name":"test243",      "last_name":"user",      "email":"test7@coeus-solutions.de",      "telephone":"",      "order_id":"srr-8153534-1476699486",      "review_hash":"a60bfc79c33dc34d3bbda26cb0bc8c28",      "transaction_time":"2015-07-08 10:07:00",      "meta_data":null,      "products_info":null,      "products_other":null,    },   "status_code":200}

Error Response

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Re-Register Recipient API

This API will do following steps :

  • Get recipient from given review hash or order id against the given shop. If both review hash and order id is given, order id will be ignored.
  • Create a duplicate recipient with new order id which is generated after appending UTC time at the end of source recipient order id
  • Send instant email / SMS to newly created recipient.
  • Return review hash and product hash of new recipient

URL Example

https://srr.ekomi.com/api/v1/recipients

Request Detail

Request type: POST

Parameters

Description

Example

Mandatory

Default

shop

Shop Id

1234|1234567890abc1

Required

None

action

Action for API

Action for Re Register API is "re-register"

i.e. action = re-register

Required

None

order_id

URL encoded order id of recipient. If review_hash is given, order_id will be ignored

srr-3451767-1482217875

Required if review_hash is not given

None

review_hash

URL encoded review hash of recipient

0df0ba37a1e56e762156225e8ca3eb33

Required if order_id is not given

None

Response Detail

Response Type: JSON

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

  • Status Code: 500. Message: Something went wrong.Please try again later
  • Status Code: 422. Message: Shop Id is missing.
  • Status Code: 422. Message: Shop Password is missing.
  • Status Code: 422. Message: Action is required.
  • Status Code: 422. Message: Action is incorrect.
  • Status Code: 422. Message: Order id or Review hash is required.
  • Status Code: 422. Message: Shop information is missing
  • Status Code: 404. Message: Recipient does not exist.
  • Status Code: 404. Message: Shop not found
  • Status Code: 500. Message: Error in registering recipient.Please try again!
  • Status Code: 401. Message: Shop is suspended. Please contact us at support@ekomi.com for further details.

status_code

number

Response Status code . In case of error, status code will be given in "error" key. 200 is returned in case of successful creation. 

Possible Values

  • 200
  • 401
  • 404
  • 422
  • 500

data

JSON

In case of success, data will be given in "data" key.

  • Not present in case of error.

·       Status Code: 200. Data: response data will be in "data"

    • Key: review_hash, Value: Review hash of newly created recipient
    • Key: product_hash, Value: Product hash of recipients's products (only provided if product_id is not empty)

Response Samples

Success Response with Product Hash

{  "data": {    "review_hash": "e36b74abbc6f4b50f19598ab1b876269",    "product_hash": "YToxOntzOjk6ImFtaW5kZGEyNCI7aToxO30="  },  "status_code": 200}

Success Response without Product Hash

{  "data": {    "review_hash": "4cce8ad7313bc40e7d9ad2c796c0bc46",     },  "status_code": 200}

Error Response

{  "error": {        "message": <error-message>,       "status_code": <status-code>    }}

Create Account

This API allows the creation of a shop / account in SRR which will inherit the email service settings and all the projects settings from the reference shop. This excludes the A/B testing settings. 

https://srr.ekomi.com/api/v1/shops/create

Request Detail

Request type: POST

Parameters

Description

Example

Mandatory

Default

shop_id

Id of shop which is to be created

1234

Required

None

shop_password

Password of shop which is to be created

123456789abc0

Required

None

reference_shop_id

Reference Shop id

4321

Required

None

reference_shop_password

Reference Shop Password

987654321xyz01

Required

None

Response Detail

Response Type : JSON

Parameters

Type

Values

message

JSON

In case of errors, message will be given in "error" key.

  • Status Code: 500. Message: Something went wrong, please try again later.

·       Status Code: 500. Message: Shop not created, please try again later

  • Status Code: 422. Message: Shop id is missing
  • Status Code: 422. Message: Shop password is missing
  • Status Code: 422. Message: Reference shop id is missing
  • Status Code: 422. Message: Reference shop password is missing
  • Status Code: 409. Message: Shop you are trying to create already exists
  • Status Code: 404. Message: Reference shop does not exist

·       Status Code: 201. Message: Shop created with reference shop settings

  • Status Code: 401. Message: Reference shop is suspended. Please contact us at support@ekomi.com for further details.

status_code

number

Response Status code of. In case of error, status code will be given in "error" key. 201 is returned in case of successful creation. 

Possible Values

  • 201
  • 401
  • 404
  • 422
  • 500

Response Samples

Success Response

{    "message": "Shop created with reference shop settings",    "status_code": 201}

Error Response

{    "error": {        "message": <error message>,        "status_code": <error code>     }}


Get Campaign Detail API

This will return Campaign detail by id

https://srr.ekomi.com/api/v1/campaigns/{campaign_id}

Request Detail

Request Type : GET

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

campaign_id

Campaign id

Required

Path

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the detail against the given campaign id

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response For Email Campaign

{    "data": {        "id": 7,        "name": "testing",        "description": "task 212",        "type": "email",        "status": "active",        "is_default": true,        "sender_name": "zain ali bbcd",        "sender_email": "reviews@feedback-ekomi.com",        "reply_to": "",        "is_feedback_only": false,        "is_instant": false,        "feedback": {            "interval": 0,            "subject": "Feedback Email",            "content": "\"<p>dgsgsdfg<\\/p>\\r\\n\""         },         "reminder1": {             "interval": 1,             "subject": "reminder 1",             "content": "\"<p>sdfsdf<\\/p>\\r\\n\""         },        "reminder2": {            "interval": 1,            "subject": "Reminder 2",            "content": "\"<p>fsdfsdf<\\/p>\\r\\n\""        },       "reminder3": {           "interval": 1,           "subject": "reminder-3",           "content": "\"<p>sdfsdf<\\/p>\\r\\n\""       },       "thankyou": {            "subject": "Thank you",            "content": "\"<p>dsfsdf<\\/p>\\r\\n\""        },        "created_at": "2015-11-05T14:45:22Z"     },    "status_code": 200}

Success Response For SMS Campaign

{    "data": {        "id": 12,        "name": "SMS_outbound_camp1",        "description": "SMS_camp1 ; test campaign",        "type": "sms",        "sms_method": "outbound",        "status": "active",        "is_default": true,        "is_instant": false,        "sender_name": "",        "feedback": {            "interval": 0,            "content": "123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123456789 123 *|REVIEW_URL|*"         },        "created_at": "2016-06-01T08:40:18Z"     },    "status_code": 200}

Error Response

{    "error": {        "message": <error message>,        "status_code": <error code>     }}

Get Campaigns API

This will return Campaigns of a Customer Segment. If there are more than 20 records, pagination links will be available in response headers.

https://srr.ekomi.com/api/v1/campaigns

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

Default

shop-id

Shop id

Required

Header

None

interface-password

Interface Password

Required

Header

None

type

Campaign type.
Possible values

  • email
  • sms
  • telephone

Optional

Query

If no type is provided then all types will be returned

customer_segment_id

Customer segment id

Optional

Query

If no Customer Segment ID is provided then default customer segment will be used

status

Campaign status.
Possible values

  • active
  • inactive

Optional

Query

If no status is provided then all statuses will be returned

records_per_page

Number of records per page

Optional

Query

20

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the campaigns against customer segment

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response

{  "data": [    {      "id": 1,      "name": "Default Campaign",      "description": "Default Campaign",      "type": "email",      "status": "active",      "is_default": true,      "created_at": "2018-02-06T10:53:57Z"    },    {      "id": 2,      "name": "Default SMS Campaign",      "description": "Default SMS Campaign",      "type": "sms",      "status": "active",      "is_default": false,      "created_at": "2018-02-06T10:53:57Z"    },    {      "id": 3,      "name": "Default Telephone Campaign",      "description": "Default Telephone Campaign",      "type": "telephone",      "status": "active",      "is_default": false,      "created_at": "2018-02-06T10:53:57Z"    }  ],  "status_code": 200}

Error Response

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Get Customer Segments API

This will return Customer Segments of a Shop. If there are more than 20 records, then pagination links will be available in Response Headers.

https://srr.ekomi.com/api/v1/customer-segments

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

Default

shop-id

Shop id

Required

Header

None

interface-password

Interface Password

Required

Header

None

status

Status of Customer Segment.
Possible values

  • active
  • inactive

Optional

Query

If no status is provided then all statuses will be returned

records_per_page

Number of records per page

Optional

Query

20

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the customer segments of a shop

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response

{  "data": [    {      "id": 1,      "name": "Test project",      "description": "Test1",      "status": "active",      "is_default": false,      "created_at": "2015-11-04T06:58:18Z"    },    {      "id": 2,      "name": "load test",      "description": "load test",      "status": "inactive",      "is_default": false,      "created_at": "2015-11-16T12:45:46Z"    }  ],  "status_code": 200}

Error Response

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Update Blacklist Rules API

This will update blacklist rules of a Customer Segment.

https://srr.ekomi.com/api/v1/customer-segments/{customer_segment_id}/blacklist-rules

Request Detail

Request Type: PATCH

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

customer_segment_id

Customer Segment id

Required

Path

data

Valid json containing comma separated value of blacklist rules to update.

Sample
{"blacklist_rules":"example.com,abc@mail,xyz"}

Required

Query

Response Detail

Response Type: JSON

Parameters

Type

Values

status_code

Number

Response status code. 200 in case of successful update. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason:Successful response

Status Code: 401. Reason:Unauthorized shop

Status Code: 404. Reason:Entity not found

Status Code: 422. Reason:Validation error

Status Code: 500. Reason:Server side error

message

String

Success / error message

Response Samples

Success Response

{  "message": "Blacklist rules updated successfully",  "status_code": 200}

Error Response

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Get Recipients API

This will return Recipients of a Customer Segment. If there are more than 20 records, then pagination links will be available in Response Headers.

https://srr.ekomi.com/api/v1/recipients

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

Default

shop-id

Shop id

Required

Header

None

interface-password

Interface Password

Required

Header

None

customer_segment_id

Customer segment id

Optional

Query

If no Customer Segment ID is provided then default customer segment will be used

detail

Detail of recipient.
Possible values: true, false.

Optional

Query

false

start_date

Filter on recipient's creation date.

Valid format: YYYY-MM-DD

Mandatory if end date is also provided.

Query

None

end_date

Filter on recipient's creation date.

Valid format: YYYY-MM-DD

Mandatory if start date is also provided.

Query

None

recipient_type

Recipient type.
Possible values: email, sms, telephone.

Optional

Query

If no type is provided then all types will be returned

workflow_status

Workflow status.
Possible values: not_started, started, completed, interrupted.

Optional

Query

If no workflow status is provided then all statuses will be returned

subscription_status

Subscription status.
Possible values:subscribed, unsubscribed.

Optional

Query

subscribed

records_per_page

Number of records per page.

Optional

Query

20

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the recipient of a customer segment

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response when "detail" is "true"

{  "data": [    {      "order_id": "LiveTest-01",      "review_hash": "0d79973f624a50049262d966f5697518",      "created_at": "2018-04-10T10:02:45Z",      "recipient_type": "sms",      "detail": {        "first_name": "Mavra",        "last_name": "Yasmin",        "email": "mavra.yasmin@coeus-solutions.de",        "telephone": "+923344011894",        "review_status": "pending",        "workflow_status": "completed",        "workflow_interrupted_reason": "",        "review_given_at": "",        "feedback_scheduled_at": "",        "sms_segments": 1      }    },    {      "order_id": "LiveTest-02",      "review_hash": "5e5662ed0d54136928013a23be1682cd",      "created_at": "2018-04-10T10:02:58Z",      "recipient_type": "email",      "detail": {        "first_name": "Mavra",        "last_name": "Yasmin",        "email": "mavra.yasmin@coeus-solutions.de",        "telephone": "923344011894",        "review_status": "pending",        "workflow_status": "started",        "workflow_interrupted_reason": "",        "review_given_at": "",        "feedback_scheduled_at": ""      }    },        {      "order_id": "LiveTest-04",      "review_hash": "2bfcd24b2e784aec4970fab1eda7f81c",      "created_at": "2018-04-10T10:03:08Z",      "recipient_type": "email",      "detail": {        "first_name": "Mavra",        "last_name": "Yasmin",        "email": "mavra.yasmin@coeus-solutions.de",        "telephone": "923344011894",        "review_status": "given",        "workflow_status": "completed",        "workflow_interrupted_reason": "",        "review_given_at": "2018-04-10T10:14:45Z",        "feedback_scheduled_at": ""      }    }      ],  "status_code": 200}

Success Response when "detail" is "false"

{  "data": [    {      "order_id": "LiveTest-01",      "review_hash": "0d79973f624a50049262d966f5697518",      "created_at": "2018-04-10T10:02:45Z",      "recipient_type": "sms",      "detail": {        "first_name": "",        "last_name": "",        "email": "",        "telephone": "",        "review_status": "",        "workflow_status": "",        "workflow_interrupted_reason": "",        "review_given_at": "",        "feedback_scheduled_at": "",        "sms_segments": ""      }    },    {      "order_id": "LiveTest-02",      "review_hash": "5e5662ed0d54136928013a23be1682cd",      "created_at": "2018-04-10T10:02:58Z",      "recipient_type": "email",      "detail": {        "first_name": "",        "last_name": "",        "email": "",        "telephone": "",        "review_status": "",        "workflow_status": "",        "workflow_interrupted_reason": "",        "review_given_at": "",        "feedback_scheduled_at": ""      }    },        {      "order_id": "LiveTest-04",      "review_hash": "2bfcd24b2e784aec4970fab1eda7f81c",      "created_at": "2018-04-10T10:03:08Z",      "recipient_type": "email",      "detail": {        "first_name": "",        "last_name": "",        "email": "",        "telephone": "",        "review_status": "",        "workflow_status": "",        "workflow_interrupted_reason": "",        "review_given_at": "",        "feedback_scheduled_at": ""      }    }      ],  "status_code": 200}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Get Recipient Activity Stream API

This will return Activity Stream of Recipients.
Possible values for workflow_status in response

  • not_started
  • started
  • completed
  • interrupted

Possible values for interrupted_reason in response:

  • sms-undelivered
  • hard-bounce
  • soft-bounce
  • spam
  • unsubscribe
  • consent-not-received

https://srr.ekomi.com/api/v1/recipients/activity_stream

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

Default

shop-id

Shop id

Required

Header

None

interface-password

Interface Password

Required

Header

None

start_date

Filter on recipient's last activity date.
Only data for 6 months will be shown
Valid format: YYYY-MM-DD

Required

Query

None

end_date

Filter on recipient's last activity date.
Only data for 6 months will be shown
Valid format: YYYY-MM-DD

Required

Query

None

campaign_id

Campaign id

Optional

Query

If no Campaign ID is provided, then data against the default customer segment will be returned regardless of the recipient type

meta_data

JSON containing recipient's meta data.
Example:
{"client_id":"10011","screen_name":"test"}

Optional

Query

None

order_id

Order ID of Recipient.

Optional

Query

None

records_per_page

Number of records per page.

Optional

Query

20

page

Page Number

Optional

Query

1

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the recipient activity stream information

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

meta

JSON

Contains information like pagination, total records, current page,etc

Response Samples

Success Response

{  "data": [    {      "order_id": "104",      "campaign_id": 1,      "workflow_status": "completed",      "interrupted_reason": "",      "created_at": "2018-02-07T14:58:28Z",      "updated_at": "2018-02-26T09:02:21Z",      "sent_at": "2018-02-26T09:02:21Z",      "delivered_at": "2018-02-26T09:02:21Z",      "dispatched_at": "2018-02-26T09:02:21Z",      "sent_by_service": "2018-02-26T09:02:21Z",      "opened_at": "",      "clicked_at": "",      "reviewed_at": "",      "meta": {        "client_id": "40",        "is_afnor": "0"      }    },    {      "order_id": "70",      "campaign_id": 2,      "workflow_status": "completed",      "interrupted_reason": "",      "created_at": "2018-02-07T14:58:28Z",      "updated_at": "2018-02-26T09:09:13Z",      "sent_at": "2018-02-26T09:03:41Z",      "delivered_at": "2018-02-26T09:09:13Z",      "dispatched_at": "2018-02-26T09:03:41Z",      "sent_by_service": "2018-02-26T09:09:13Z",      "opened_at": "",      "clicked_at": "",      "reviewed_at": "",      "meta": {        "client_id": "31",        "is_afnor": "0"      }    },    {      "order_id": "80",      "campaign_id": 3,      "workflow_status": "completed",      "interrupted_reason": "",      "created_at": "2018-02-07T14:58:28Z",      "updated_at": "2018-02-26T09:03:16Z",      "sent_at": "2018-02-26T09:03:16Z",      "delivered_at": "2018-02-26T09:03:16Z",      "dispatched_at": "2018-02-26T09:03:16Z",      "sent_by_service": "2018-02-26T09:03:16Z",      "opened_at": "",      "clicked_at": "",      "reviewed_at": "",      "meta": {        "client_id": "27",        "is_afnor": "0"      }    }  ],  "status_code": 200,  "meta": {    "_links": {      "first": {        "href": ""      },      "prev": {        "href": ""      },      "next": {        "href": "https://srr.ekomi.com/api/v1/recipients/activity_stream?start_date=2018-01-01&end_date=2018-06-28&page=2"      },      "last": {        "href": "https://srr.ekomi.com/api/v1/recipients/activity_stream?start_date=2018-01-01&end_date=2018-06-28&page=42"      }    },    "_count": {      "current_page": 1,      "total_records": 839    }  }}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Get Blacklist Rules API

This will return blacklist rules of a Customer Segment.

https://srr.ekomi.com/api/v1/customer-segments/{customer_segment_id}/blacklist-rules

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

customer_segment_id

Customer Segment id

Required

Path

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the blacklist rules against customer segment

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response

{  "data": [    "marketplace.amazon",    "test1@coeus-solutions.de"  ],  "status_code": 200}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Get Orders API

This will return orders and related meta data

https://srr.ekomi.com/api/v1/orders

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

order_ids

Array containing multiple order ids
Maximum Limit : 50

Example
["orderid1","orderid2","orderid3"]

Required

Query

Response Detail

Response Type: JSON

Parameters

Type

Values

data

JSON

This key is only returned in case of success. It contains the information about orders and their meta data

status_code

Number

Response status code. 200 in case of successful retrieval. In case of error, status code will be given in "error" key.

Possible Values and their Reasons

Status Code: 200. Reason: Successful response

Status Code: 401. Reason: Unauthorized shop

Status Code: 404. Reason: Entity not found

Status Code: 422. Reason: Validation error

Status Code: 500. Reason: Server side error

message

String

This key is only returned in case of error and contains the error message

Response Samples

Success Response

{  "data": [    {      "order_id": "LiveTestInpro-06",      "meta_data": {        "first_name": "μαυρα",        "test": "Stag!ng Te$ting",        "mobile": "HTC",                "transaction_date": "2017-09-28 14:50:31",        "Name": "Mavra Yasmin",        "timezone_type": "3",        "timezone": "UTC",        "client_id": "LiveAXA1",        "screen_name": "Chaмpion",        "is_afnor": "1"      }    },    {      "order_id": "tid0506201702",      "meta_data": ""    }  ],  "status_code": 200}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Add Consent API

This will save consent against an order for a shop. If shop does not exist in SRR, Consent will not be saved.

https://srr.ekomi.com/api/v1/consents

Request Detail

Request Type: POST

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

order_id

Order Id for which consent is taken

Required

Query

consent_taken_at

Date and Time when consent was taken from end User.
Valid format: YYYY-MM-DD HH:MM:SS
Timezone: UTC

Optional

Query

Response Detail

Response Type: JSON

Parameters

Type

Values

status_code

Number

Possible Values and their Reasons

Status Code: 201 Reason: Successful response

Status Code: 401. Reason:Unauthorized shop

Status Code: 404. Reason:Entity not found

Status Code: 422. Reason:Validation error

Status Code: 500. Reason:Server side error

message

String

Success / error message

Response Samples

Success Response

{  "message": "Consent request accepted and will be processed shortly",  "status_code": 201}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Update Shop Settings

This will update Shop Settings.

https://srr.ekomi.com/api/v1/shops/setting

Request Detail

Request Type: PUT

Parameters

Description

Mandatory

Parameter Type

shop-id

Shop id

Required

Header

interface-password

Interface Password

Required

Header

body

Requires a json containing setting name as key and setting new value as value
Example: {"smartcheck_on": true}

Required

Body

Response Detail

Response Type: JSON

Parameters

Type

Values

status_code

Number

Possible Values and their Reasons

Status Code: 200 Reason: Successful response

Status Code: 401. Reason:Unauthorized shop

Status Code: 404. Reason:Entity not found

Status Code: 422. Reason:Validation error

Status Code: 500. Reason:Server side error

message

String

Success / error message

Response Samples

Success Response

{    "message": "Shop Settings updated successfully",    "status_code": 200}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

Create / Clone Account

This will create / clone account and all the related settings

https://srr.ekomi.com/api/v2/accounts

Request Detail

Request Type: POST

Parameters

Description

Mandatory

Parameter Type

shop-id

Source Shop id

Required

Header

interface-password

Source Shop Interface Password

Required

Header

auth

Shop id and interface password for the new account.
Format: <shopid>|<interfacePassword>
Example: 1234|abc123xyz

Required

Query

Response Detail

Response Type: JSON

Parameters

Type

Values

status_code

Number

Possible Values and their Reasons

Status Code: 202, Reason: Request Accepted

Status Code: 401. Reason:Unauthorized shop

Status Code: 404. Reason:Entity not found

Status Code: 422. Reason:Validation error

Status Code: 500. Reason:Server side error

message

String

Success / error message

Response Samples

Success Response

{  "message": "Request has been accepted for processing",  "status_code": 202}

Error Response:

{    "error": {        "message": <error_message>,        "status_code": <status_code>     }}

4. Feedback Engagement API

Use following URL to access API documentation.

Live: https://engage.ekomiapps.de/api/doc

API: Security login 

API : /api/1.0/security/login

Request Type : POST

Pre-Condition

Parameters

Description

Example

Authorization

User has to create a new valid token by entering a valid Shop ID and password

/api/1.0/security/login

Response Samples

Success Response

Reponse body:

{"token": "MjA3M2Q5YjBlYzllZmU4MjYzNjU4YzdkMjdmMmM2ZmRmNmY1YzIxNmVmOTZmMmUzN2FhOTljNTFiNzQwNTI4Yw"}

Error Response Example:

Reponse body:

422 Unprocessable Entity


Possible Values and their Reasons

Status Code

Reason

200 

Successful response

401

Unauthorized shop

422

Unprocessable Entity

API: Review Cases

API : /api/1.0/review-cases

Request Type : GET

Description:

API to fetch all Review Cases of specified shop.


Pre-Condition

Parameters

Description

Example

Mandatory

Authorization 

eKomi authorization, token you get from Login API

KJS8ASD92J2

required

Start_date

User can enter the start date for which reviews cases he is looking for

Start date (YYYY-MM-DD)

optional

End_date

User can enter the End date for which reviews cases he is looking for

End date (YYYY-MM-DD)

optional

Limit

User can limit the records in result

200

optional

Offset

User can start the record from given offset

0

optional

Case_number

Case number to fetch any specific case (optional)

Test1234567890

optional

Response Detail

Response Type: JSON

Response Samples

Success Response

Reponse body:

{  "data": [    {      "case_id": "TEST1234567890",      "created_at": "2018-03-29 15:05:20",      "updated_at": "2018-04-18 00:05:03",      "case_statues": {        "1": "18-03-29 15:05:21",        "2": "",        "3": "",        "4": "",        "5": "",        "6": ""      },      "meta": {        "pool_name": "Poolname"      }    },    {      "case_id": "TEST1234567890",      "created_at": "2018-03-29 15:05:21",      "updated_at": "2018-04-18 00:05:03",      "case_statues": {        "1": "18-03-29 15:05:21",        "2": "",        "3": "",        "4": "",        "5": "",        "6": ""      },      "meta": {        "pool_name": "Poolname"      }    },    {      "case_id": "TEST1234567890",      "created_at": "2018-03-29 15:05:21",      "updated_at": "2018-04-18 00:05:03",      "case_statues": {        "1": "18-03-29 15:05:22",        "2": "",        "3": "",        "4": "",        "5": "",        "6": ""      },      "meta": {        "pool_name": "Poolname"      }

Status of Cases

Status

Description

Case imported:

Status => Untouched

An agent opens the case:

Status => In-progress

Customer refused to talk:

Status => Customer not reached

Customer didn't appear after 3 calls:

Status => Interview unsuccessful

Customer gave a feedback and case has been updated

Status => Interview successful

Case expired after due date

Status => Expired


Error Response Example:

 

Reponse body:

403 Forbidden

Possible Values and their Reasons

Status Code

Reason

200

Successful response

403

Forbidden Access

API: Review Comment

API : /api/1.0/review-comment

Request Type : GET

Description

API to fetch all comments of specified Order ID and Product ID.


Requirement

Description

Mandatory

Authorization 

eKomi authorization, token you get from Login API

required

Order ID

Enter the valid Order ID in this label

optional

Product ID

Enter the valid Product ID in this label

required

 

Response Detail

Response Type: JSON

Response Samples

Success Response

Response

{  "0": {    "order_id": "Testidhere12345678",    "product_id": "newproductid33330",    "review_hash": "45644365489f51cab152a40a903f1",    "comment": [],    "reviewer": {      "name": " ",      "telephone": ""    }  },  "total": 1

Error Response Example:

Reponse body:

404 Not Found

Possible Values and their Reasons

Status Code

Reason

200

Successful response

403

Forbidden Access

404

Not Found

5. SmartWidgets API

Use URL to access API documentation.

API: Get Widget Code

This will return all widget codes for specific shop

API : /api/1.0/widget/code

Request Detail

Request Type: GET

Parameters

Description

Mandatory

Parameter Type

Authorization 

eKomi authorization, token you get from Login API

Required

Header

widget_id

To get code of specific widget

Optional

integer

offset

To start the record from this offset

Optional

integer

limit

To limit the records

Optional

integer

Response Detail

Response Type: JSON

Response Samples

Success Response

[  {    "3": "<div id=\"widget-container\" class=\"ekomi-widget-container ekomi-widget-sf66558f899xxd\"></div> <script type=\"text/javascript\"> (function (w) { w['_ekomiWidgetsServerUrl'] = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//widgets.ekomi.com'; w['_customerId'] = 665; w['_ekomiDraftMode'] = true; w['_language'] = 'en'; if(typeof(w['_ekomiWidgetTokens']) !== 'undefined'){ w['_ekomiWidgetTokens'][w['_ekomiWidgetTokens'].length] = 'sf66558f899aa2e38d'; } else { w['_ekomiWidgetTokens'] = new Array('sf66558f899aa2e38d'); } if(typeof(ekomiWidgetJs) == 'undefined') { ekomiWidgetJs = true; var scr = document.createElement('script');scr.src = 'https://sw-assets.ekomiapps.de/static_resources/widget.js'; var head = document.getElementsByTagName('head')[0];head.appendChild(scr); } })(window); </script>",    "thumbnail": ""  },  ]

Error Response Example:

{"errors":{"message":"Invalid request."}}

API: Widget Clone

Clone account including setting and widgets of referenced shop

Parameters

Description

Mandatory

Parameter Type

Authorization 

eKomi authorization, token you get from Login API

Required

Header

shop_id

Shop id of target shop

Required

integer

interface_password 

Shop password of target shop

Required

String

widget_ids

Comma separated widgets ids to copy from reference shop

Optional

String

 

Response Detail

Response Type: JSON

Response Samples

Success Response

"Account cloned successfully"

 

Error Response Example:

{"errors":{"message":"Target user is not registered in eKomi connect."}}{"errors":{"message":"Invalid Widget id(s)."}}

Possible Values and their Reasons

Status Code

Reason

200

Successful response

404

Not found

422

Unprocessable entity

6. Mail2DB

Url to API documentation https://mail2db.ekomiapps.de/doc

API: Login

/api/1.0/security/login

 

Authoriation


Response:

{

  "client_id": "string",

  "client_secret": "string"

}


API: shop

/api/1.0/shop


Authorization: String


{

  "enabled": true,

  "userEmailAddress": "string",

  "shopId": 0

}

7. ARI

The Ari tool has an API at https://ari.ekomiapps.de/api/doc with the following endpoints:

Login

This call allows you to get an Authorization token that will allow you to access other APIs in the ARI tool.

<?php

$curl = curl_init();

$apiEndPoint = 'https://ari.ekomiapps.dev/api/1.0/security/login';
$ekomiConnectUsername = 'username';
$ekomiConnectPassword = 'password';

curl_setopt_array($curl, array(
    CURLOPT_URL => $apiEndPoint,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{"username": "'.$ekomiConnectUsername.'", "password": "'.$ekomiConnectPassword.'"}',
    CURLOPT_HTTPHEADER => array(
        'cache-control: no-cache',
        'content-type: application/json',
    ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:' . $err;
} else {
    $json = json_decode($response, true);
    echo $json['accessToken'];
}

Reviews

For this API to work, the eKomi Connect must have this role assigned to his account: ARI_POST_REVIEW

Please note that a new endpoint is added for POST review which accepts productReviewTitle: https://ari.ekomiapps.dev/api/1.1/reviews

Example call:

<?php

$curl = curl_init();

$apiEndPoint = 'https://ari.ekomiapps.dev/api/1.0/reviews';

// You get this token when you call the login API
$ekomiConnectAccessToken = 'MnRlMjJlNDE5ZTdlMjFmZTdlNmIzOGQ1OGZkYjA2NjYwMzBmZmQ0OTIyNmM1ODM2ODg1Mjk0ODU2NTY2MGVlNQ';

// Those parameters are mandatory
$curlOptPostFields = [];
$curlOptPostFields['inputSourceId'] = 2; // The ID of the input source (created in the ari tool admin)
$curlOptPostFields['orderId'] = 'test-12'; // The order ID
$curlOptPostFields['rating'] = 4; // Review rating
$curlOptPostFields['reviewText'] = 'This is lorem'; // Review text
$curlOptPostFields['transactionDate'] = '2004-02-12T15:19:21+00:00'; // ISO 8601 date
$curlOptPostFields['shopId'] = '12345'; // Account Id
// Those parameters are optional $curlOptPostFields['clientId'] = 1234; // The client’s id by which the client shall be registered. Must be alpha-numeric.
$curlOptPostFields['email'] = 'abdel@example.com'; // Clients contact email address


curl_setopt_array(
    $curl,
    array(
        CURLOPT_URL => $apiEndPoint,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => json_encode($curlOptPostFields),
        CURLOPT_HTTPHEADER => array(
            'authorization: ekomi '.$ekomiConnectAccessToken,
            'cache-control: no-cache',
            'content-type: application/json',
        ),
    )
);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo 'cURL Error #:'.$err;
} else {
    $json = json_decode($response, true);
    print_r($json);
}



8. Special Authentication API


There may be cases, where eKomi sytsem needs to be integrated into a third party system where users of the third party system need to login into eKomi without any need for special authentication. There are two ways to go about it:

a. The third party system implements eKomi's single sign on functionality, eKomi Connect

or 

b. Our special token based authentication is used. 


The token based authentication allows special accounts to retrieve a login token that can be used to login automatically. This needs to be enabled to accounts and is not enabled on all accounts. Furthermore, the authentication is restricted by IPs. 

To retrieve the token, the API will look like this: 

http://lite-api.coddle.de/getagent?connectuser=<connect_user>&access_token=<access_token>

Note that this is NOT the actual api link, the actual API link can be provided once this is enabled. 

The above API returns result such as following:


// 20200525163556
// http://lite-api.coddle.de/getagent?connectuser=<connect_user>&access_token=<access_token>

{
"status": 200,
"data": "http://lite.coddle.de/organizations/<orgnization_id>?token=<returned_access_token>"
}


Then user can login directly into the account using the data above.