# Feedback API reference

> Report bugs, feature requests, feedback or questions to the SignWith team on the user's
behalf. Meant for API clients and AI agents such as the SignWith MCP server.

Source: https://signwith.co/docs/api/feedback · Updated 2026-10-02

## Send feedback to the SignWith team

`POST https://app.signwith.co/api/v1/feedback`

Read-only keys can call this. Accepts `Idempotency-Key`.

Sends a bug report, feature request, general feedback or question to the SignWith team on
the user's behalf. This is how API clients and AI agents — for example the SignWith MCP
server (recorded with source `mcp`) — pass on problems or ideas the user mentions, without
the user having to leave their tool. The team is notified straight away.

Include what happened and, in `context`, identifiers that help reproduce it (the failing
`error_code`, `signature_request_id`, etc.). Don't include passwords, API keys or document
contents. Read-only keys may call it. Limited to 20 messages per user per hour
(`429 rate_limited`).

### Headers

| Name | Type | Description |
| --- | --- | --- |
| `Idempotency-Key` | string | A unique value (e.g. a UUID) that makes retries of this request safe. A successful response is stored for 24 hours and replayed for retries with the same key.  |

### Request body (`application/json`)

- `type` (string, one of `bug`, `feature_request`, `feedback`, `question`, default `"feedback"`). What kind of message this is.
- `message` (string, required, 1 to 5,000 characters). The feedback in plain language. Up to 5,000 characters.
- `context` (object). Optional details that help the team investigate. Only the keys below are kept; others are dropped.
  - `client` (string). Name of the client or AI assistant, e.g. `claude-desktop`.
  - `client_version` (string).
  - `tool` (string). The tool or operation the user was using.
  - `signature_request_id` (integer or string).
  - `template_id` (integer or string).
  - `error_code` (string). The API `error.code` the user ran into, if any.
  - `request_id` (string).

### Request sample

cURL:

```bash
curl -X POST https://app.signwith.co/api/v1/feedback \
  -H "Authorization: Bearer $SIGNWITH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "bug",
  "message": "Prefilling the \"Start date\" field with 2026-11-01 shows an empty date to the signer.",
  "context": {
    "client": "claude-desktop",
    "client_version": "1.4.2",
    "tool": "send_signature_request",
    "signature_request_id": 4812,
    "template_id": 311
  }
}'
```

Node:

```javascript
const response = await fetch('https://app.signwith.co/api/v1/feedback', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIGNWITH_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    type: 'bug',
    message: 'Prefilling the "Start date" field with 2026-11-01 shows an empty date to the signer.',
    context: {
      client: 'claude-desktop',
      client_version: '1.4.2',
      tool: 'send_signature_request',
      signature_request_id: 4812,
      template_id: 311,
    },
  }),
})

console.log(response.status, await response.json())
```

Python:

```python
import os
import uuid

import requests

response = requests.post(
    "https://app.signwith.co/api/v1/feedback",
    headers={
        "Authorization": f"Bearer {os.environ['SIGNWITH_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "type": "bug",
        "message": "Prefilling the \"Start date\" field with 2026-11-01 shows an empty date to the signer.",
        "context": {
            "client": "claude-desktop",
            "client_version": "1.4.2",
            "tool": "send_signature_request",
            "signature_request_id": 4812,
            "template_id": 311,
        },
    },
)

print(response.status_code, response.json())
```

### Response 201

The feedback was received.

```json
{
  "object": "feedback",
  "id": 57,
  "type": "bug",
  "status": "received",
  "message": "Thanks! The SignWith team has been notified."
}
```

### Errors

| Status | Meaning |
| --- | --- |
| 400 | The request body is not valid JSON. |
| 401 | The API key is missing, invalid or expired, or its account has been archived. |
| 409 | A request with the same `Idempotency-Key` is still being processed. Retry shortly. |
| 422 | The request is valid JSON but can't be processed. See `error.code`; the codes each endpoint can return are described in the endpoint's description and in the error table above.  |
| 429 | Rate limit exceeded (`rate_limited`, with `Retry-After`); more than 20 `POST /feedback` messages in an hour (`rate_limited`, with `Retry-After`: seconds until the next clock hour); or — for `POST /signature_requests/{id}/remind` — signers were reminded less than an hour ago (`remind_too_soon`, with `Retry-After`).  |
| 500 | Something went wrong on SignWith's side. It's safe to retry with the same `Idempotency-Key`. |

## The feedback object

Anchor: https://signwith.co/docs/api/feedback#the-feedback-object

- `object` (string, required, always `feedback`).
- `id` (integer, required).
- `type` (string, required, one of `bug`, `feature_request`, `feedback`, `question`).
- `status` (string, required, always `received`).
- `message` (string, required). A confirmation you can show to the user.