---
title: "Create a number monitor"
method: POST
path: "/monitors"
tags: ["Monitoring"]
---

# Create a number monitor

`POST /monitors`

## Request

- Base URL: `https://app.1lookup.io/api/v1`
- URL: `https://app.1lookup.io/api/v1/monitors`
- Auth: HTTP bearer

Number Monitoring (beta): rechecks a list of phone numbers daily or weekly and records an event when status, line type, carrier, porting, DNC listing or spam risk changes. Creating and managing monitors is free; each recheck is charged like a phone validation, plus a spam check when `include_spam_check` is on. Up to 3 active monitors per account.

## Request body

- object
  - `name` string, required: Monitor name, up to 255 characters.
  - `frequency` 'daily' | 'weekly'
  - `include_spam_check` boolean: Also recheck spam risk.
  - `alert_email` boolean: Email the account when a number changes.
  - `webhook_url` string: https URL to call on each change. The response carries a `webhook_secret` to verify the `X-1Lookup-Signature` header.

## Response `201`

Monitor created.

- object
  - `success` true, required
  - `data` object, required
    - `monitor` NumberMonitor, required
      - `id` string, required
      - `name` string, required
      - `frequency` 'daily' | 'weekly', required
      - `include_spam_check` boolean, required
      - `alert_email` boolean, required
      - `webhook_url` string, nullable, required
      - `active` boolean, required
      - `number_count` integer: Only in the list response.
      - `last_run_at` string, nullable: Only in the list response.
      - `created_at` string, date-time, required
    - `webhook_secret` string, nullable, required: Returned once, at creation, when a webhook was set.

## Other responses

- `400`: `INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format; `INVALID_WEBHOOK_URL`: `webhook_url` is not an https URL that can receive webhooks
- `401`: `UNAUTHORIZED`: Invalid or missing API key
- `403`: `UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key
- `409`: `LIMIT_REACHED`: An account or monitor limit was reached (active monitors, or numbers or contacts per monitor); `NO_LIST_OWNER`: The organization has no active owner or admin to own the monitor
- `429`: `RATE_LIMIT_EXCEEDED`: Too many requests
- `500`: `INTERNAL_ERROR`: Internal server error
- `503`: `SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds

---

[API](https://skmtc.dev/1lookup/apis/1lookup-api.md) · [All operations](https://skmtc.dev/1lookup/apis/1lookup-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1lookup/apis/1lookup-api/revisions/57b6d8ba04ac?raw)