The API facilitates product survey with a MTN Customer.
---
swagger: "2.0"
info:
description: The API facilitates product survey with a MTN Customer.
version: "1.1"
title: Customer Survey API
host: api.mtn.com
basePath: "/v1/survey"
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
security:
- ApiKeyAuth: []
paths:
/customers/{customerId}:
get:
tags:
- Customer
summary: Get Survey Quetions
description: Fetch Survey Questions and Options.
parameters:
- name: "customerId"
in: path
description: Source Msisdn. The format must be E.123
required: true
type: string
- name: "surveyId"
type: string
in: query
required: false
description: The unique ID of a particular survey
- name: targetSystem
type: string
in: query
enum:
- CLM
- DIGISURVEY
- CLM_REST
- name: surveyType
type: string
in: query
enum: ['eValidator','SHARENSELL']
responses:
"200":
description: Success
schema:
type: object
properties:
statusCode:
type: string
description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'"
statusMessage:
type: string
description: "Status Message"
transactionId:
type: string
description: "API generated Id to include for tracing requests"
data:
$ref: '#/definitions/DataResponse'
_links:
type: object
properties:
self:
type: string
example: "https://api.mtn.com/v1/survey/customers/23464618463"
"400":
description: Bad Request
schema:
$ref: '#/definitions/Error'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/Error'
"404":
description: Not Found
schema:
$ref: '#/definitions/Error'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error'
"406":
description: Not acceptable
schema:
$ref: '#/definitions/Error'
"415":
description: Unsupported media Type
schema:
$ref: '#/definitions/Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
post:
tags:
- Customer
summary: Submit Survey and more KYC Answers
description: Submit a list of questions and answers to survey.
parameters:
- name: surveyId
in: header
type: string
description: unique ID generated for each transaction
required: false
- name: surveyType
in: header
type: string
description: Survey type
required: false
- name: countryCode
in: header
type: string
description: Survey type
required: false
- name: "customerId"
in: path
description: Source Msisdn. The format must be E.123
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
required:
- answers
properties:
hash:
type: string
example: "Wk68gjJxucqM4qxTYCNH94TMid0KhIaE"
description: "The unique hash identifier for submiting a survey answer"
targetSystem:
type: string
example: DIGISURVEY
enum:
- CLM
- DIGISURVEY
- CLM_REST
- GENESIS
surveyType:
type: string
enum: ['SHARENSELL','eValidator']
servicePlan:
type: string
description: This is the service class of the customerId submiting survey answers
answers:
type: array
description: "The list of answered questions"
items:
type: object
properties:
id:
type: integer
message:
type: string
input :
type: string
responses:
"200":
description: Success Response
schema:
type: object
properties:
statusCode:
type: string
description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'"
statusMessage:
type: string
description: "Status Message"
transactionId:
type: string
description: "API generated Id to include for tracing requests"
data:
$ref: '#/definitions/DataResponse'
_links:
type: object
properties:
self:
type: string
example: "https://api.mtn.com/v1/survey/customers/23464618463"
"400":
description: Bad Request
schema:
$ref: '#/definitions/Error'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/Error'
"404":
description: Not Found
schema:
$ref: '#/definitions/Error'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error'
"406":
description: Not acceptable
schema:
$ref: '#/definitions/Error'
"415":
description: Unsupported media Type
schema:
$ref: '#/definitions/Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/customers/surveyOptInByTimeStamp:
get:
tags:
- Customer
summary: Get Survey Msisdn List in CSV format
description: Fetch Survey Msisdn List in CSV format.
parameters:
- name: startDate
in: query
type: string
- name: endDate
in: query
type: string
description: startDate
required: true
- name: targetSystem
type: string
in: query
enum:
- GENESIS
responses:
"200":
description: Success
schema:
type: object
properties:
statusCode:
type: string
description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'"
statusMessage:
type: string
description: "Status Message"
transactionId:
type: string
description: "API generated Id to include for tracing requests"
data:
$ref: '#/definitions/SurveyListResponse'
_links:
type: object
properties:
self:
type: string
example: "https://api.mtn.com/v1/survey/customers/surveyOptInByTimeStamp"
"400":
description: Bad Request
schema:
$ref: '#/definitions/Error'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/Error'
"403":
description: Forbidden
schema:
$ref: '#/definitions/Error'
"404":
description: Not Found
schema:
$ref: '#/definitions/Error'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error'
"406":
description: Not acceptable
schema:
$ref: '#/definitions/Error'
"415":
description: Unsupported media Type
schema:
$ref: '#/definitions/Error'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/customers/surveyInvitation:
post:
tags:
- Customer
summary: Submit Survey and more KYC Answers
description: Submit a list of questions and answers to survey.
parameters:
- name: transactionId
in: header
description: Transaction Id for tracking purposes
required: false
type: string
- name: requestBody
in: body
required: true
schema:
$ref: '#/definitions/surveyInvitationRequest'
responses:
'200':
description: Identity status response from ROC Enroll
schema:
$ref: '#/definitions/surveyInvitationResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error400'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error401'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error404'
"405":
description: Method No Allowed
schema:
$ref: '#/definitions/Error405'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/Error500'
definitions:
DataResponse:
type: object
properties:
hash:
type: string
description: The unique hash identifier attached to a survey
example: "Wk68gjJxucqM4qxTYCNH94TMid0KhIaE"
questions:
type: array
items:
type: object
properties:
id:
type: integer
description: "Unique Question Id"
type:
type: string
description: "Type of the question"
example: "QuestionScalableDIGI"
nested_level:
example: 1
type: integer
description: "Questions Current Position"
language:
type: object
description: "The actual Question"
example: {
"text": "How would you rate your experience performing this transaction?",
"error": "Please rate your experience to help us serve you better:"
}
options:
description: "Available options for the question"
type: object
example: {
"render_type": "star rating",
"required": "1",
"number": "5",
"start_from_0": "0"
}
answers:
description: "Expected answers"
type: object
example: [
{
"id": "647",
"value": "Yes",
"name": "Yes"
},
{
"id": "648",
"value": "No",
"name": "No"
}
]
finish:
type: boolean
example: false
description: "Determined the last question"
state:
type: string
example: "Created"
requiredScore:
type: string
example: 15
actualScore:
type: string
example: 20
SurveyListResponse:
type: string
title: SurveyListResponse
description: msisdn list in csv format
example: '26876497748,26876497748,26876062635'
surveyInvitationRequest:
type: object
required:
- customerId
- address
- language
- surveyId
properties:
customerId:
type: string
description: MTN SA's ID of the customer that is invited to a survey
example: 'kbu_test'
address:
type: string
description: Customer's email address (email or phone number) to send out survey invitation to.
example: 'kbu@sansdiv.com'
language:
type: string
description: Required. Should contain Language code in ISO-691-1 format not of the survey to be shown to the customer. example like EN, FR, etc.
example: 'EN'
surveyId:
type: integer
description: Should contain ID of the survey the customer should be invited to. Survey ID to use for each touchpoint is provided by MTN SA's Customer Experience team (e.g. Call Center Interaction, SIM card replacement, Mobile Data plan switch, etc. Example values are 123, 234, etc.
example: '360'
metadata:
type: object
properties:
city:
type: string
description: Name of the city of the customer
example: 'Cape Town'
shop:
type: string
description: Name of the shop
example: 'MTN Cavendish Square'
surveyInvitationResponse:
type: object
properties:
statusCode:
type: string
description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes',
example: '0000'
maxLength: 30
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client. Success for 200.
example: 'Success'
supportMessage:
type: string
description: More details information of status of transaction from backend.
example: 'Success'
transactionId:
type: string
description: Unique Id sent with the request
data:
type: object
properties:
id:
type: integer
description: id
example: '843873'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/questionnaire/xqLjY9sVhsDNfTUJRCAb9gMYKXED4M32/'
hash:
type: string
description: hash id
example: 'xqLjY9sVhsDNfTUJRCAb9gMYKXED4M32'
survey:
type: object
description: survey details
properties:
id:
type: integer
description: survey id
example: '360'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/survey/360/'
channel:
type: string
description: Channel name
example: 'DIGI'
state:
type: integer
description: state of the survey
example: '1'
surveyGroup:
type: integer
description: number of survey group
example: '172'
isStepbyStep:
type: boolean
description: Indication of the process being done step wise
example: 'true'
customer:
type: object
properties:
id:
type: string
description: customer id
example: '904'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/customer/904/'
state:
type: integer
description: state of the survey
example: '1'
language:
type: string
description: language preference
example: 'EN'
externalId:
type: string
description: External id
example: 'kbu_test'
creationDate:
type: string
description: creation date
example: '2020-03-31T20:55:47.162853+02:00'
language:
type: object
properties:
id:
type: string
description: language id
example: '4'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/language/4/'
name:
type: string
description: language name
example: 'English'
iso6391code:
type: string
description: ISO code of the language
example: 'EN'
state:
type: integer
description: state of the survey
example: '32'
subState:
type: integer
description: Sub state of the survey
example: 'string'
creationDate:
type: string
description: creation date
example: '2020-03-31T20:55:47.162853+02:00'
startTime:
type: string
description: start time
example: '2020-03-31T20:55:47.162853+02:00'
invitationTime:
type: string
description: invitation time
example: '2020-03-31T20:55:47.162853+02:00'
endTime:
type: string
description: end time
example: '2020-04-01T20:55:47.162853+02:00'
details:
type: array
description: additional details
items:
properties:
id:
type: integer
description: id
example: '690418'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/questionnaire-detail/690418/'
questionnaire:
type: integer
description: questionnaire number
example: '843873'
name:
type: string
description: parameter name
example: 'MSISDN'
value:
type: integer
description: parameter value
example: 'kbu@sandsiv.com'
importId:
type: integer
description: Import id
example: 'string'
transactionalDataValues:
type: array
items:
properties:
id:
type: integer
description: transaction data id
example: '1884108'
self:
type: string
description: URL for questionnaire
example: 'https://mtn-sa-rest.sandsiv.com/api/rest/transactional-data-value/1884108/'
creationDate:
type: string
description: creation date
example: '2024-07-25T19:10:51.625254+02:00'
name:
type: string
description: parameter name
example: 'SHOP'
value:
type: integer
description: parameter value
example: 'MTN Cavendish Square'
Error:
type: object
required:
- "statusCode"
- "statusMessage"
properties:
statusCode:
type: string
description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
example: '1000'
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client
supportMessage:
type: string
description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful)
transactionId:
type: string
description: API generated Id to include for tracing requests
timestamp:
type: string
format: date-time
description: Timestamp of the error
example: "2019-08-23T07:29:25.593+0000"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: "https://api.mtn.com/v1/survey/customers/surveyOptInByTimeStamp"
Error400:
properties:
statusCode:
type: "integer"
description: Status code from target system to indicate transaction status
example: '5000'
statusMessage:
type: "string"
description: Status message from target system to indicate transaction status.
supportMessage:
type: "string"
description: detail message from target system to indicate transaction status.
transactionId:
type: string
description: This is the same transactionId that is sent in the request
example: "0d1e1b18-1b6d-4792-8417-72d337f42a1c"
error:
type: object
Error401:
properties:
error:
type: "string"
description: error message from target system to indicate transaction status.
example: missing_authorization
error_description:
type: "string"
description: detailed error message from target system to indicate transaction status.
example: Missing Authorization header
Error404:
properties:
status:
type: "integer"
description: Status code from target system to indicate transaction status
example: '1000'
message:
type: string
description: details
example: "no match found"
Error405:
properties:
timestamp:
type: string
format: date-time
description: Timestamp that the error occurred
example: '2021-07-21T17:32:28Z'
status:
type: "integer"
description: Status code from target system to indicate transaction status
example: '3002'
error:
type: "string"
description: error message
example: Method Not Allowed
message:
type: string
description: details
path:
type: string
description: The path that caused the error
Error415:
properties:
timestamp:
type: string
format: date-time
description: Timestamp that the error occurred
example: '2021-07-21T17:32:28Z'
status:
type: "integer"
description: Status code from target system to indicate transaction status
example: 415
error:
type: "string"
description: error message
example: Unsupported Media Type
message:
type: string
description: details
path:
type: string
description: The path that caused the error
Error500:
properties:
statusMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client
example: 'Internal Server Error'
statusCode:
type: string
description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
example: '3001'
transactionId:
type: string
description: This is the same transactionId that is sent in the request
example: "0d1e1b18-1b6d-4792-8417-72d337f42a1c"
supportMessage:
type: string
description: More details and corrective actions related to the error which can be shown to a client
example: 'Backend System Error'
httpStatus:
type: string
description: The path that caused the error
example: "BAD REQIUEST"