Complete API Documentation
- Ali Shaheen (Unlicensed)
- Mohsin Naeem
- Tayyab Hussain (Unlicensed)
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:
- Feedback as seller ratings: This is the customer feedback that's pushed to Google as seller ratings.
- 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.
- Feedback as Net Promoter Score or CSAT: This is customer feedback collected to create NPS benchmarks.
- 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:
- Access tokens provided via eKomi oAuth based system, eKomi Connect. OR
- 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.
ATTENTION- do not use the test environment with real customer data and doublecheck the eMail templates before any action. Ensure to delete all your templates and data once your test is completed. eKomi is not liable for any claims, if those rules are not followed.
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
| Feedback Engagement App Workflow | Smart Widgets DataOut |
Other than these, there are:
- Voice of Employees which is used as a solution for collecting feedback from Employees.
- 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:
- Sending data to eKomi so that eKomi can send out feedback requests: use AddRecipient API
- Get all widgets created for the shop. Use GetWidget
- 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 Forbidden | Username 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 Forbidden | Username 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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 Id | 665 | 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 { "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: 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 | 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
| |
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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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 | 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 | 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 | |||||
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 | 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 Id | 665 | required | ||
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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. | optional | string |
withdrawn | Review's withdrawn status. | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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 | 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 | 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. | 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 | optional | ||
page | Page number. | 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 | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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.
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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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_rate879,"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 | 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 Id | 665 | required | ||||||||
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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. | optional | integer | ||||||||
page | Page number. | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 Id | 665 | required | ||||
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | required | ||||
Parameters | Description | Mandatory | Type | ||||
question_id | Question id | required | integer | ||||
expand | Allows to return extra meta data associated with question. | optional | string | ||||
show_multiple_question_labels | Allows to return multiple labels of sub-ranking questions. | optional | string | ||||
show_question_tags | Allows to return tags add with questions. | 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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | 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 | 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 | 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 Id | 665 | 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 { "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: 422. Message: Status should be published or rejected · Status Code: 409. Message: Feedback already rejected.
|
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
|
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 Id | 665 | required | |
interface-password | Interface or shop password | FMJuyuC8uEbo3WxRa5aG | required | |
Parameters
Pre-Condition | ||||
Parameters | Description | Example | Mandatory | Default |
review_hash | 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 | 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. | query | string |
form_id | Form id | 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. | query | string |
withdrawn | Review's withdrawn status. | query | string |
order_ids[] | Order ids filter to get reviews for more than 1 order id. Maximum 10 number of order ids are allowed. | query | Array[string] |
question_type | Question type(s) to fetch in response. | query | string |
exclude | Question type(s) to exclude from response. | query | string |
filter | Filter positive, negative and neutral rating. | 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. | query | string |
records_per_page | Number of records per page. | query | integer |
page | Page number. | 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:
| 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 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
| Optional (Required for AFNOR) |
has_products | Flag indicating whether the products information is required or not.
| 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:
| 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
| 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 |
· Nested JSON is also allowed but it will be stored as <parent_key>_<child_key> : <child_value>
| Optional |
client_id | Client id for recipient | Optional (Required for AFNOR) |
screen_name | Screen name for recipient | Optional |
is_afnor | Possible values
Cases
| Optional. Default is false |
Response Detail
Response Type: JSON
Parameters | Type | Values |
status | string | Possible Values:
|
message | string | In case of success, ‘ Recipient is added successfully’ will be returned. In case of errors, following error message will be returned
|
data | array | null, in case of error.
|
key | integer |
|
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}
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 | 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:
|
data | JSON | In case of success, data will be given in "data" key.
· Status Code: 200. Data: response data will be in "data" key:
|
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 | 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
|
data | JSON | In case of success, data will be given in "data" key.
· Status Code: 200. Data: response data will be in "data"
|
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: Shop not created, please try again later
· Status Code: 201. Message: Shop created with reference shop settings
|
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
|
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.
| 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.
| 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.
| 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 | 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. | 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. | Optional | Query | If no type is provided then all types will be returned |
workflow_status | Workflow status. | Optional | Query | If no workflow status is provided then all statuses will be returned |
subscription_status | Subscription status. | Optional | Query | subscribedadd r |
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. | Required | Query | None |
end_date | Filter on recipient's last activity date. | 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. | 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 Example | 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. | 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 | 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. | 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
Response DetailResponse Type: JSON Response SamplesSuccess 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.