openapi: 3.0.1
info:
  title: PSAP Outage Alerts
  contact:
    name: Bandwidth
  version: 1.0.0
  termsOfService: https://www.bandwidth.com/legal/terms-of-service/
  description: |-
    The API specification for Bandwidth's PSAP Outage Alerts platform.

    ## Base URL
    `https://api.bandwidth.com/api/v2`
servers:
  - url: https://api.bandwidth.com/api/v2
paths:
  /accounts/{accountId}/emergency/psap-alerts/incidents:
    get:
      summary: List Incidents
      description: >
        Retrieve all PSAP Outage Alert Incidents and alert information for an
        account. 

        PSAP Outage Alert Incidents are returned in descending order by
        createdAt, and grouped by incidentId.
      operationId: listIncidents
      tags:
        - Incidents
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentIdQuery'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/triggeredOnly'
        - $ref: '#/components/parameters/triggeredTestAlertsOnly'
      responses:
        '200':
          $ref: '#/components/responses/listIncidentsResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    post:
      summary: Create Incident
      description: Create a new PSAP Outage Alert Incident and an initial alert
      operationId: createIncident
      tags:
        - Incidents
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        $ref: '#/components/requestBodies/incidentRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/createIncidentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}:
    get:
      summary: Get Incident
      description: |
        Return metadata about a specific PSAP Outage Alert Incident.
      operationId: getIncident
      tags:
        - Incidents
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
        - $ref: '#/components/parameters/includeTestAlerts'
      responses:
        '200':
          $ref: '#/components/responses/getIncidentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    patch:
      summary: Update Incident
      description: >
        Update an existing PSAP Outage Alert Incident. This can only be used
        before any alerts for this incident have been triggered.

        All previous alerts for this incident will be deleted and a new initial
        alert will be created.
      operationId: updateIncident
      tags:
        - Incidents
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
      requestBody:
        $ref: '#/components/requestBodies/updateIncidentRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/updateIncidentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    delete:
      summary: Delete Incident
      description: >-
        Delete an incident and all associated alerts. This can only be used
        before any alerts for this incident have been triggered.
      operationId: deleteIncident
      tags:
        - Incidents
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/alerts:
    post:
      summary: Create Alert
      description: >
        Create a new alert for an existing incident A new alert can only be
        created if the incident has a status of ACTIVE.
      operationId: createAlert
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
      requestBody:
        $ref: '#/components/requestBodies/alertRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/createAlertResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/alerts/{alertId}:
    delete:
      summary: Delete Alert
      description: >-
        Delete an alert for an incident. This can only be used before the alert
        has been triggered.
      operationId: deleteAlert
      tags:
        - Alerts
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
        - $ref: '#/components/parameters/alertId'
      responses:
        '204':
          $ref: '#/components/responses/noContentResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers:
    get:
      summary: List Triggers
      description: |
        Retrieve all PSAP Outage Alert Triggers for a specific incident.
      operationId: listTriggers
      tags:
        - Trigger
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/incidentId'
      responses:
        '200':
          $ref: '#/components/responses/listTriggersResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
    post:
      summary: Trigger Alert
      description: >
        Trigger a PSAP Outage Alert. Each account can only have one trigger in
        progress at a time.
      operationId: postTriggerPsapOutage
      tags:
        - Trigger
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
      requestBody:
        $ref: '#/components/requestBodies/triggerRequestBody'
      responses:
        '202':
          $ref: '#/components/responses/triggerPsapOutageResponse'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
  /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers/{triggerId}:
    get:
      summary: Get Trigger Details
      description: Retrieve details about a PSAP Outage Alert Trigger.
      operationId: getTriggerDetails
      tags:
        - Trigger
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/incidentId'
        - $ref: '#/components/parameters/triggerId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          $ref: '#/components/responses/getTriggerDetails'
        '400':
          $ref: '#/components/responses/badRequestResponse'
        '401':
          $ref: '#/components/responses/unauthorizedResponse'
        '403':
          $ref: '#/components/responses/forbiddenResponse'
        '404':
          $ref: '#/components/responses/notFoundResponse'
        '405':
          $ref: '#/components/responses/methodNotAllowedResponse'
        '429':
          $ref: '#/components/responses/tooManyRequestsResponse'
        '500':
          $ref: '#/components/responses/internalServerErrorResponse'
components:
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique account identifier
      schema:
        type: string
        example: '9999999'
    alertId:
      name: alertId
      in: path
      required: true
      description: The unique alert identifier
      schema:
        type: string
        example: 051997bc-20c5-4896-95ce-3d2d46dfd250
    incidentId:
      name: incidentId
      in: path
      required: true
      description: The unique pre-existing incident identifier
      schema:
        type: string
        example: '1234567'
    incidentIdQuery:
      name: incidentId
      in: query
      required: false
      description: Returns PSAP Outage Alert Incidents matching the incidentId substring
      schema:
        type: string
        example: '1234567'
    includeTestAlerts:
      name: includeTestAlerts
      in: query
      required: false
      description: Include test alerts in the response
      schema:
        type: boolean
        example: true
        default: false
    limit:
      name: limit
      in: query
      description: The number of records to return in the response.
      schema:
        type: integer
        example: 100
    offset:
      name: offset
      in: query
      description: Position in the dataset of a particular record to start the response.
      schema:
        type: integer
        example: 100
    triggerId:
      name: triggerId
      in: path
      required: true
      description: The unique trigger identifier
      schema:
        type: string
        example: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
    triggeredOnly:
      name: triggeredOnly
      in: query
      required: false
      description: Only return triggered alerts
      schema:
        type: boolean
        example: true
        default: false
    triggeredTestAlertsOnly:
      name: triggeredTestAlertsOnly
      in: query
      required: false
      description: Only return triggered test alerts
      schema:
        type: boolean
        example: true
        default: false
  requestBodies:
    alertRequestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/alertRequest'
    incidentRequestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/incidentRequest'
    triggerRequestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/triggerPsapOutage'
    updateIncidentRequestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/updateIncidentRequest'
  schemas:
    alertId:
      type: string
      example: 051997bc-20c5-4896-95ce-3d2d46dfd250
      description: The unique identifier for the alert.
    alertRequest:
      title: Create a new alert for an existing incident
      description: Create a new alert for an existing incident
      type: object
      properties:
        alertTime:
          type: string
          format: date-time
          example: '2024-08-27T15:30:00Z'
          description: >
            The time of the alert. This information is included in the alert
            text that is sent to the PSAPs.
        expectedRestorationTime:
          $ref: '#/components/schemas/expectedRestorationTime'
        causeOfOutage:
          $ref: '#/components/schemas/causeOfOutage'
        alertType:
          type: string
          enum:
            - UPDATE
            - ALL_CLEAR
          example: UPDATE
          description: >
            The alert type.

            - UPDATE: This is an update to the INITIAL alert, indicating that
            the incident is still ongoing.

            - ALL_CLEAR: This is an all clear alert, indicating that the
            incident is now resolved.
        testAlert:
          $ref: '#/components/schemas/testAlert'
      required:
        - alertTime
        - alertType
    alertType:
      type: string
      enum:
        - INITIAL
        - UPDATE
        - ALL_CLEAR
      example: INITIAL
      description: >
        The type of alert.

        - INITIAL: This is the initial alert that is sent to the PSAPs.

        - UPDATE: This is an update to the initial alert, indicating that the
        incident is still ongoing.

        - ALL_CLEAR: This is an all clear alert, indicating that the incident is
        now resolved.
    areasAffected:
      type: array
      items:
        type: string
      example:
        - USA
      description: >
        The areas affected by the outage. This can be either a list of FCC IDs,
        two-letter state codes, or USA if the outage is nationwide.

        Once an alert has been triggered, the areas affected cannot be updated.
        In the case that additional areas are impacted after an alert

        has been triggered, a new incident should be created with the additional
        areas affected.
    causeOfOutage:
      type: string
      example: a network disruption
      description: >
        The best known cause of the outage. If left blank, the PSAP will be
        notified that the cause of the outage is unknown.
      maxLength: 100
      pattern: ^[a-zA-Z0-9\s]{1,100}$
    createAlertResponse:
      title: Create Alert Response
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          properties:
            alertId:
              $ref: '#/components/schemas/alertId'
            alertType:
              $ref: '#/components/schemas/alertType'
            ttsPreAnnouncement:
              type: string
              example: This is a pre-announcement for a PSAP Outage Alert.
              description: >-
                The text-to-speech pre-announcement that will be played before
                the PSAP Outage Alert is played.
            alertText:
              type: string
              example: This is a PSAP Outage Alert.
              description: The alert text that will be shared to the PSAP.
            triggered:
              type: boolean
              example: true
              description: >
                Indicates if the alert has been triggered.

                If true, the alert has been sent to the PSAPs and cannot be
                triggered again.

                If false, the alert has not been sent.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    errorResponse:
      title: Error Response
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
          default: []
        data:
          type: object
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    error:
      title: Error
      type: object
      properties:
        id:
          type: string
          example: '50420'
          description: A unique identifier for the error.
        type:
          type: string
          example: resource-not-found
          description: The type of error.
        description:
          type: string
          example: The resource specified cannot be found.
          description: A description of the error.
        code:
          type: integer
          example: 50420
          description: The error code.
    expectedRestorationTime:
      type: string
      format: date-time
      example: '2024-08-27T15:30:00Z'
      description: >
        The expected time the outage will be resolved. This will be shared with
        the PSAPs. 

        If left blank, the PSAP will be notified that the expected restoration
        time is unknown.
    incidentId:
      type: string
      example: '1234567'
      description: A unique numeric identifier for the incident.
      pattern: ^[0-9]{1,100}$
    incidentResponse:
      title: Get Incident Response
      description: Return incident metadata
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          properties:
            incidentId:
              $ref: '#/components/schemas/incidentId'
            status:
              $ref: '#/components/schemas/incidentStatus'
            startTime:
              type: string
              format: date-time
              example: '2024-08-27T15:30:00Z'
              description: >
                The time the incident started. This information is included in
                the initial alert that is sent to the PSAPs.
            lastUpdated:
              type: string
              format: date-time
              example: '2024-08-27T15:30:00Z'
              description: The time the incident was last updated.
            alerts:
              type: array
              items:
                properties:
                  alertId:
                    $ref: '#/components/schemas/alertId'
                  alertType:
                    $ref: '#/components/schemas/alertType'
                  ttsPreAnnouncement:
                    type: string
                    example: This is a pre-announcement for a PSAP Outage Alert.
                    description: >
                      The text-to-speech pre-announcement that will be played
                      before the PSAP Outage Alert is played.
                  alertText:
                    type: string
                    example: This is a PSAP Outage Alert.
                    description: >
                      The alert text that will be shared to the PSAP. This
                      information is shared with PSAPs via email or
                      text-to-speech 

                      based off the PSAP's preferred method of communication.
                      Each PSAP receives the same alert text.
                  triggered:
                    type: boolean
                    example: true
                    description: >
                      Indicates if the alert has been triggered.

                      If true, the alert has been sent to the PSAPs and cannot
                      be triggered again.

                      If false, the alert has not been sent.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    incidentRequest:
      title: Create a new PSAP Outage Alert Incident
      description: Create a new PSAP Outage Alert Incident
      type: object
      properties:
        incidentId:
          $ref: '#/components/schemas/incidentId'
        incidentStartTime:
          type: string
          format: date-time
          example: '2024-08-27T15:30:00Z'
          description: >
            The time the incident occurred. This information is included in the
            initial alert that is sent to the PSAPs.

            This time cannot be updated after the alert has been triggered. This
            must be provided in UTC.
        areasAffected:
          $ref: '#/components/schemas/areasAffected'
        outageImpact:
          $ref: '#/components/schemas/outageImpact'
        expectedRestorationTime:
          $ref: '#/components/schemas/expectedRestorationTime'
        causeOfOutage:
          $ref: '#/components/schemas/causeOfOutage'
        testAlert:
          $ref: '#/components/schemas/testAlert'
      required:
        - incidentId
        - incidentStartTime
        - outageImpact
        - areasAffected
    incidentStatus:
      title: Incident Status
      type: string
      enum:
        - CREATED
        - ACTIVE
        - RESOLVED
        - TESTING
      example: CREATED
      description: >
        The status of the incident.

        - CREATED: The incident has been created but no alerts have been
        triggered.

        - ACTIVE: Alerts have been triggered for the incident and it is ongoing.

        - RESOLVED: The incident has been resolved. No additional alerts can be
        created or triggered for this incident.

        - TESTING: The incident has been created and contains only test alerts.
        Test alerts are only used for testing and are not sent to the PSAPs.
        Test alerts are excluded
                   from the GET /incidents response, and can be retrieved using the includeTestAlerts query parameter via the GET /incidents/{incidentId} endpoint.
    links:
      title: Links
      type: object
      properties:
        href:
          type: string
          description: URI of the link.
          example: /relative/uri
        rel:
          type: string
          description: Specifies the relationship between this link and the resource.
          example: RelatedResource
        method:
          type: string
          description: HTTP method to be used.
          example: GET
    listIncidentsResponse:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          type: array
          items:
            properties:
              incidentId:
                $ref: '#/components/schemas/incidentId'
              status:
                $ref: '#/components/schemas/incidentStatus'
              startTime:
                type: string
                format: date-time
                example: '2024-08-27T15:30:00Z'
                description: The time the incident started.
              lastUpdated:
                type: string
                format: date-time
                example: '2024-08-27T18:30:00Z'
                description: The time the incident was last updated.
              outageImpact:
                $ref: '#/components/schemas/outageImpact'
              areasAffected:
                type: array
                items:
                  type: string
                example:
                  - NC
                  - CO
                description: >-
                  The areas affected by the outage. This can be either a list of
                  FCC IDs, US states, or USA
              alerts:
                type: array
                items:
                  properties:
                    alertId:
                      $ref: '#/components/schemas/alertId'
                    triggerId:
                      type: string
                      example: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
                      description: The unique identifier for the PSAP Outage Alert Trigger.
                    alertTime:
                      type: string
                      format: date-time
                      example: '2024-08-27T15:30:00Z'
                      description: The time the alert was sent.
                    alertType:
                      type: string
                      enum:
                        - INITIAL
                        - UPDATE
                        - ALL_CLEAR
                      example: INITIAL
                      description: The alert type.
                    causeOfOutage:
                      $ref: '#/components/schemas/causeOfOutage'
                    expectedRestorationTime:
                      $ref: '#/components/schemas/expectedRestorationTime'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
        page:
          $ref: '#/components/schemas/pageMeta'
    listTriggersResponse:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          properties:
            triggerId:
              type: string
              format: uuid
              example: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
              description: The unique identifier for the PSAP Outage Alert Trigger.
            alertId:
              $ref: '#/components/schemas/alertId'
            user:
              type: string
              example: myUsername
              description: The user who triggered the PSAP Outage Alert.
            triggerType:
              $ref: '#/components/schemas/triggerType'
            triggerStatus:
              type: string
              enum:
                - RECEIVED
                - PROCESSING
                - COMPLETED
                - FAILED
                - PARTIAL
              example: RECEIVED
              description: >
                The status of the trigger.

                - RECEIVED: The trigger has been received and is awaiting
                processing.

                - PROCESSING: The trigger is being processed.

                - COMPLETED: The trigger has been successfully processed and all
                alerts have been successfully sent.

                - FAILED: The trigger has finished processing, but all alerts
                have failed to send.

                - PARTIAL: The trigger has finished processing, but some alerts
                have failed to send.
            acceptedCount:
              type: integer
              example: 0
              description: The number of PSAP Outage Alerts that were successfully sent.
            invalidCount:
              type: integer
              example: 0
              description: The number of PSAP Outage Alerts that failed to send.
            updated:
              type: string
              format: date-time
              example: '2024-11-08T21:47:04.608Z'
              description: The time the trigger was last updated.
            totalNumber:
              type: integer
              example: 6000
              description: >
                The total number of PSAP Outage Alerts that were attempted to be
                sent or have been sent.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
        page:
          $ref: '#/components/schemas/pageMeta'
    outageImpact:
      type: string
      enum:
        - CALL_COMPLETION
        - CALL_QUALITY
        - CALL_QUALITY_AND_LOCATION_INFORMATION
        - LOCATION_INFORMATION
      description: >
        The impact of the outage. This will be shared with the PSAPs to help
        them understand the impact of the outage.

        - CALL_COMPLETION: Users may be unable to complete 911 calls

        - CALL_QUALITY: Operators may experience call quality issues

        - CALL_QUALITY_AND_LOCATION_INFORMATION: Operators may experience call
        quality issues and loss of location information

        - LOCATION_INFORMATION: Operators may experience loss of location
        information
    pageMeta:
      title: Pagination Metadata
      type: object
      properties:
        pageSize:
          type: integer
          description: The size of pages returned.
          example: 20
        totalElements:
          type: integer
          description: The total number of elements in the collection.
          example: 1000
        totalPages:
          type: integer
          description: >-
            The total number of pages in the collection of the specified
            pageSize.
          example: 500
        pageNumber:
          type: integer
          description: The page number for the page returned.
          example: 0
      nullable: true
    testAlert:
      type: boolean
      example: false
      default: false
      description: >
        Indicates if this alert should be created as a test alert. If true, the
        alert will only be able to be triggered as a test alert.

        Test alerts are not sent to the PSAPs, but instead are sent to the
        pre-configured test phone number and email address from the PSAP Outage
        Alert Settings.
    triggerPsapOutage:
      title: Trigger a PSAP Outage Alert
      type: object
      description: >-
        Trigger a PSAP Outage Alert. This will send alerts to all PSAPs in the
        affected areas of this incident.
      properties:
        alertId:
          $ref: '#/components/schemas/alertId'
        testAlert:
          type: boolean
          example: false
          default: false
          description: >
            Indicates if this is a test alert. If true, the alert will be sent
            to the test phone number and email address instead of the PSAPs.
      required:
        - alertId
    triggerDetails:
      title: Get Trigger Details
      description: Retrieve information about a PSAP Outage Alert Trigger
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          properties:
            triggerId:
              type: string
              example: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
              description: The unique identifier for the PSAP Outage Alert Trigger.
            type:
              $ref: '#/components/schemas/triggerType'
            status:
              $ref: '#/components/schemas/triggerStatus'
            acceptedCount:
              type: integer
              example: 1500
              description: The number of PSAP Outage Alerts that were successfully sent.
            invalidCount:
              type: integer
              example: 0
              description: The number of PSAP Outage Alerts that failed to send.
            updated:
              type: string
              format: date-time
              example: '2024-11-08T21:47:04.608Z'
            user:
              type: string
              example: myUsername
              description: The user who triggered the PSAP Outage Alert.
            totalNumber:
              type: integer
              example: 6000
              description: The total number of PSAP Outage Alerts that will be sent.
            alertId:
              $ref: '#/components/schemas/alertId'
            alertType:
              $ref: '#/components/schemas/alertType'
            alertTime:
              type: string
              format: date-time
              example: '2024-08-27T15:30:00Z'
              description: |
                The time included in the alert that was sent to the PSAPs.
            incidentStartTime:
              type: string
              format: date-time
              example: '2024-08-27T15:30:00Z'
              description: >
                The time the incident started. This information is included in
                the initial alert that is sent to the PSAPs.

                For an INITIAL alert, this is the same as the alertTime.
            causeOfOutage:
              $ref: '#/components/schemas/causeOfOutage'
            outageImpact:
              $ref: '#/components/schemas/outageImpact'
            areasAffected:
              $ref: '#/components/schemas/areasAffected'
            expectedRestorationTime:
              $ref: '#/components/schemas/expectedRestorationTime'
            alerts:
              type: array
              items:
                properties:
                  psapName:
                    type: string
                    example: PSAP Name
                    description: The name of the PSAP that will receive the alert.
                  testContactInformation:
                    type: string
                    example: '+15555555555'
                    description: >
                      The phone number or email address that will receive the
                      test alert.

                      This is only included if the alert is a test alert.
                  psapFccId:
                    type: string
                    example: '123'
                    description: The FCC of the PSAP receiving the alert.
                  alertMethod:
                    type: string
                    enum:
                      - EMAIL
                      - TTS
                    example: TTS
                  status:
                    type: string
                    enum:
                      - PROCESSING
                      - DELIVERED
                      - FAILED
                    example: PROCESSING
                  alertTime:
                    type: string
                    format: date-time
                    example: '2024-08-27T15:30:00Z'
                    description: The time the alert was sent.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
        page:
          $ref: '#/components/schemas/pageMeta'
    triggerStatus:
      type: string
      enum:
        - RECEIVED
        - PROCESSING
        - COMPLETED
        - FAILED
        - PARTIAL
      example: RECEIVED
      description: >
        The status of the trigger.

        - RECEIVED: The trigger has been received and is awaiting processing.

        - PROCESSING: The trigger is being processed.

        - COMPLETED: The trigger has been successfully processed and all alerts
        have been successfully sent.

        - FAILED: The trigger has finished processing, but all alerts have
        failed to send.

        - PARTIAL: The trigger has finished processing, but some alerts have
        failed to send.
    triggerType:
      type: string
      enum:
        - SEND_PSAP_OUTAGE_ALERT
        - TEST_SEND_PSAP_OUTAGE_ALERT
      example: SEND_PSAP_OUTAGE_ALERT
    triggerResponse:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/links'
        data:
          properties:
            triggerId:
              type: string
              format: uuid
              example: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
              description: The unique identifier for the PSAP Outage Alert Trigger.
            user:
              type: string
              example: myUsername
              description: The user who triggered the PSAP Outage Alert.
            triggerType:
              $ref: '#/components/schemas/triggerType'
            triggerStatus:
              $ref: '#/components/schemas/triggerStatus'
            acceptedCount:
              type: integer
              example: 0
            invalidCount:
              type: integer
              example: 0
            updated:
              type: string
              format: date-time
              example: '2024-11-08T21:47:04.608Z'
            totalNumber:
              type: integer
              example: 6000
              description: The total number of PSAP Outage Alerts that will be sent.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    updateIncidentRequest:
      title: Update a PSAP Outage Alert Incident
      description: Update a PSAP Outage Alert Incident
      type: object
      properties:
        incidentStartTime:
          type: string
          format: date-time
          example: '2024-08-27T15:30:00Z'
          description: >
            The time the incident occurred. This information is included in the
            initial alert that is sent to the PSAPs.

            This time cannot be updated after the alert has been triggered. This
            must be provided in UTC.
        areasAffected:
          $ref: '#/components/schemas/areasAffected'
        outageImpact:
          $ref: '#/components/schemas/outageImpact'
        expectedRestorationTime:
          $ref: '#/components/schemas/expectedRestorationTime'
        causeOfOutage:
          $ref: '#/components/schemas/causeOfOutage'
        testAlert:
          $ref: '#/components/schemas/testAlert'
      required:
        - incidentStartTime
        - outageImpact
        - areasAffected
  responses:
    noContentResponse:
      description: No Content
    unauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    methodNotAllowedResponse:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    forbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    notFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    tooManyRequestsResponse:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    badRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    internalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    createAlertResponse:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createAlertResponse'
    createIncidentResponse:
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/incidentResponse'
    updateIncidentResponse:
      description: Updated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/incidentResponse'
    listTriggersResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listTriggersResponse'
          examples:
            listTriggers:
              $ref: '#/components/examples/listTriggersExample'
    listIncidentsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listIncidentsResponse'
          examples:
            listIncidents:
              $ref: '#/components/examples/listIncidentsExample'
    getIncidentResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/incidentResponse'
    triggerPsapOutageResponse:
      description: Accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/triggerResponse'
    getTriggerDetails:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/triggerDetails'
  examples:
    listTriggersExample:
      value:
        links:
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers
            rel: self
            method: GET
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers
            rel: first
            method: GET
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers?offset=1&limit=100
            rel: next
            method: GET
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents/{incidentId}/triggers?offset=1000&limit=100
            rel: last
            method: GET
        data:
          - triggerId: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
            user: myUsername
            alertId: 051997bc-20c5-4896-95ce-3d2d46dfd250
            triggerType: SEND_PSAP_OUTAGE_ALERT
            triggerStatus: RECEIVED
            acceptedCount: 0
            invalidCount: 0
            updated: '2024-11-08T21:47:04.608Z'
            totalNumber: 6000
          - triggerId: 9e8dde3b7c79-adea-40c3-a70e-9e8dde3b7c79
            user: myUsername
            alertId: 3d2d46dfd250-20c5-4896-95ce-3d2d46dfd250
            triggerType: TEST_SEND_PSAP_OUTAGE_ALERT
            triggerStatus: COMPLETED
            acceptedCount: 2
            invalidCount: 0
            updated: '2024-11-08T20:47:04.608Z'
            totalNumber: 2
        errors: []
        page:
          pageSize: 100
          totalElements: 1000
          totalPages: 10
          pageNumber: 0
    listIncidentsExample:
      summary: List Incidents
      value:
        links:
          - href: /accounts/{accountId}/emergency/psap-alerts/incidents
            rel: self
            method: GET
          - href: /accounts/{accountId}/emergency/psap-alerts/incidents
            rel: first
            method: GET
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents?offset=1&limit=20
            rel: next
            method: GET
          - href: >-
              /accounts/{accountId}/emergency/psap-alerts/incidents?offset=1000&limit=20
            rel: last
            method: GET
        data:
          - incidentId: '1'
            status: CREATED
            startTime: '2024-08-27T15:30:00Z'
            lastUpdated: '2024-08-27T18:30:00Z'
            outageImpact: CALL_COMPLETION
            areasAffected:
              - NC
              - CO
            alerts:
              - alertId: 051997bc-20c5-4896-95ce-3d2d46dfd250
                triggerId: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
                alertTime: '2024-08-27T15:30:00Z'
                alertType: INITIAL
                causeOfOutage: a network disruption
                expectedRestorationTime: '2024-08-27T20:00:00Z'
          - incidentId: '1234568'
            status: ACTIVE
            startTime: '2024-08-27T15:30:00Z'
            lastUpdated: '2024-08-27T18:30:00Z'
            outageImpact: LOCATION_INFORMATION
            areasAffected:
              - USA
            alerts:
              - alertId: 95ce95ce95ce-20c5-4896-95ce-3d2d46dfd250
                triggerId: adeaadea-adea-40c3-a70e-9e8dde3b7c79
                alertTime: '2024-08-27T15:30:00Z'
                alertType: INITIAL
                causeOfOutage: unknown
                expectedRestorationTime: '2024-08-27T20:00:00Z'
              - alertId: 20c520c5-20c5-4896-95ce-3d2d46dfd250
                triggerId: ceda15dd-adea-40c3-a70e-9e8dde3b7c79
                alertTime: '2024-08-27T15:30:00Z'
                alertType: UPDATE
                causeOfOutage: a network disruption
                expectedRestorationTime: '2024-08-27T20:00:00Z'
        errors: []
        page:
          pageSize: 2
          totalElements: 10
          totalPages: 5
          pageNumber: 0
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: >-
        Basic authentication is a simple authentication scheme built into the
        HTTP protocol. To use it, send your HTTP requests with an Authorization
        header that contains the word Basic followed by a space and a
        base64-encoded string `username:password`.

        Example: `Authorization: Basic ZGVtbZpwQDU1dzByZA==`
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication (also called token authentication) is an HTTP
        authentication scheme that involves security tokens called bearer
        tokens. The name “Bearer authentication” can be understood as “give
        access to the bearer of this token.” The client must send this token in
        the Authorization header when making requests to protected resources.


        Example: `Authorization: Bearer <token>`
security:
  - Basic: []
  - Bearer: []
tags:
  - name: Incidents
    description: Operations for PSAP Outage Alerts Incidents
  - name: Alerts
    description: Operations for PSAP Outage Alerts
  - name: Trigger
    description: Operations for PSAP Outage Alert Triggers
