---
title: "Search requests using customer, assignment, date, status, and custom-field filters"
method: GET
path: "/requests/search"
tags: ["Requests"]
---

# Search requests using customer, assignment, date, status, and custom-field filters

`GET /requests/search`

## Request

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

Omit `reporting_tags` to search without a tag filter. When supplied, it must contain 1–100 distinct tag names; an empty array returns 422.

## Query parameters

- `query` string
- `match` 'any' | 'all'
- `request_id` integer
- `customer_id` string
- `first_name` string
- `last_name` string
- `email` string, email
- `phone` string
- `open` boolean
- `category_id` integer
- `assigned_staff_id` integer
- `status_id` integer
- `reporting_tags[]` string[]
- `custom_fields[]` string[]
- `before_date` integer
- `after_date` integer
- `closed_before_date` integer
- `closed_after_date` integer
- `relative_date` 'today' | 'tomorrow' | 'yesterday' | 'past_7' | 'past_14' | 'past_30' | 'past_60' | 'past_90' | 'past_365' | 'this_week' | 'this_month' | 'this_year' | 'last_week' | 'last_month' | 'last_year' | 'next_7' | 'next_14' | 'next_30' | 'next_90' | 'next_365' | 'next_week' | 'next_month' | 'next_year' | 'date_is_set' | 'date_is_not_set'
- `order_by` string
- `direction` 'asc' | 'desc'
- `offset` integer
- `per_page` integer
- `include_time_total` boolean

## Response `200`

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
  - `meta` object
    - `offset` integer, required
    - `per_page` integer, required
    - `count` integer, required
    - `has_more` boolean, required
    - `next_offset` integer, nullable, required

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