# Alarm Feedback

To further improve the accuracy of the fraud alarms, BankID Antifraud provides a service that enables alarm recipients to provide feedback on alarms either via a web interface or directly via an API.

## Feedback URI

Each alarm payload includes a signed link that can be used to submit feedback for that specific notification:

```json
{
  ...
  "feedbackUri": "https://<bankid-antifraud-domain>/alarm-feedback/<signed_notification_reference>"
}
```

## API feedback

The API accepts `POST` requests with `application/x-www-form-urlencoded` data with the following fields:

| Field Name  | Description                                                                                                                         | Example                                                                      | Required |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------- |
| `suspicion` | Classification of the alarm                                                                                                         | `VERIFIED_FRAUD`, `VERIFIED_NOT_FRAUD`, `SUSPECTED_FRAUD`                    | Yes      |
| `details`   | Textual description of the fraud case. This is manually reviewed by analysts and used to augment insight into general fraud trends. | `"klarna phishing"`, `"vishing from individual impersonating bank employee"` | No       |

### Response codes

| Code  | Description                                                                                               |
| ----- | --------------------------------------------------------------------------------------------------------- |
| `200` | OK, feedback received                                                                                     |
| `400` | The `suspicion` parameter is likely missing                                                               |
| `401` | The `signed_notification_reference` is malformed and cannot be verified                                   |
| `403` | The link has expired, or the link has been tampered with, causing a mismatch when verifying the signature |

## Web UI feedback

To submit feedback via the web interface, open the feedback URI in a browser with a valid `suspicion` query parameter (`VERIFIED_FRAUD`, `VERIFIED_NOT_FRAUD`, or `SUSPECTED_FRAUD`). Opening a valid feedback URI without this parameter returns HTTP 400.

Opening the URL with this parameter immediately records the selected classification and displays a landing page confirming that the feedback has been received:

```
https://<bankid-antifraud-domain>/alarm-feedback/<signed_notification_reference>?suspicion=VERIFIED_FRAUD
```

This page also presents the option of entering additional details.

![Feedback form](https://docs.stoe.no/bankid-antifraud/img/feedback.png)

![Feedback confirmation](https://docs.stoe.no/bankid-antifraud/img/feedback-thanks.png)

## Notes

> **Resubmission**
>
> Feedback can be safely resubmitted any number of times.

> **Link expiration**
>
> The feedback link has an expiration time, currently set to **30 days**.