---
title: "Create an Unwanted Access Rule"
method: POST
path: "/v1/unwanted_access_rules"
tags: ["Unwanted Access Rules"]
---

# Create an Unwanted Access Rule

`POST /v1/unwanted_access_rules`

Creates a new Unwanted Access Rule associated with your account, an organization, or a specific identity.

**Rule logic.** Provide exactly one of `country_code`, `vpn`, `ip_address`, or `logic`:
  - Omit `logic` and supply `country_code`, `vpn`, or `ip_address` to create `standard` rules. Provide a single value to create one rule, or a comma-separated list to create one `standard` rule per value in a single request. All rules share the same scope, type, and schedule, and are created atomically. If any value fails validation (for example a duplicate rule already exists, or an `ip_address` value is not a valid address or CIDR range), no rules are created. Duplicate values in the list are ignored. Only the last created rule is returned in the response. `ip_address` rules must be `expected`.
  - Set `logic` as `catchall` (with `category`) to create a catchall rule that matches every value in the category. Catchalls must be `unauthorized` and may only be scoped to the account or an organization. An account or organization may have at most one catchall per category.
  - Set `logic` as `catchall_exception` (with `category`) to create an exception that opts an organization out of an account-level catchall. Exceptions must be `expected`, may only be scoped to an organization, and must omit `starts_at`/`expires_at`.

**Scope.** The rule scope is determined by the IDs supplied: provide `identity_id` to scope the rule to a single identity, `organization_id` to scope it to an organization. Omitting both scopes the rule at the account level.

## Request body

- UnwantedAccessRuleCreationParameters — Create an Unwanted Access Rule
  - `identity_id` integer — Scope the rule to a specific identity. Mutually exclusive with `organization_id`. If neither is provided, the rule is scoped to the account.
  - `organization_id` integer — Scope the rule to an organization. Mutually exclusive with `identity_id`. If neither is provided, the rule is scoped to the account.
  - `country_code` string — ISO 3166-1 alpha-2 country code(s) this rule should match. Provide for `standard` rules. Accepts a single code or a comma-separated list, which creates one rule per code. Mutually exclusive with `vpn`, `ip_address`, and `logic`.
  - `vpn` string — Tunnel operator name(s) this rule should match. Provide for `standard` rules. Accepts a single name or a comma-separated list, which creates one rule per name. Mutually exclusive with `country_code`, `ip_address`, and `logic`.
  - `ip_address` string — IP address(es) or CIDR range(s) this rule should match. Provide for `standard` rules, which must be of type `expected`. Each value must be a valid IPv4 or IPv6 address or CIDR range. Accepts a single address or a comma-separated list, which creates one rule per address. Mutually exclusive with `country_code`, `vpn`, and `logic`.
  - `logic` 'catchall' | 'catchall_exception' — Rule logic. Set to `catchall` to match every value in a category, or `catchall_exception` to opt an organization out of an account-level catchall. Omit to create a `standard` rule (in which case `country_code`, `vpn`, or `ip_address` is required). Mutually exclusive with `country_code`, `vpn`, and `ip_address`.
  - `type` 'expected' | 'unauthorized', required — Whether matching access is `expected` or `unauthorized`. Must be `unauthorized` when rule `logic` is `catchall` and `expected` when rule `logic` is `catchall_exception`.
  - `starts_at` string, date — UTC date (YYYY-MM-DD) when the rule becomes active. Omit for `expected` rules that should start immediately. Must be omitted for `unauthorized` rules and for rules with `logic` of `catchall` or `catchall_exception`.
  - `expires_at` string, date — UTC date (YYYY-MM-DD) when the rule expires. Omit for `expected` rules that should never expire. Must be omitted for `unauthorized` rules and for rules with `logic` of `catchall` or `catchall_exception`.
  - `notes` string — Optional free-text note to attach to the rule.
  - `category` 'country' | 'vpn' — Category that the catchall or exception applies to. Required when `logic` is provided.

## Response `201`

Create an Unwanted Access Rule

- object
  - `unwanted_access_rule` UnwantedAccessRule — UnwantedAccessRule model
    - `id` integer — A Huntress-unique identifier for the rule.
    - `applied_to` unknown
    - `category` 'country' | 'vpn' | 'ip_address' — The category of attribute this rule governs.
    - `country_code` string — ISO 3166-1 alpha-2 country code this rule matches. Null unless `category` is `country`.
    - `vpn` string — Tunnel operator name this rule matches. Null unless `category` is `vpn`.
    - `ip_address` string — IP Address this rule matches. Null unless `category` is `ip_address`.
    - `type` 'expected' | 'unauthorized' — Whether matching access is expected or unauthorized.
    - `status` 'active' | 'scheduled' | 'expired' | 'not_applicable' — The current status of the rule.
    - `logic` 'catchall_exception' | 'catchall' | 'standard' — How the rule matches: `standard` matches a specific value within the `country`, `vpn`, or `ip_address` category, `catchall` matches all values in the category, and `catchall_exception` opts the resource out of an inherited catchall.
    - `note` string — Optional free-text note the rule author attached to the rule.
    - `starts_at` string, date-time — ISO-8601 formatted timestamp for when this rule becomes active. Null for unscheduled rules.
    - `expires_at` string, date-time — ISO-8601 formatted timestamp for when this rule expires. Null if the rule does not expire.
    - `created_by` string — The name of the user who created this rule, or "Deleted" if the user has been removed.
    - `created_at` string, date-time — ISO-8601 formatted timestamp for when this rule was created.
    - `updated_at` string, date-time — ISO-8601 formatted timestamp for when this rule was last updated.

## Other responses

- `400` — Invalid request parameters.
- `403` — There was an issue with your API credential or permissions.
- `404` — Specified organization or identity not found.
- `422` — Invalid creation parameters. The rule failed validation — for example, a duplicate rule already exists, an ip_address value is not a valid IPv4 or IPv6 address or CIDR range, the scope is not allowed for the chosen logic, or the type/schedule fields conflict with the rule logic.

---

[API](https://skmtc.net/huntress/apis/huntress-api-reference.md) · [All operations](https://skmtc.net/huntress/apis/huntress-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/huntress/huntress-api-reference/revisions/94acb422c07d/schema)