Quickstart

Minimal path from zero to a working Public API call.

1. Create an API key

Sign in at app.notiq.io.
Open API & MCP → /api-mcp.
Create a key and copy the secret once (sk_live_…).

Paid (or eligible white-label) access is required — otherwise calls return 403 plan_required.

2. Check credits

export BASE=https://api.notiq.io/public/v1
export KEY=sk_live_…
curl -sS "$BASE/credits" -H "X-API-Key: $KEY"

Expected: { "credits", "topUpCredits", "planId" } plus header X-Request-Id.

3. List accounts and campaigns

curl -sS "$BASE/accounts" -H "X-API-Key: $KEY"
curl -sS "$BASE/campaigns" -H "X-API-Key: $KEY"

Optional — check setup and connect a mailbox (Gmail / Outlook / IMAP):

curl -sS -H "X-API-Key: $KEY" "$BASE/setup"
curl -sS -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"mailboxKind":"gmail"}' "$BASE/accounts/connect-link"

Open connectUrl in a browser, then list accounts again. You can also create manual agents via POST /templates — see Agent setup.

4. Launch a Maps campaign (optional)

curl -sS -X POST "$BASE/campaigns" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"userQuery":"dentists in Austin TX","numberOfSearch":25}'

Poll GET /campaigns/:id (and optionally …/leads) until ready — wait until status is READY_TO_SEND (or later) and extensionStatus is null. Parent status may stay READY_TO_SEND while an extend sets extensionStatus to "FINDING_LEADS". Via MCP, prefer wait_for_campaign_leads (resume on time_budget). Credits debit as email leads are stored.

5. Add a lead by email

curl -sS -X POST "$BASE/campaigns/YOUR_CAMPAIGN_ID/leads" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-1" \
  -d '{"email":"jane@acme.com","fullName":"Jane Doe"}'

status: "created" → creditsCharged: 1.

For many emails, prefer POST …/leads/batch (max 100 per call, 1 credit per create) — see POST …/leads/batch.

6. (Optional) Validate an email and enrich a site

curl -sS -X POST "$BASE/tools/validate-email" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-validate-1" \
  -d '{"email":"jane@acme.com","mode":"mx"}'

curl -sS -X POST "$BASE/tools/enrich-website" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"website":"https://acme.com"}'

mode=mx is free. mode=full charges 1 credit only when ZeroBounce is called. Enrichment is 0 credits.

7. (Optional) Activity & insights

curl -sS "$BASE/activity?type=reply_received&limit=10" -H "X-API-Key: $KEY"
curl -sS "$BASE/insights/overview" -H "X-API-Key: $KEY"

8. (Optional) Batch leads

# Batch add (1 credit per created)
curl -sS -X POST "$BASE/campaigns/YOUR_CAMPAIGN_ID/leads/batch" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-batch-1" \
  -d '{"leads":[{"email":"jane@acme.com","fullName":"Jane Doe"}]}'

# List excluded
curl -sS "$BASE/campaigns/YOUR_CAMPAIGN_ID/leads?excluded=true&limit=5" -H "X-API-Key: $KEY"

# Batch update (0 credits)
curl -sS -X POST "$BASE/campaigns/YOUR_CAMPAIGN_ID/leads/batch-update" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-batch-update-1" \
  -d '{"updates":[{"leadId":"lead_1","excluded":true}]}'

# Batch delete (0 credits, irreversible — confirm first)
curl -sS -X POST "$BASE/campaigns/YOUR_CAMPAIGN_ID/leads/batch-delete" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-batch-delete-1" \
  -d '{"leadIds":["lead_1"]}'

See POST …/leads/batch, POST …/leads/batch-update, and POST …/leads/batch-delete for field tables and soft statuses.

9. (Optional) MCP

Point Cursor / Claude at https://mcp.notiq.io with the same API key (sk_live_…). MCP exposes 48 tools — Public REST mirrors plus MCP-only wait_for_campaign_leads — covering setup, templates, tags, exclude desk, mailbox connect, campaigns, leads, validation, and enrichment. Prefer starting with get_setup_status — see Agent setup and MCP.

Topic	Doc
One-prompt MCP runbook	Agent setup
Full route list	Endpoints
Copy-paste samples	Examples
MCP / Cursor	MCP, Connect MCP
Claude / ChatGPT	Connect Claude / ChatGPT
Errors & limits	Errors, Credits & rate limits
Webhooks	Webhooks
Auth details	Authentication