openapi: 3.2.0 info: description: List of services to integrate with insurance service provider to manage insurance policies and policy related information. It provides the ability for channel applications to request for quote, submit application, manage application and fetch list of policies. version: v1.0 title: Insurance Policy API servers: - url: https://za.api.mtn.com/insurance security: - ApiKeyAuth: [] - OAuth2: [] tags: - name: Policy paths: /v1/application: post: tags: - Policy summary: Create a set of new policies based on a quote description: Provides the ability for channels to submit application to create one or more policies based on a given quote. operationId: Application parameters: - name: channelId in: header description: Source system identifier required: true x-example: EBUPortal schema: type: string - name: targetSystem in: header required: false description: Name of the backend system schema: type: string enum: - ATS default: ATS - name: transactionId in: header description: Unique identifier of this transaction. Generated automatically by MADAPI and passed to backend if not sent by channel. schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApplicationResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorBadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorUnauthorized' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorForbidden' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorBackend' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApplicationRequest' required: true components: schemas: ApplicationRequest: type: object required: - customer - billing - cover - compliance properties: customer: type: object required: - customerIdType - customerId - type - firstName - lastName properties: customerIdType: type: string description: Customer identification type chosen on request enum: - billingMsisdn - insuredMsisdn - policyId - idNumber - company - appReferenceNumber customerId: type: string description: Actual identifier for the selected customer type chosen on request example: 27831234567 minLength: 5 maxLength: 50 type: type: string description: Type of customer enum: - cbu - ebu - sme customerSubType: type: string enum: - sme title: type: string enum: - mr - mrs - ms initials: type: string description: Intials of the customer. Data encrypted by MADAPI before sending to backend system. example: MJ maxLength: 10 firstName: type: string description: First name of the customer. Data encrypted by MADAPI before sending to backend system. example: Mary minLength: 1 maxLength: 100 lastName: type: string description: Surname of the customer. Data encrypted by MADAPI before sending to backend system. example: Joan minLength: 2 maxLength: 100 additionalIdType: type: string enum: - saId - drivers - passport - other additionalId: type: string description: Length is 13 characters if SA ID. Data encrypted by MADAPI before sending to backend system. example: 8010200033854 minLength: 2 maxLength: 13 company: type: object required: - name - registrationNumber properties: name: type: string description: Company name of the customer. Data encrypted by MADAPI before sending to backend system. minLength: 2 maxLength: 100 example: Missy Joans (Pty) Ltd tradingName: type: string description: Trading name of the customer. Data encrypted by MADAPI before sending to backend system. minLength: 2 maxLength: 100 example: Missy Joans & Co registrationNumber: type: string description: Company registration number of the customer. Data encrypted by MADAPI before sending to backend system. minLength: 20 maxLength: 100 address: type: object description: Clients address. Data encrypted by MADAPI before sending to backend system. required: - province - country properties: streetNumber: type: string description: Unit or house number. Data encrypted by MADAPI before sending to backend system. example: 45 minLength: 1 maxLength: 10 streetName: type: string description: Street name. Data encrypted by MADAPI before sending to backend system. example: Sandton Drive minLength: 2 maxLength: 100 buildingName: type: string description: Building name. Data encrypted by MADAPI before sending to backend system. example: Block B maxLength: 100 unitNumber: type: string description: Third line of the client's address, if needed. Data encrypted by MADAPI before sending to backend system. minLength: 1 maxLength: 10 example: 2A suburb: type: string description: Suburb for the client's address. Data encrypted by MADAPI before sending to backend system. example: Sandton minLength: 2 maxLength: 100 city: type: string description: City for the client's address. Data encrypted by MADAPI before sending to backend system. example: Johannesburg minLength: 2 maxLength: 100 province: type: string description: Province of the client's address. Data encrypted by MADAPI before sending to backend system. example: Gauteng minLength: 2 maxLength: 100 country: type: string description: Country of the client's address. Data encrypted by MADAPI before sending to backend system. example: South Africa minLength: 2 maxLength: 100 postalCode: type: string description: Postal code of the client's address. example: 2192 minLength: 4 maxLength: 10 dateOfBirth: type: string format: date description: Date of birth in YYYY-MM-DD format. Data encrypted by MADAPI before sending to backend system. example: 2001-10-20 minLength: 10 maxLength: 10 emailAddress: type: string format: email description: Email address of the client. Data encrypted by MADAPI before sending to backend system. example: mary.joan@mycompany.com minLength: 8 maxLength: 100 contactNumber: type: string description: Contact phone number of the client. Data encrypted by MADAPI before sending to backend system. example: 27842401234 minLength: 10 maxLength: 11 additionalContactNumber: type: string description: Any other phone number of the client, if applicable. Data encrypted by MADAPI before sending to backend system. example: 27841230099 minLength: 10 maxLength: 11 address: type: object description: Clients address. Data encrypted by MADAPI before sending to backend system. required: - province - country properties: streetNumber: type: string description: Unit or house number. Data encrypted by MADAPI before sending to backend system. example: 45 minLength: 1 maxLength: 10 streetName: type: string description: Street name. Data encrypted by MADAPI before sending to backend system. example: Sandton Drive minLength: 2 maxLength: 100 buildingName: type: string description: Building name. Data encrypted by MADAPI before sending to backend system. example: Block B maxLength: 100 unitNumber: type: string description: Third line of the client's address, if needed. Data encrypted by MADAPI before sending to backend system. minLength: 1 maxLength: 10 example: 2A suburb: type: string description: Suburb for the client's address. Data encrypted by MADAPI before sending to backend system. example: Sandton minLength: 2 maxLength: 100 city: type: string description: City for the client's address. Data encrypted by MADAPI before sending to backend system. example: Johannesburg minLength: 2 maxLength: 100 province: type: string description: Province of the client's address. Data encrypted by MADAPI before sending to backend system. example: Gauteng minLength: 2 maxLength: 100 country: type: string description: Country of the client's address. Data encrypted by MADAPI before sending to backend system. example: South Africa minLength: 2 maxLength: 100 postalCode: type: string description: Postal code of the client's address. example: 2192 minLength: 4 maxLength: 10 beneficiary: type: object description: Details of the policy beneficiary. Mandatory when covers section has cover type is Contact Protector required: - firstName - surname - contactNumber - dateOfBirth properties: firstName: type: string description: First name of the beneficiary, mandatory. Data encrypted by MADAPI before sending to backend system. example: Jack minLength: 1 maxLength: 100 surname: type: string description: Surname of the beneficiary, mandatory. Data encrypted by MADAPI before sending to backend system. example: Kabelo minLength: 2 maxLength: 100 emailAddress: type: string format: email description: Email address of the beneficiary. Data encrypted by MADAPI before sending to backend system. example: jkabelo@gmail.com minLength: 8 maxLength: 100 contactNumber: type: string description: Contact number of the beneficiary, mandatory. Data encrypted by MADAPI before sending to backend system. minLength: 10 maxLength: 11 dateOfBirth: type: string format: date description: Date of birth of the beneficiary, in YYYY-MM-DD format, mandatory. Data encrypted by MADAPI before sending to backend system. example: 1998-08-12 minLength: 10 maxLength: 10 beneficiaryIdType: type: string description: 'Type of identification used by the beneficiary. ' enum: - saId - passport beneficiaryId: type: string description: Identification number of the beneficiary. Length is 13 characters if SA ID. Data encrypted by MADAPI before sending to backend system. minLength: 2 maxLength: 13 cover: type: array description: Insurace covers requested by customer. Multiple instances allowed. required: - quoteId - coverType items: type: object required: - quoteId - coverType properties: quoteId: type: string description: Unique quote identifier for this product. This is the primary Quote ID or item level Quote ID that is also used for the selected cover. This ID is obtained from the service /quotation example: 245-371-18 product: type: object required: - productIdType - productId properties: productIdType: type: string description: How the insured product is identified, such as using a Product Code, TAC or SKU enum: - code - tac - sku - marketingId productId: type: string description: Actual identifier for the selected type such as a specific SKU example: 7923642 minLength: 2 maxLength: 50 asset: type: array description: This array contains the insured MSISDN details, along with the device details items: type: object required: - msisdn - id properties: msisdn: type: string minLength: 1 maxLength: 12 description: Insured MSISDNs for the related device. If multiple, then first MSISDN item in list relates to first IMEI/Serial No in related list. example: 27832227008 id: type: string minLength: 1 maxLength: 100 description: IMEI numbers or Serial numbers for the related device. IMEI should be 14 to 16 digits long, if applicable. example: AA-BBBBBB-CCCCCC-D coverType: type: string description: Type of premium band for this group of policies. enum: - allRisk - repairOnly - accident - lossTheft - excessBuyDown - cyberSim - contractProtector - routerInsurance addOn: type: array items: type: string example: excessBuyDown description: List of addOn covers like excessBuyDown, cyberSim, contractProtector, routerInsurance billing: type: object required: - collectionType properties: collectionType: type: string default: contract description: Type of collection for policy. enum: - debitOrder - contract billingIdType: type: string description: Customer's MTN billing identification type. enum: - profileId - msisdn billingId: type: string description: Customer’s MTN billing identifier. example: 27832227008 minLength: 10 maxLength: 50 bank: type: object properties: bankName: type: string description: Data encrypted by MADAPI before sending to backend system. minLength: 5 maxLength: 50 example: Absa bankAccountHolderName: type: string description: Data encrypted by MADAPI before sending to backend system. minLength: 5 maxLength: 50 example: Mary Joan bankAccountNumber: type: string description: Data encrypted by MADAPI before sending to backend system. example: 8074812224 bankBranchNumber: type: string description: Data encrypted by MADAPI before sending to backend system. example: 62005 bankBranchName: type: string description: Data encrypted by MADAPI before sending to backend system. example: Sandton City bankAccountType: type: string description: Data encrypted by MADAPI before sending to backend system. example: cheque bankDebitDay: type: integer example: 1 commission: type: object description: Agent information used for commission purposes. properties: storeCode: type: string description: Code of the store initiating the policy. Internal MTN store code. Used commission purposes. example: SABC0001 minLength: 2 maxLength: 30 agentIdType: type: string enum: - storeAgent agentId: type: string description: Identifier of the agent handling the policy. Used commission purposes. example: 149220 minLength: 2 maxLength: 30 compliance: type: object description: List of regulations. Once instance allowed. required: - consent properties: consent: type: boolean description: Electronic signature provided as consent to share customer information. For example, false is not signed. advertisingConsent: type: boolean description: Electronic signature provided as consent to receive marketing related communications. For example, false is not signed. default: false document: type: array items: type: object properties: fileType: type: string enum: - proofOfPurchase - authorisationLetter - mandate - waiver - imeisMsisdns fileRefNumber: type: string ErrorBackend: type: object title: ErrorBackend required: - statusCode - statusMessage properties: statusCode: type: string description: MADAPI Canonical Error Code of 4 digit long default: '5000' statusMessage: type: string description: Error description supportMessage: type: string description: More error details and corrective measures path: type: string description: The path that caused the error timestamp: type: string format: date-time description: Timestamp of the error transactionId: type: string description: Unique identifier of this transaction ErrorUnauthorized: type: object title: ErrorUnauthorized required: - statusCode - statusMessage properties: statusCode: type: string description: MADAPI Canonical Error Code of 4 digit long default: '4000' statusMessage: type: string description: Error description supportMessage: type: string description: More error details and corrective measures path: type: string description: The path that caused the error timestamp: type: string format: date-time description: Timestamp of the error transactionId: type: string description: Unique identifier of this transaction ErrorBadRequest: type: object title: ErrorBadRequest required: - statusCode - statusMessage properties: statusCode: type: string description: MADAPI Canonical Error Code of 4 digit long default: '5000' statusMessage: type: string description: Error description supportMessage: type: string description: More error details and corrective measures path: type: string description: The path that caused the error timestamp: type: string format: date-time description: Timestamp of the error transactionId: type: string description: Unique identifier of this transaction ErrorForbidden: type: object title: ErrorForbidden required: - error - error_description properties: error: type: string description: Error description error_description: type: string description: More error details and corrective measures ApplicationResponse: type: object required: - statusCode - statusMessage - transactionId - data properties: statusCode: type: string description: Result code. default: '0000' statusMessage: type: string description: Result message. Example- 'Successfully processed' transactionId: type: string description: Unique id of this transaction. data: type: object properties: applicationRefNumbers: type: array items: required: - groupId - subGroupId - coverTypeCode properties: groupId: minLength: 5 maxLength: 50 example: ATS-EBU-22333-MTNAR–12345 description: 'Structure would include ATS-EBU-ClientIdentifier-CoverType–DeviceID. ClientIdentifier: Max 11 digits CoverTypes: MTNAR (All Risk), MTNLT (Loss & Theft), MTNAD (Liquid & Accident), MTNRO (Repair Only), MTNCS (Cyber Sim), MTNRI (Router Insurance), MTNCP (Contract Protector) DeviceID: System product code for the device' subGroupId: minLength: 5 maxLength: 50 example: ATS-EBU-22333-MTNAR–12345 description: 'Structure would include ATS-EBU-ClientIdentifier-CoverType–DeviceID-QuoteID. ClientIdentifier: Max 11 digits CoverTypes: MTNAR (All Risk), MTNLT (Loss & Theft), MTNAD (Liquid & Accident), MTNRO (Repair Only), MTNCS (Cyber Sim), MTNRI (Router Insurance), MTNCP (Contract Protector) DeviceID: System product code for the device QuoteID: As per cover in application request' coverTypeCode: minLength: 2 maxLength: 50 example: allRisk enum: - allRisk - repairOnly - accident - lossTheft - excessBuyDown - cyberSim - contractProtector - routerInsurance deviceId: type: string minLength: 1 maxLength: 50 example: '12345' securitySchemes: ApiKeyAuth: type: apiKey name: x-api-key in: header OAuth2: type: oauth2 flows: clientCredentials: scopes: {} tokenUrl: https://api.mtn.com/edgemicro-custom-auth/token?grant_type=client_credentials