# Distributing a survey

Share a Simple Feedback survey as a link or as saved QR codes for print, see scans per location, and know what respondents see before it goes live.

This guide gets a published survey in front of respondents: as a link in an email, an app or on a receipt, or as a QR
code on a counter display, a poster or a table card. The shell variables `SF_API`, `SF_KEY` and `SURVEY_ID` are set
up as in the [Quickstart](https://simplefeedback.de/developer/docs/quickstart.md).

## Link or saved QR code

|                        | Survey link               | Saved QR code                            |
| ---------------------- | ------------------------- | ---------------------------------------- |
| Get it with            | `GET /v1/surveys/{id}/qr` | `POST /v1/surveys/{id}/qr-codes`         |
| Scope                  | `surveys:read`            | `qr:write`                               |
| Points at              | `/p/{surveyId}`           | a short link `/q/{slug}`                 |
| Counts scans           | no                        | yes, per code                            |
| Shown in the dashboard | no                        | yes, under its name                      |
| Plan limit             | none                      | counts against your plan's QR-code limit |

Use the survey link where people click: an email, a chat message, your website or app. Use a saved QR code for
everything printed, one per place it hangs. Each code then shows how often it was scanned, so you can tell the
front desk from the waiting room.

## Share the link

```bash
curl "$SF_API/v1/surveys/$SURVEY_ID/qr?includeImage=false" -H "Authorization: Bearer $SF_KEY"
```

```json
{
  "publicUrl": "https://simplefeedback.de/p/4c303674-1dd4-4836-ada7-0092fe2c7df3"
}
```

Put `publicUrl` wherever people click. Without `includeImage=false` the answer also carries `qrDataUrl`, the same
link as a QR code image; it is not saved anywhere, and scans of it are not counted.

## Create a saved QR code

```bash
curl -X POST "$SF_API/v1/surveys/$SURVEY_ID/qr-codes" \
  -H "Authorization: Bearer $SF_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Front desk" }'
```

The answer is `201` with the new code:

```json
{
  "id": "cmv5mnv7t000hn57dw59lohb1",
  "slug": "cKvlVi0lNrlq",
  "name": "Front desk",
  "publicUrl": "https://simplefeedback.de/q/cKvlVi0lNrlq",
  "qrDataUrl": "data:image/png;base64,iVBORw0KGgo..."
}
```

`name` is how the code appears in the dashboard, so name it after where it goes. `publicUrl` is the code's short
link: opening it counts a scan and then shows the survey.

A key needs the scope `qr:write`, which `surveys:write` does not include. Without it the call answers
`403 INSUFFICIENT_SCOPE`. When the plan has no room for another code, it answers `409 TIER_LIMIT_REACHED` and
creates nothing.

> **Note:** Every call creates a new code. Store the `id` and `publicUrl` you get back and reuse them, instead of
> creating a code each time you print. To retry after a timeout without creating a second code, send the same
> [`Idempotency-Key`](https://simplefeedback.de/developer/docs/overview.md#conventions) again.

## Save the image

`qrDataUrl` is a 512 × 512 PNG with its white border included. To write it to a file:

```bash
curl -s -X POST "$SF_API/v1/surveys/$SURVEY_ID/qr-codes" \
  -H "Authorization: Bearer $SF_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Waiting room" }' \
  | jq -r '.qrDataUrl' | sed 's/^data:image\/png;base64,//' | base64 -d > waiting-room.png
```

Keep the white border when you place the image: a scanner needs it to find the code. For your own design, generate
a QR code of `publicUrl` with any library; scans are counted as long as it encodes that link.

## Before it goes live

Respondents can open a survey only while it is published. A link or code of a draft leads to a page that says the survey
wasn't found, so [publish](https://simplefeedback.de/developer/docs/building-a-survey.md#publish-it) before you print.

To list your codes, read their scans, point a printed code at another survey or delete it, see
[QR codes](https://simplefeedback.de/developer/docs/qr-codes.md).

## One response per person

A link or a saved QR code can be answered by anyone who has it. When every respondent should answer exactly once,
for example once per ticket, receipt or course place, give each one a personal code instead. See
[Single-use codes](https://simplefeedback.de/developer/docs/single-use-codes.md).