# Feedback API

The Feedback API lets you submit feedback, report bugs, suggest features, or contact support from within the platform or from the command line. Submissions are routed automatically to the right team (e.g. bugs to engineering, feature ideas to product, help requests to support).

**Category:** [Platform](https://docs.zipwire.io/api#platform) (general)

***

## Endpoints

### Submit feedback (authenticated web users)

**POST** `/api/v1/feedback`

Submit feedback when logged in to the web application.

**Request body:**

```json
{
  "feedbackType": "BugReport",
  "message": "The app crashes when I click the invoice button"
}
```

**Feedback types:**

| Type              | Use for                             |
| ----------------- | ----------------------------------- |
| `BugReport`       | Bugs or unexpected behaviour        |
| `FeatureRequest`  | New feature or enhancement ideas    |
| `GeneralFeedback` | General comments or feedback        |
| `SupportRequest`  | Help or support requests            |
| `Other`           | Anything that doesn’t fit the above |

**Success (200):**

```json
{
  "status": "submitted",
  "message": "Thank you for your feedback! (ID: ABC123DEF456)"
}
```

The response includes a unique feedback ID so you can refer to it if needed.

**Error (400):**

```json
{
  "error": "feedback_message_too_long",
  "message": "Feedback must be 1000 characters or less."
}
```

**Error codes:**

| Code                        | HTTP | Meaning                                                   |
| --------------------------- | ---- | --------------------------------------------------------- |
| `feedback_message_empty`    | 400  | Message is empty or only whitespace                       |
| `feedback_message_too_long` | 400  | Message is over 1000 characters                           |
| `feedback_type_invalid`     | 400  | Feedback type is missing or not one of the allowed values |
| `feedback_routing_failed`   | 500  | Submission was received but delivery to the team failed   |

***

### Submit feedback via API key (CLI / scripts)

**POST** `/api/feedback/{apiKey}`

Submit feedback from the command line or a script using an API key. Useful for the Zipwire CLI or automation.

**Query parameters:**

| Parameter      | Required | Description                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| `feedbackType` | Yes      | One of: `BugReport`, `FeatureRequest`, `GeneralFeedback`, `SupportRequest`, `Other` |
| `text`         | Yes      | Your message (max 1000 characters). Underscores in the URL are converted to spaces. |

**Example:**

```bash
curl -X POST \
  "https://zipwire.io/api/feedback/YOUR_API_KEY?feedbackType=BugReport&text=App_crashes_on_startup"
```

**Success (200):** Plain text body, e.g.\
`Thank you for your feedback! (ID: ABC123DEF456)`

**Error (400):** Plain text body, e.g.\
`Feedback type is required. Valid types: BugReport, FeatureRequest, GeneralFeedback, SupportRequest, Other`

**Error (403):** Invalid or missing API key.

***

## Feedback types in detail

| Type                | Who receives it | Examples                                                            |
| ------------------- | --------------- | ------------------------------------------------------------------- |
| **BugReport**       | Engineering     | "App crashes when I click submit", "Invoice numbers are duplicated" |
| **FeatureRequest**  | Product         | "Add dark mode", "Export to CSV", "Calendar integration"            |
| **GeneralFeedback** | Product         | "Great work on the new UI", "Onboarding was smooth"                 |
| **SupportRequest**  | Support (email) | "How do I export my data?", "I forgot my password"                  |
| **Other**           | Product         | Anything else                                                       |

Types are case-insensitive (`BugReport`, `bugreport`, `BUGREPORT` are all valid).

***

## Examples

### Web app (JavaScript)

```javascript
const response = await fetch('/api/v1/feedback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({
    feedbackType: 'BugReport',
    message: 'Invoice PDF fails to generate for clients with special characters in names'
  })
});
const result = await response.json();
console.log(result.message);
```

### CLI

```bash
zw feedback submit --type FeatureRequest --message "Add dark mode to the dashboard"
```

Or with curl:

```bash
curl -X POST \
  "https://zipwire.io/api/feedback/YOUR_API_KEY?feedbackType=FeatureRequest&text=Add_dark_mode_to_dashboard"
```

### Simple HTML form

```html
<form id="feedback-form">
  <select name="feedbackType" required>
    <option value="">Select feedback type</option>
    <option value="BugReport">Bug Report</option>
    <option value="FeatureRequest">Feature Request</option>
    <option value="GeneralFeedback">General Feedback</option>
    <option value="SupportRequest">Support Request</option>
    <option value="Other">Other</option>
  </select>
  <textarea name="message" maxlength="1000" required></textarea>
  <button type="submit">Send Feedback</button>
</form>

<script>
document.getElementById('feedback-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(e.target);
  const response = await fetch('/api/v1/feedback', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      feedbackType: formData.get('feedbackType'),
      message: formData.get('message')
    })
  });
  const result = await response.json();
  alert(result.message);
});
</script>
```

***

## Troubleshooting

**Feedback not received?**

1. Check the success response for the feedback ID and keep it for reference.
2. **Web endpoint:** Ensure you send a valid `Authorization: Bearer ...` token.
3. **API key endpoint:** Check that the API key is correct and associated with your account.
4. Keep the message between 1 and 1000 characters.

**"Invalid feedback type"**

Use exactly one of: `BugReport`, `FeatureRequest`, `GeneralFeedback`, `SupportRequest`, `Other` (case does not matter).

**Message too long**

Maximum length is 1000 characters. Truncate or shorten your message.

***

## Rate limiting

There is no rate limiting on feedback submissions. Please use the API responsibly.