Create a request

Safe retries

POST /requests accepts an optional Idempotency-Key header. Generate a unique key for each new request, for example a UUID. Keys are case-sensitive, scoped to the authenticated staff member and this endpoint, and contain 1–128 ASCII letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit. Without a key, each call creates a new request.

POST /api/v2/requests
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "note": "Cannot sign in",
  "email": "customer@example.com",
  "category_id": 1
}

• Retry with the same key and payload after a network failure. A completed operation returns its original HTTP 201 response with Idempotency-Replayed: true, without running creation, triggers, or notifications again. JSON and XML are both supported; changing Accept or format does not change the operation.
• Completed responses are available for 24 hours after completion. After that, the key can create a new request. Never reuse keys for unrelated operations.
• A different payload with the same retained key returns 409 idempotency_conflict. Object-key order does not matter; array order, explicit nulls, and omitted fields do. Send the same field values and types on retries.
• Authentication and input validation run on every call. Validation failures do not reserve a key. If access to the created request is subsequently lost, a replay returns only data.id, not the cached customer fields.
• A running operation, an execution failure, or an interrupted operation without a recorded result returns 409 idempotency_unresolved on retry. These keys do not automatically expire. A request or notifications may already exist: do not switch to a new key or omit the key to force a retry. Contact support with the response request ID, the idempotency key, and the staff account if the conflict persists.

Idempotency prevents re-execution for retained keys; it does not make request creation, file storage, and delivery of external notifications one atomic operation. Successful response bodies are stored encrypted. Other write endpoints do not support idempotency keys.