openapi: 3.0.1 info: title: Customer Survey description: This API enables the facilitation of a product-related survey conducted with an MTN customer to collect insights and feedback. license: name: MADAPI url: https://developers.mtn.com/ version: 3.0.0 - Last updated date:2026-09-08 07:29:39 servers: - url: https://api.mtn.com/v1 description: Production Server security: - OAuth2: [] tags: - name: Customer Survey paths: /customers: get: tags: - Customer Survey summary: provides the ability for a consumer to retrieve list of survey questions and options description: This operation enables the facilitation of a product-related survey conducted with an MTN customer to collect insights and feedback. operationId: CustomerSurveyAggregatorService_get_getCustomerData_customers parameters: - name: countryCode in: header required: true schema: type: string - name: customerId in: query required: false schema: type: string - name: language in: header required: false schema: type: string - name: surveyId in: header required: false schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_customersurvey_CustomerSurveyResponse' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false post: tags: - Customer Survey summary: Submit a list of questions and answers to survey without customerId description: This submits a detailed list of survey questions and the corresponding answers collected from the specified MTN customer. operationId: CustomerSurveyAggregatorService_post_postCustomerSurveyForServiceNow_customers parameters: - name: countryCode in: header required: true schema: type: string - name: surveyId in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string requestBody: content: application/json: schema: title: CustomerSurveyRequest type: object properties: hash: type: string customerId: type: string id: type: string targetSystem: type: string servicePlan: type: string surveyType: type: string answers: type: array items: $ref: '#/components/schemas/com_mtn_aggregator_models_Answer' name: type: string emailAddress: type: string phoneNumber: type: string msisdn: type: string transactionID: type: string customerEmailAddress: type: string customerSegment: type: string locationState: type: string interactionType: type: string callReasonArea: type: string callReasonSubArea: type: string tariffPlan: type: string timeofContact: type: string dateofBirth: type: string channelofInteraction: type: string modeofInteraction: type: string dateofInteraction: type: string agentID: type: string lob: type: string customerName: type: string locationGeoPolitical: type: string tenureofCustomer: type: string ninLinked: type: string usim: type: string phoneType: type: string phoneModel: type: string surveyId: type: string required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: title: PostCustomersurveyResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false /customers/surveyInvitation: post: tags: - Customer Survey summary: Submit Survey and more KYC Answers description: Submit Survey and more KYC (Know Your Customer) Answers. This endpoint handles survey submission and additional KYC answers operationId: CustomerSurveyAggregatorService_post_postCustomerSurveyInvitiation_customerssurveyInvit parameters: - name: countryCode in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: CustomerSurveyInvitationRequest type: object properties: customerId: type: string address: type: string language: type: string surveyId: type: integer format: int32 metadata: title: Metadata type: object properties: city: type: string shop: type: string required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: title: CustomerSurveyInvitationResponse type: object properties: statusCode: type: string statusMessage: type: string supportMessage: type: string transactionId: type: string data: title: CustomerSurveyInvitationResponseData type: object properties: id: type: integer format: int32 self: type: string hash: type: string survey: title: Survey type: object properties: id: type: integer format: int32 self: type: string channel: type: string state: type: integer format: int32 surveyGroup: type: integer format: int32 isStepbyStep: type: boolean customer: title: Customer type: object properties: id: type: string self: type: string state: type: integer format: int32 language: type: string externalId: type: string creationDate: type: string language: title: Language type: object properties: id: type: string self: type: string name: type: string iso6391code: type: string state: type: integer format: int32 subState: type: string creationDate: type: string startTime: type: string invitationTime: type: string endTime: type: string details: type: array items: title: Details type: object properties: id: type: integer format: int32 self: type: string questionnaire: type: integer format: int32 name: type: string value: type: string importId: type: string transactionalDataValues: type: array items: title: TransactionalDataValues type: object properties: id: type: integer format: int32 self: type: string creationDate: type: string name: type: string value: type: string error: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false /customers/surveyOptInByTimeStamp: get: tags: - Customer Survey summary: Provides msisdn list opted in for genesis description: Retrieves a list of MSISDNs that have opted in to participate in Genesis product surveys within a defined time range. operationId: CustomerSurveyAggregatorService_get_getSurveyOptInMsisdn_customerssurveyOptIn parameters: - name: countryCode in: header required: false schema: type: string - name: endDate in: query required: false schema: type: string - name: startDate in: query required: true schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: title: SurveyOptInResponseSWZ type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false /customers/{customerId}: get: tags: - Customer Survey summary: Provides the ability for a consumer to retrieve list of Survey Questions and Options. description: This API enables the facilitation of a product-related survey conducted with an MTN customer to collect insights and feedback. operationId: CustomerSurveyAggregatorService_get_customerSurvey_customerscustomerId parameters: - name: countryCode in: header required: true schema: type: string - name: customerId in: path required: true schema: type: string - name: surveyId in: header required: false schema: type: string - name: surveyType in: query required: false schema: type: string - name: targetSystem in: query required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: title: CustomerSurveyResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string sequenceNumber: type: string code: type: string status: type: string actualScore: type: string passScore: type: string state: type: string message: type: string requiredScore: type: string data: type: string output: type: array items: title: CustomersurveyResponseData type: object properties: hash: type: string questions: type: array items: title: Question type: object properties: id: type: string type: type: string nestedLevel: type: string language: title: Language type: object properties: text: type: string error: type: string options: title: Options type: object properties: renderType: type: string required: type: string min: type: string max: type: string isMultiChoice: type: string lastIsOpen: type: string number: type: string startFrom: type: string answers: type: array items: title: Answer type: object properties: id: type: string message: type: string value: type: string name: type: string result: type: string input: type: string finish: type: boolean state: type: string requiredScore: type: string actualScore: type: string id: type: string score: type: string result: type: string data: type: string supportMessage: type: string error: type: string isSuccessful: type: boolean "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false post: tags: - Customer Survey summary: Submit a list of questions and answers to survey description: This submits a detailed list of survey questions and the corresponding answers collected from the specified MTN customer. operationId: CustomerSurveyAggregatorService_post_postCustomerSurveyWithId_customerscustomerId parameters: - name: countryCode in: header required: true schema: type: string - name: customerId in: path required: true schema: type: string - name: surveyId in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string - name: x-origin-channelid in: header required: false schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_request_CustomerSurveyRequest' required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_customersurvey_PostCustomersurveyResponse' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false /customers/{surveySessionId}/{operation}: post: tags: - Customer Survey summary: "For different operations like activate, terminate, metadata, etc.\ \ on a survey." description: "This endpoint allows for various operations to be performed on\ \ a survey session, such as activating, terminating, or updating metadata.The\ \ specific operation is determined by the 'operation' path parameter." operationId: CustomerSurveyAggregatorService_post_postCustomerSurveyOperation_customerssurveySessi parameters: - name: countryCode in: header required: false schema: type: string - name: operation in: path required: true schema: type: string - name: surveySessionId in: path required: true schema: type: string - name: targetSystem in: header required: false schema: type: string - name: transactionId in: header required: false schema: type: string requestBody: content: application/json: schema: title: CustomerSurveyMetadataRequest type: object properties: metadata: type: object additionalProperties: type: string required: true responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: $ref: '#/components/schemas/com_mtn_aggregator_models_response_customersurvey_CustomerSurveyResponse' "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false /token: get: tags: - Customer Survey summary: Get JWT Token description: Retrieves a JWT token for authentication purposes. This token is generated and then returned as a plain string response. operationId: CustomerSurveyAggregatorService_get_getJwtToken_token responses: "200": description: HTTP 200 indicating the request succeeded; the response body follows the documented schema for this operation and includes correlation identifiers where applicable for traceability across MTN MADAPI Customer Survey flows. content: application/json: schema: type: string "400": description: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "400" statusMessage: "Bad request. Invalid request parameters, missing required\ \ fields, or validation errors." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "401": description: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "401" statusMessage: "Unauthorized. Invalid or missing authorization credentials,\ \ insufficient permissions, or authentication failure." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "403": description: Forbidden. Access denied. The request is valid but the server refuses to perform it. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "403" statusMessage: Forbidden. Access denied. The request is valid but the server refuses to perform it. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "404": description: Not found. The requested resource was not found or does not exist. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "404" statusMessage: Not found. The requested resource was not found or does not exist. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "500": description: "Internal server error. Unexpected system failure, database\ \ connectivity issues, or external service integration problems." content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "500" statusMessage: "Internal server error. Unexpected system failure,\ \ database connectivity issues, or external service integration\ \ problems." supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "502": description: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "502" statusMessage: Bad gateway. The server acting as a gateway received an invalid response from an upstream server. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z "503": description: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. content: application/json: schema: $ref: '#/components/schemas/APIError' example: statusCode: "503" statusMessage: Service unavailable. The server is temporarily unable to handle the request due to maintenance or overload. supportMessage: API_ERROR transactionId: "1234567890" sequenceNo: "20250115120000001" timestamp: 2025-01-15T12:00:00Z deprecated: false components: schemas: com_mtn_aggregator_models_Answer: title: Answer type: object properties: id: type: string message: type: string value: type: string name: type: string result: type: string input: type: string com_mtn_aggregator_models_request_CustomerSurveyRequest: title: CustomerSurveyRequest type: object properties: hash: type: string customerId: type: string id: type: string targetSystem: type: string servicePlan: type: string surveyType: type: string answers: type: array items: $ref: '#/components/schemas/com_mtn_aggregator_models_Answer' name: type: string emailAddress: type: string phoneNumber: type: string msisdn: type: string transactionID: type: string customerEmailAddress: type: string customerSegment: type: string locationState: type: string interactionType: type: string callReasonArea: type: string callReasonSubArea: type: string tariffPlan: type: string timeofContact: type: string dateofBirth: type: string channelofInteraction: type: string modeofInteraction: type: string dateofInteraction: type: string agentID: type: string lob: type: string customerName: type: string locationGeoPolitical: type: string tenureofCustomer: type: string ninLinked: type: string usim: type: string phoneType: type: string phoneModel: type: string surveyId: type: string com_mtn_aggregator_models_response_customersurveyinvitation_TransactionalDataValues: title: TransactionalDataValues type: object properties: id: type: integer format: int32 self: type: string creationDate: type: string name: type: string value: type: string com_mtn_aggregator_models_response_customersurvey_CustomersurveyResponseData: title: CustomersurveyResponseData type: object properties: hash: type: string questions: type: array items: title: Question type: object properties: id: type: string type: type: string nestedLevel: type: string language: title: Language type: object properties: text: type: string error: type: string options: title: Options type: object properties: renderType: type: string required: type: string min: type: string max: type: string isMultiChoice: type: string lastIsOpen: type: string number: type: string startFrom: type: string answers: type: array items: title: Answer type: object properties: id: type: string message: type: string value: type: string name: type: string result: type: string input: type: string finish: type: boolean state: type: string requiredScore: type: string actualScore: type: string id: type: string score: type: string result: type: string data: type: string com_mtn_aggregator_models_request_CustomerSurveyInvitationRequest: title: CustomerSurveyInvitationRequest type: object properties: customerId: type: string address: type: string language: type: string surveyId: type: integer format: int32 metadata: title: Metadata type: object properties: city: type: string shop: type: string com_mtn_aggregator_models_response_customersurveyinvitation_CustomerSurveyInvitationResponse: title: CustomerSurveyInvitationResponse type: object properties: statusCode: type: string statusMessage: type: string supportMessage: type: string transactionId: type: string data: title: CustomerSurveyInvitationResponseData type: object properties: id: type: integer format: int32 self: type: string hash: type: string survey: title: Survey type: object properties: id: type: integer format: int32 self: type: string channel: type: string state: type: integer format: int32 surveyGroup: type: integer format: int32 isStepbyStep: type: boolean customer: title: Customer type: object properties: id: type: string self: type: string state: type: integer format: int32 language: type: string externalId: type: string creationDate: type: string language: title: Language type: object properties: id: type: string self: type: string name: type: string iso6391code: type: string state: type: integer format: int32 subState: type: string creationDate: type: string startTime: type: string invitationTime: type: string endTime: type: string details: type: array items: title: Details type: object properties: id: type: integer format: int32 self: type: string questionnaire: type: integer format: int32 name: type: string value: type: string importId: type: string transactionalDataValues: type: array items: title: TransactionalDataValues type: object properties: id: type: integer format: int32 self: type: string creationDate: type: string name: type: string value: type: string error: type: string com_mtn_aggregator_models_Language: title: Language type: object properties: text: type: string error: type: string com_mtn_aggregator_models_request_CustomerSurveyMetadataRequest: title: CustomerSurveyMetadataRequest type: object properties: metadata: type: object additionalProperties: type: string com_mtn_aggregator_models_response_customersurveyinvitation_Customer: title: Customer type: object properties: id: type: string self: type: string state: type: integer format: int32 language: type: string externalId: type: string creationDate: type: string com_mtn_aggregator_models_Question: title: Question type: object properties: id: type: string type: type: string nestedLevel: type: string language: title: Language type: object properties: text: type: string error: type: string options: title: Options type: object properties: renderType: type: string required: type: string min: type: string max: type: string isMultiChoice: type: string lastIsOpen: type: string number: type: string startFrom: type: string answers: type: array items: title: Answer type: object properties: id: type: string message: type: string value: type: string name: type: string result: type: string input: type: string com_mtn_aggregator_models_response_customersurvey_CustomerSurveyResponse: title: CustomerSurveyResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string sequenceNumber: type: string code: type: string status: type: string actualScore: type: string passScore: type: string state: type: string message: type: string requiredScore: type: string data: type: string output: type: array items: title: CustomersurveyResponseData type: object properties: hash: type: string questions: type: array items: title: Question type: object properties: id: type: string type: type: string nestedLevel: type: string language: title: Language type: object properties: text: type: string error: type: string options: title: Options type: object properties: renderType: type: string required: type: string min: type: string max: type: string isMultiChoice: type: string lastIsOpen: type: string number: type: string startFrom: type: string answers: type: array items: title: Answer type: object properties: id: type: string message: type: string value: type: string name: type: string result: type: string input: type: string finish: type: boolean state: type: string requiredScore: type: string actualScore: type: string id: type: string score: type: string result: type: string data: type: string supportMessage: type: string error: type: string isSuccessful: type: boolean com_mtn_aggregator_models_Options: title: Options type: object properties: renderType: type: string required: type: string min: type: string max: type: string isMultiChoice: type: string lastIsOpen: type: string number: type: string startFrom: type: string com_mtn_aggregator_models_response_customersurveyinvitation_Details: title: Details type: object properties: id: type: integer format: int32 self: type: string questionnaire: type: integer format: int32 name: type: string value: type: string com_mtn_aggregator_models_response_customersurveyinvitation_CustomerSurveyInvitationResponseData: title: CustomerSurveyInvitationResponseData type: object properties: id: type: integer format: int32 self: type: string hash: type: string survey: title: Survey type: object properties: id: type: integer format: int32 self: type: string channel: type: string state: type: integer format: int32 surveyGroup: type: integer format: int32 isStepbyStep: type: boolean customer: title: Customer type: object properties: id: type: string self: type: string state: type: integer format: int32 language: type: string externalId: type: string creationDate: type: string language: title: Language type: object properties: id: type: string self: type: string name: type: string iso6391code: type: string state: type: integer format: int32 subState: type: string creationDate: type: string startTime: type: string invitationTime: type: string endTime: type: string details: type: array items: title: Details type: object properties: id: type: integer format: int32 self: type: string questionnaire: type: integer format: int32 name: type: string value: type: string importId: type: string transactionalDataValues: type: array items: title: TransactionalDataValues type: object properties: id: type: integer format: int32 self: type: string creationDate: type: string name: type: string value: type: string com_mtn_aggregator_models_response_customersurveyinvitation_Survey: title: Survey type: object properties: id: type: integer format: int32 self: type: string channel: type: string state: type: integer format: int32 surveyGroup: type: integer format: int32 isStepbyStep: type: boolean com_mtn_aggregator_models_request_Metadata: title: Metadata type: object properties: city: type: string shop: type: string APIError: title: APIError required: - statusCode - statusMessage type: object properties: statusCode: type: string description: Error status code statusMessage: type: string description: Human-readable error message supportMessage: type: string description: Technical support message or error code for troubleshooting transactionId: type: string description: Transaction identifier for tracking and correlation sequenceNo: type: string description: Sequence number for request tracking timestamp: type: string description: Error timestamp in ISO 8601 format format: date-time path: type: string description: API endpoint path where the error occurred method: type: string description: HTTP method of the request that caused the error downstreamStatusCode: type: string description: Downstream service error code if applicable description: Generic MADAPI error response structure com_mtn_aggregator_models_response_SurveyOptInResponseSWZ: title: SurveyOptInResponseSWZ type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string data: type: string com_mtn_aggregator_models_response_customersurvey_PostCustomersurveyResponse: title: PostCustomersurveyResponse type: object properties: statusCode: type: string statusMessage: type: string transactionId: type: string com_mtn_aggregator_models_response_customersurveyinvitation_Language: title: Language type: object properties: id: type: string self: type: string name: type: string iso6391code: type: string securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://api.mtn.com/v1/oauth/access_token scopes: {} Bearer: type: http description: Bearer token received from OAuth2.0 authentication with the MADAPI scheme: bearer bearerFormat: JWT