---
title: "Create a new monitor to track lookalike domains for a specific term."
method: POST
path: "/v1/iris-detect/monitors/"
tags: ["Iris Detect"]
---

# Create a new monitor to track lookalike domains for a specific term.

`POST /v1/iris-detect/monitors/`

## Request

- Base URL: `https://api.domaintools.com`
- URL: `https://api.domaintools.com/v1/iris-detect/monitors/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP basic
  - API key in query parameter `signature`
- TypeScript: <https://skmtc.dev/domaintools/apis/domaintools-iris-api/docs/v1/iris-detect/monitors/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a monitor that begins discovering matching domains immediately.
The monitor `status` is `pending` after creation and changes to `completed`
once initial domain discovery finishes.

Requires the "manage monitors" permission.

## Request body

- CreateMonitorRequest: Request body for creating a new Iris Detect monitor.
  - `term` string, required: The keyword to monitor for domain variations.
  - `match_substring_variations` boolean: When `true`, includes domains where variations of the term appear as substrings within matched domains.
  - `nameserver_exclusions` string[]: Nameserver patterns to exclude. Wildcards (`*`) are accepted. A domain is excluded only when all of its nameservers match an exclusion pattern.
  - `text_exclusions` string[]: Text strings to exclude from results. A domain is excluded when its second-level domain contains any of these strings. Text exclusions don't match top-level domains (TLDs).

## Response `200`

Monitor created successfully.

- CreateMonitorResponse: Response returned after successfully creating a monitor.
  - `status` string: The result of the operation (for example, `created`).
  - `monitor` Monitor: Details of a single Iris Detect monitor.
    - `term` string
    - `match_substring_variations` boolean
    - `nameserver_exclusions` string[]
    - `text_exclusions` string[]
    - `id` string
    - `created_date` string, date-time
    - `updated_date` string, date-time
    - `state` 'active' | 'inactive'
    - `status` string
    - `domain_counts` MonitorDomainCounts: Counts of domains associated with a monitor in various states.
      - `new` integer: The number of new domains discovered.
      - `watched` integer: The number of domains currently on the watchlist.
      - `escalated` integer: The number of domains that have been escalated.
      - `changed` integer: The number of watched domains that have changed.
    - `created_by` string

## Other responses

- `400`: 400: Bad Request. The request was invalid. The response will contain details about the error.
- `401`: 401: Unauthorized. API credentials are required and were not provided, or the provided credentials are not valid.
- `403`: 403: Forbidden. The API credentials provided do not have access to the requested resource or endpoint.
- `422`: 422: Unprocessable Entity. The request is syntactically valid JSON but contains values that fail validation. The response includes per-field error messages.

---

[API](https://skmtc.dev/domaintools/apis/domaintools-iris-api.md) - [All operations](https://skmtc.dev/domaintools/apis/domaintools-iris-api/llms.txt) - [OpenAPI document](https://skmtc.dev/domaintools/apis/domaintools-iris-api/revisions/74a0d057a130?raw)