openapi: 3.1.0
info:
  version: 1.0.1
  title: Root Applications Notifications API
  description: Root is an end-to-end digital insurance platform that enables you to launch new products and digital engagement channels fast.
  termsOfService: https://rootplatform.com/about
  contact:
    name: Root support team
    url: https://rootplatform.com/contact
    email: support@root.co.za
servers:
- url: https://sandbox.uk.rootplatform.com/v1/insurance
  description: United Kingdom multi-tenant - sandbox
- url: https://api.uk.rootplatform.com/v1/insurance
  description: United Kingdom multi-tenant - production
- url: https://sandbox.rootplatform.com/v1/insurance
  description: South Africa multi-tenant - sandbox
- url: https://api.rootplatform.com/v1/insurance
  description: South Africa multi-tenant - production
security:
- basicAuth: []
tags:
- name: Notifications
paths:
  /custom-notification-events/{custom_event_key}/trigger:
    post:
      operationId: trigger-custom-notification-event
      summary: Trigger a custom notification event
      description: 'Queue a custom notification request (or first queue policy documents to be generated if there are email attachments). A `200 (Success)` response does not indicate that the notification was sent successfully. Please refer to the [custom notification events](doc:custom-notification-events) guide.

        '
      tags:
      - Notifications
      x-additional-tags:
      - Endpoints
      parameters:
      - name: custom_event_key
        in: path
        description: The key identifiying the custom notification event.
        required: true
        schema:
          type: string
          example: policyholder_birthday
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - custom_event_type
              properties:
                custom_event_type:
                  $ref: '#/components/schemas/custom-event-type'
                policy_id:
                  type: string
                  description: The UUID of the policy for which the event should be triggered. Required if `custom_event_type` is `policy` or `payment_method`.
                payment_id:
                  type: string
                  description: The UUID of the payment for which the event should be triggered. Required if `custom_event_type` is `payment`.
                claim_id:
                  type: string
                  description: The UUID of the claim for which the event should be triggered. Required if `custom_event_type` is `claim`.
              example:
                custom_event_type: policy
                policy_id: 21e26db0-e620-4472-ba21-886208f99b54
      responses:
        '200':
          description: Success
  /notifications:
    get:
      operationId: fetch-notifications
      summary: List all notifications
      tags:
      - Notifications
      x-additional-tags:
      - Endpoints
      parameters:
      - name: channel
        in: query
        description: Either `email`, `sms` or `other`. If omitted defaults to fetching notifications across all channels.
        required: false
        schema:
          type: string
      - name: provider
        in: query
        description: Either `root_standard`, `external` or `root_webhooks`. If omitted defaults to fetching notifications across all providers.
        required: false
        schema:
          type: string
      - name: policy_id
        in: query
        description: The unique identifier for the policy to filter by.
        required: false
        schema:
          type: string
      - name: policyholder_id
        in: query
        description: The unique identifier for the policyholder to filter by.
        required: false
        schema:
          type: string
      - name: claim_id
        in: query
        description: The unique identifier for the claim to filter by.
        required: false
        schema:
          type: string
      - name: exclude_types
        in: query
        description: Optionally exclude notification types from the returned results.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notifications'
              example:
              - notification_id: dccdd659-0a42-4df2-9d02-5df9f98a2433
                organization_id: 00000000-0000-0000-0000-000000000001
                channel: email
                notification_type: claim_received
                provider: root_mandrill
                created_at: '2022-06-21T08:39:24.293Z'
                created_by:
                  type: user
                  id: 00000000-0000-0000-0000-000000000001
                status: queued
                status_updates:
                - status: queued
                  createdAt: '2022-06-21T08:39:24.293Z'
                linked_entities:
                  policy_id: 11111112-0000-0000-0000-000000000008
                  policyholder_id: 00000000-0000-0000-0000-000000000004
                  claim_id: 535e439c-3d75-43cc-b706-3a0b05dec894
                data:
                  to:
                  - name: Tim
                    type: to
                    email: tim@smith.com
                  html: <div>hello</div>
                  subject: 'Claim #F0BABAC137E6 received'
                  from_name: Policy Administration System
                  from_email: no-reply@policy@adminsystem.com
                  attachments: []
              - notification_id: 43c13dc8-2c19-402c-bb70-a7deb56b9f38
                organization_id: 00000000-0000-0000-0000-000000000001
                channel: sms
                notification_type: policy_issued
                provider: root_clickatell
                created_at: '2022-06-23T07:59:53.261Z'
                created_by:
                  type: user
                  id: 6f852057-b381-4ab0-a53d-93a6c2ec6f26
                status: delivered
                status_updates:
                - status: queued
                  createdAt: '2022-06-23T07:59:53.261Z'
                - status: sent
                  createdAt: '2022-06-23T07:59:54.000Z'
                  description: Delivered to gateway (003)
                - status: delivered
                  createdAt: '2022-06-23T07:59:57.000Z'
                  description: Received by recipient (004)
                linked_entities:
                  policy_id: b338a75b-207e-4b6c-8649-4c0ebfe39d8b
                  policyholder_id: b5b10383-0b50-4965-8bff-addb2001c5d1
                data:
                  to:
                  - '+27811231234'
                  content: Congratulations! Your  Cover has been activated from 01/06/2022.
    post:
      operationId: create-external-notification
      summary: Create an external notification
      tags:
      - Notifications
      x-additional-tags:
      - Endpoints
      description: Create a notification with provider of `external`. If you use an integration external to Root to send notifications to end customers, you can use this endpoint to record the notification on Root and link it to the relevant entities (such as a policy or claim).
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - channel
              - status
              - notification_type
              - linked_entities
              - data
              properties:
                channel:
                  type: string
                  description: The channel over which the notification is sent.
                  enum:
                  - email
                  - sms
                  - other
                status:
                  type: string
                  description: The status of the notification.
                  enum:
                  - sent
                  - rejected
                failure_reason:
                  type: string
                  description: Forbidden if `status` is not `rejected`. The reason for the notification failure.
                notification_type:
                  type: string
                  description: The event the notification is linked to.
                  enum:
                  - payment_failure_1st
                  - payment_failure_4th
                  - payment_failure_15th
                  - payment_failure_debit_order
                  - payment_success_debit_order
                  - payment_success_external
                  - payment_failure_eft
                  - payment_failure_on_demand_cover_period
                  - payment_failure_on_demand_monthly
                  - payment_failure_card
                  - payment_failure_external
                  - payment_reversal
                  - payment_method_blocked
                  - payment_method_failed_verification
                  - payment_method_updated
                  - policy_issued
                  - beneficiaries_updated
                  - covered_people_updated
                  - debit_orders_activated
                  - eft_activated
                  - policy_policyholder_updated
                  - policy_cancelled
                  - policy_lapsed
                  - policy_not_taken_up
                  - policy_expired
                  - policy_updated
                  - first_premium_payment
                  - sum_assured_updated
                  - policy_requoted
                  - policy_reactivated
                  - policy_anniversary
                  - external_payments_activated
                  - alteration_package_applied
                  - claim_approved_beneficiary
                  - claim_approved
                  - claim_received
                  - claim_repudiated
                  - claim_linked_to_policy
                  - claim_sent_to_review
                  - claim_decision_review
                  - claim_sent_to_review_claimant
                  - send_application_pdf_to_policyholder
                  - complaint_received
                  - custom
                  - custom_event
                linked_entities:
                  description: Entities linked to the notification.
                  type: object
                  required:
                  - policy_id
                  properties:
                    policy_id:
                      type: string
                      description: Must be a UUID. The unique identifier of the policy linked to the notification.
                data:
                  $ref: '#/components/schemas/notification-data'
              example:
                channel: email
                status: sent
                notification_type: policy_issued
                linked_entities:
                  policy_id: 3d292076-a531-4028-988e-e863b04d8497
                data:
                  from_email: erlich@aviato.com
                  from_name: Erlich Bachman
                  reply_to_email: erlich@aviato.com
                  subject: Hello
                  html: <div>hello</div>
                  to:
                  - name: Dinesh
                    email: dinesh@piedpiper.com
                  attachments:
                  - type: application/pdf
                    name: AviatoS3Script.pdf
            example:
              channel: email
              status: sent
              notification_type: policy_issued
              linked_entities:
                policy_id: 3d292076-a531-4028-988e-e863b04d8497
              data:
                from_email: erlich@aviato.com
                from_name: Erlich Bachman
                reply_to_email: erlich@aviato.com
                subject: Hello
                html: <div>hello</div>
                to:
                - name: Dinesh
                  email: dinesh@piedpiper.com
                attachments:
                - type: application/pdf
                  name: AviatoS3Script.pdf
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification'
              example:
                notification_id: ff693e05-244a-4b48-97fa-237ebafc4c29
                organization_id: 2f26d0e1-9158-4685-83e8-1660c27e4c3f
                channel: email
                notification_type: policy_issued
                provider: external
                created_at: '2022-06-23T08:38:30.703Z'
                created_by:
                  type: api_key
                  id: 95d369a6-93c0-4687-9506-86f1659a6d3e
                  owner_id: 2f26d0e1-9158-4685-83e8-1660c27e4c3f
                status: sent
                status_updates:
                - status: sent
                  created_at: '2023-02-15T09:49:45.503Z'
                linked_entities:
                  policy_id: 3d292076-a531-4028-988e-e863b04d8497
                data:
                  from_email: erlich@aviato.com
                  from_name: Erlich Bachman
                  reply_to_email: erlich@aviato.com
                  subject: Hello
                  html: <div>hello</div>
                  to:
                  - name: Dinesh
                    email: dinesh@piedpiper.com
                  attachments:
                  - name: AviatoS3Script.pdf
                    type: application/pdf
  /notifications/{notification_id}:
    get:
      operationId: retrieve-a-notification
      summary: Retrieve a notification
      tags:
      - Notifications
      x-additional-tags:
      - Endpoints
      parameters:
      - name: notification_id
        in: path
        description: The unique identifier of the [notification](ref:notification).
        required: true
        schema:
          type: string
          example: 43c13dc8-2c19-402c-bb70-a7deb56b9f38
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification'
    patch:
      operationId: update-external-notification
      summary: Update an external notification
      tags:
      - Notifications
      x-additional-tags:
      - Endpoints
      description: Update the status of a notification with provider of `external`.
      parameters:
      - name: notification_id
        in: path
        description: Must be a UUID. The unique identifier of the notification to update.
        required: true
        schema:
          type: string
          example: 3ac406c1-b5f4-4850-a615-d4bb2b951039
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  type: string
                  enum:
                  - queued
                  - sent
                  - delivered
                  - rejected
                  - opened
                  - unknown_error
                  description: The new status of the notification.
                status_update_description:
                  type: string
                  description: A description of or reason for the update to the notification status. This will be stored as part of the `status_updates` array on the [notification object](ref:notification).
              example:
                status: rejected
                status_update_description: Hard bounce - invalid mailbox.
            example:
              status: rejected
              status_update_description: Hard bounce - invalid mailbox.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification'
              example:
                notification_id: ff693e05-244a-4b48-97fa-237ebafc4c29
                organization_id: 2f26d0e1-9158-4685-83e8-1660c27e4c3f
                channel: email
                notification_type: policy_issued
                provider: external
                created_at: '2022-06-23T08:38:30.703Z'
                created_by:
                  type: api_key
                  id: 95d369a6-93c0-4687-9506-86f1659a6d3e
                  owner_id: 2f26d0e1-9158-4685-83e8-1660c27e4c3f
                status: rejected
                status_updates:
                - status: queued
                  created_at: '2023-02-15T09:48:04.799Z'
                - status: rejected
                  created_at: '2023-02-15T09:49:45.503Z'
                  description: Hard bounce - invalid mailbox.
                linked_entities:
                  policy_id: 3d292076-a531-4028-988e-e863b04d8497
                data:
                  from_email: erlich@aviato.com
                  from_name: Erlich Bachman
                  reply_to_email: erlich@aviato.com
                  subject: Hello
                  html: <div>hello</div>
                  to:
                  - name: Dinesh
                    email: dinesh@piedpiper.com
                  attachments:
                  - name: AviatoS3Script.pdf
                    type: application/pdf
components:
  schemas:
    custom-event-type:
      type: string
      description: The type of custom event. Must match the type on the Root management dashboard.
      enum:
      - policy
      - payment_method
      - payment
      - claim
    notification-other-data:
      type: object
      required:
      - to
      - content
      - content_type
      properties:
        to:
          type: string
          description: An array containing phone numbers that the notification was sent to.
        content:
          type: string
          description: Content for the SMS notification.
        content_type:
          type: string
          description: Whether it was `text` or `html`.
        app_data:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object containing additional custom data for the SMS notification.'
          additionalProperties: true
    notification-email-data:
      type: object
      required:
      - subject
      - html
      - attachments
      - to
      properties:
        from_email:
          type: string
          description: Email address of who sent the email notification.
        from_name:
          type: string
          description: Name of who sent the email notification.
        reply_to_email:
          type: string
          description: Recipient of who to respond to for the email notification.
        subject:
          type: string
          description: Email subject.
        html:
          type: string
          description: The HTML structure of the email body.
        attachments:
          type: array
          description: An array of objects containing a list of `type` and `name` pairs for the attachments on the email notification.
          items:
            type: object
            properties:
              type:
                type: string
                description: Whether the file is a document or image.
              name:
                type: string
                description: The name of the file
        to:
          type: array
          description: An array of objects containing a list of `email` and `name` pairs of the recipients of the email notification.
          items:
            type: object
            properties:
              email:
                type: string
                description: The desired recipient's email.
              name:
                type: string
                description: The recipient's name.
    notification:
      type: object
      required:
      - notification_id
      - notification_type
      - linked_entities
      - channel
      - provider
      - created_at
      - created_by
      - status
      - status_updates
      properties:
        notification_id:
          type: string
          description: The identifier of the notification.
        organization_id:
          type: string
          description: The identifier of the organization.
        notification_type:
          type: string
          description: Indicates the type of notification (e.g., policy_issued).
        linked_entities:
          type: object
          description: Indicates which entities the notification is linked to.
          properties:
            policy_id:
              type: string
              description: The identifier of the policy.
        channel:
          type: string
          description: The channel used for the notification. Channels available include `email`, `sms` or `other`.
        provider:
          type: string
          description: Indicates how the notification was generated. Whether it was `external`, `root_standard` or `root_webhooks`.
        created_at:
          type: string
          format: date-time
          description: Time at which the notification was created.
        created_by:
          type: object
          description: An object indicating the user or API key that created the notification. See [Authentication](#client-apps).
        status:
          type: string
          description: The current status of the notification.
          enum:
          - queued
          - sent
          - delivered
          - rejected
          - opened
          - unknown_error
        status_updates:
          type: array
          description: An array of status update information for the notification.
          items:
            type: object
            properties:
              status:
                type: string
                description: The status that the notification was updated to.
                enum:
                - queued
                - sent
                - delivered
                - rejected
                - opened
                - unknown_error
              createdAt:
                type: string
                format: date-time
                description: Time at which the status update was created.
              description:
                type: string
                description: An optional detailed description of the status update.
            required:
            - status
            - createdAt
        data:
          $ref: '#/components/schemas/notification-data'
      example:
        notification_id: 43c13dc8-2c19-402c-bb70-a7deb56b9f38
        organization_id: 4ce6ad99-9576-4d28-84ba-c30d2d536cbe
        channel: sms
        notification_type: policy_issued
        provider: root_clickatell
        created_at: '2022-06-23T07:59:53.261Z'
        created_by:
          type: user
          id: 6f852057-b381-4ab0-a53d-93a6c2ec6f26
        status: delivered
        status_updates:
        - status: queued
          createdAt: '2022-06-23T07:59:53.261Z'
        - status: sent
          createdAt: '2022-06-23T07:59:54.000Z'
          description: Delivered to gateway (003)
        - status: delivered
          createdAt: '2022-06-23T07:59:57.000Z'
          description: Received by recipient (004)
        linked_entities:
          policy_id: b338a75b-207e-4b6c-8649-4c0ebfe39d8b
          policyholder_id: b5b10383-0b50-4965-8bff-addb2001c5d1
        data:
          to:
          - '+27811231234'
          content: Congratulations! Your  Cover has been activated from 01/06/2022.
    notification-sms-data:
      type: object
      required:
      - to
      - content
      properties:
        to:
          type: array
          items:
            type: string
          description: An array containing phone numbers that the notification was sent to.
        content:
          type: string
          description: Content for the SMS notification.
        content_type:
          type: string
          description: Whether it was `text` or `html`.
        app_data:
          type:
          - object
          - 'null'
          description: '`null` is allowed. An object containing additional custom data for the SMS notification.'
          additionalProperties: true
    notification-data:
      type: object
      description: An object containing additional data depending on whether the notification channel is `email`, `sms`, or `other`.
      oneOf:
      - $ref: '#/components/schemas/notification-email-data'
      - $ref: '#/components/schemas/notification-sms-data'
      - $ref: '#/components/schemas/notification-other-data'
    notifications:
      type: array
      items:
        $ref: '#/components/schemas/notification'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true