---
title: "Create a request"
method: POST
path: "/requests"
tags: ["Requests"]
---

# Create a request

`POST /requests`

## Request

- Base URL: `https://helpspot.example.com/api/v2`
- URL: `https://helpspot.example.com/api/v2/requests`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

### 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.

```http
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.

## Headers

- `Idempotency-Key` string

## Request body

- StoreRequestRequest
  - `note` string, required
  - `category_id` integer, required
  - `opened_at` integer
  - `note_type` integer
  - `note_is_html` boolean
  - `reporting_tags` string[]
  - `title` string
  - `opened_by_staff_id` integer
  - `assigned_staff_id` integer
  - `open` boolean
  - `status_id` integer
  - `portal_id` integer
  - `customer_id` string, nullable
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `email` string, email, nullable
  - `phone` string, nullable
  - `urgent` boolean
  - `opened_via` integer
  - `skip_custom_checks` boolean
  - `email_from_mailbox_id` integer
  - `email_cc` string, nullable
  - `email_bcc` string, nullable
  - `email_to` string, nullable
  - `notify_staff_ids` integer[]
  - `custom_fields` string[]
  - `attachments` object[]
    - `filename` string, required
    - `mime_type` string, required
    - `content_base64` string, required

## Response `201`

Request resource. Fields depend on visibility and endpoint; see the Requests guide.

- object
  - `data` RequestResource, required
    - `id` integer
    - `title` string, nullable
    - `customer_id` string, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `email` string, nullable
    - `phone` string, nullable
    - `category_id` integer, nullable
    - `status_id` integer, nullable
    - `assigned_staff_id` integer, nullable
    - `opened_by_staff_id` integer, nullable
    - `portal_id` integer, nullable
    - `opened_via` integer
    - `opened_via_id` integer, nullable
    - `email_from_mailbox_id` integer, nullable
    - `open` boolean
    - `urgent` boolean
    - `trashed` boolean
    - `opened_at` string, date-time, nullable
    - `closed_at` string, date-time, nullable
    - `trashed_at` string, date-time, nullable
    - `last_reply_by_staff_id` integer, nullable
    - `time_total_seconds` integer
    - `unread` boolean
    - `summary` string, nullable
    - `access_key` string, nullable
    - `ai_summary` string, nullable
    - `out_of_office_detected` boolean
    - `auto_categorized` boolean
    - `custom_fields` object[]
      - `id` integer, required
      - `value` union, required
        - string
        - integer
        - boolean
    - `history` object[]
      - `id` integer
      - `request_id` integer
      - `author_id` integer
      - `created_at` string, date-time, nullable
      - `body_html` string, nullable
      - `public` boolean
      - `initial` boolean
      - `pinned` boolean
      - `external` boolean
      - `attachments` object[]
        - `id` integer
        - `filename` string, nullable
        - `mime_type` string, nullable
        - `content_id` string, nullable
        - `public_url` string, nullable
        - `private_url` string, nullable
    - `reporting_tags` object[]
      - `id` integer
      - `name` string
    - `subscriber_ids` integer[]
    - `survey_responses` object[]
      - `survey_id` integer
      - `name` string, nullable
      - `scoring_type` string, nullable
      - `score` integer, nullable
      - `comment` string, nullable
      - `responded_at` string, date-time, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `405`: Method Not Allowed
- `406`: Not Acceptable
- `409`: Conflict
- `413`: Content Too Large
- `422`: Validation error
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/helpspot/apis/helpspot-api-v2.md) · [All operations](https://skmtc.dev/helpspot/apis/helpspot-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/helpspot/apis/helpspot-api-v2/revisions/794dac0002c0?raw)