# List options for a filter (https://terac.com/docs/developers/reference/getFilterOptions)

`GET https://terac.com/api/external/v2/filters/{filter_slug}/options`

Lists the allowed values for one filter; send an option's `id`, not its `name`, as the value in an opportunity's `filters`. `search` matches ids, names and alternate names, ignoring case and accents. Results are paged by number with `page` and `per_page`, and `meta.total` counts every match. State options need `country_id`, and city options need `country_id` with an optional `state_id`; without `country_id` both lists are empty. An unknown `filter_slug` returns 400.

## Authorization

Requires a Bearer token via the `Authorization` header.

```
Authorization: Bearer <token>
```

## Path Parameters

- `filter_slug` (string) **(required)**: A filter's `slug` from `GET /filters`, such as `multi_select--country`. A filter with no `options_url` returns an empty list.

## Query Parameters

- `search` (string): Text to match against option ids, names and alternate names, ignoring case and accents.
- `page` (integer): 1-based page number. Defaults to 1.
- `per_page` (integer): Options per page, from 1 to 100. Defaults to 50.
- `country_id` (string): ISO 3166-1 alpha-2 country code, such as `US`. `multi_select--state` and `multi_select--city` list nothing without it; other filters ignore it.
- `state_id` (string): Narrows `multi_select--city` to one state or province: the state option's `id` (`US-CA`) or its bare code (`CA`). Other filters ignore it.

## Responses

### 200: One page of the filter's allowed values, with the total match count.

- `data` (array) **(required)**
  - `id` (string) **(required)**
  - `name` (string) **(required)**
- `meta` (object) **(required)**
  - `total` (number) **(required)**
  - `page` (number) **(required)**
  - `per_page` (number) **(required)**
### 400: Invalid input data

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**
### 401: The API key is missing, invalid, disabled, expired or revoked, its owner no longer exists, or it is not linked to an organization. The body is nested under `error`.

- `error` (object) **(required)**
  - `code` (string) **(required)**: one of: `UNAUTHORIZED`: The error code.
  - `message` (string) **(required)**: What went wrong.
### 403: Either the account that owns the API key is banned or deleted (from the key check, nested under `error`), or the key's owner lacks the organization permission this operation needs (from the operation, with `code` and `message` at the top level).

- One of: API key error (403)
  - `error` (object) **(required)**
    - `code` (string) **(required)**: one of: `FORBIDDEN`: The error code.
    - `message` (string) **(required)**: What went wrong.
- One of: Insufficient access error (403)
  - `message` (string) **(required)**: The error message
  - `code` (string) **(required)**: The error code
  - `issues` (array): An array of issues that were responsible for the error
    - `message` (string) **(required)**
### 404: Not found

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**
### 429: The API key is rate limited. A key accepts 100 requests, then refuses every request until more than 60 seconds pass with no accepted request; refused requests do not extend the wait. Wait the number of seconds in `Retry-After`, then retry. The body is nested under `error`.

- `error` (object) **(required)**
  - `code` (string) **(required)**: one of: `RATE_LIMITED`: The error code.
  - `message` (string) **(required)**: What went wrong.
### 500: Internal server error

- `message` (string) **(required)**: The error message
- `code` (string) **(required)**: The error code
- `issues` (array): An array of issues that were responsible for the error
  - `message` (string) **(required)**