Username Availability API: Integrate Name Checking Into Your App

If you're building a product that needs username or brand name checking, you already know the pain. Each social platform has its own URL patterns, its own bot detection, its own quirks around redirects and login walls. Domain registrars have WHOIS rate limits. Trademark databases require parsing legal filings. Building all of this from scratch is a multi-week project that never stops needing maintenance.

NameSniper's API handles this for you. One POST request checks domain availability across 20+ TLDs, username availability across 16 social platforms, brand quality scoring, and USPTO trademark conflicts. This post walks through integration from first request to production deployment, with working code examples in curl, TypeScript, and Python.

Why Build Username Checking Into Your Product?

There are four categories of products where programmatic name checking adds real value.

SaaS onboarding flows. When a user signs up for your platform and picks a username, you can immediately show them whether that name is available across the internet. It's a retention feature: users who secure a consistent brand identity early are more invested in your platform. Tools like Linktree and Carrd do this during signup, and the conversion data supports it.

Brand agency and naming tools. Agencies evaluating name candidates for clients need to check 50 to 100 names per engagement. Doing that manually takes days. An API integration turns it into a batch job that runs in minutes. If you're building an internal tool for a branding agency, this is the core integration.

Startup name generators. If you're building a naming tool, the hard part isn't generating names -- it's checking availability. Anyone can combine syllables and dictionary words. The differentiation is telling users which of those generated names are actually usable. Without availability data, you're generating noise.

AI agents and automated workflows. AI agents helping users start businesses, register domains, or build personal brands need real-time name availability data. An agent that suggests "acmebrand" without knowing it's taken on every platform is not useful. The Model Context Protocol (MCP) makes this integration straightforward, which we'll cover below.

Getting Started

You need three things:

1. A NameSniper account with a Pro or Business plan. Pro is $7/month (1 API key). Business is $24/month (5 API keys, webhooks, higher rate limits).
2. An API key, generated from your dashboard.
3. The base URL: https://namesniper.pro/api/v1

Authentication uses the Authorization header with a Bearer token:

Authorization: Bearer ns_sk_your_key_here

All endpoints accept and return JSON. The full API reference is at /docs/api.

Quick Start: Check a Name

The /check endpoint is the flagship. It runs domains, social media, brand scoring, and trademark screening in a single call.

curl:

curl -X POST https://namesniper.pro/api/v1/check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -d '{"name": "acmebrand"}'

TypeScript:

const response = await fetch('https://namesniper.pro/api/v1/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.NAMESNIPER_API_KEY}`,
  },
  body: JSON.stringify({ name: 'acmebrand' }),
});

const data = await response.json();
console.log(data);

Python:

import requests

response = requests.post(
    "https://namesniper.pro/api/v1/check",
    headers={"Authorization": "Bearer ns_sk_your_key_here"},
    json={"name": "acmebrand"},
)

data = response.json()
print(data)

The response follows a consistent structure across all endpoints:

{
  "success": true,
  "data": {
    "name": "acmebrand",
    "domains": {
      "results": [
        { "domain": "acmebrand.com", "available": false, "method": "dns" },
        { "domain": "acmebrand.dev", "available": true, "method": "dns" }
      ],
      "summary": { "available": 15, "taken": 4 }
    },
    "social": {
      "results": [
        { "platform": "github", "status": "available", "confidence": 95 },
        { "platform": "twitter", "status": "taken", "confidence": 90 }
      ],
      "summary": { "available": 10, "taken": 4 }
    },
    "brandScore": {
      "overall": 82,
      "memorability": { "score": 85 },
      "seo": { "score": 78 },
      "professional": { "score": 83 }
    },
    "trademark": {
      "riskLevel": "low",
      "matches": []
    }
  },
  "meta": {
    "plan": "pro",
    "duration": 3200,
    "timestamp": "2026-02-23T12:00:00Z"
  }
}

A few things to note about the response:

• Confidence scores on social results range from 50 to 95. High confidence (90-95) means the platform returned a clear signal like a 404. Medium confidence (70-85) means the result is likely correct but the platform's response was ambiguous. Low confidence (50-65) means bot detection or rate limiting may have interfered. See our username availability checker guide for details on why confidence varies by platform.
• Domain checking uses a 3-tier verification system: HTTP HEAD first (~100ms), then DNS over HTTPS (~500ms), then WhoAPI fallback (~1200ms). The method field tells you which tier resolved the check.
• Brand score and trademark are included by default. You can disable them by passing "brandScore": false or "trademark": false in the request body to speed up the response.

Checking Specific Resources

If you only need part of the data, the focused endpoints are faster because they skip the checks you don't need.

Domains Only

curl -X POST https://namesniper.pro/api/v1/check/domains \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "acmebrand", "tlds": ["com", "io", "dev", "app"]}'

The tlds parameter is optional. If omitted, it checks 9 default TLDs: com, org, net, app, dev, tech, io, co, and ai.

Social Media Only

curl -X POST https://namesniper.pro/api/v1/check/social \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "acmebrand", "platforms": ["github", "twitter", "youtube", "instagram"]}'

The platforms parameter is optional. If omitted, it checks all 16 supported platforms: YouTube, Reddit, TikTok, Instagram, Twitter/X, Telegram, GitHub, npm, Twitch, Threads, Bluesky, Pinterest, Snapchat, Mastodon, Product Hunt, and LinkedIn. All platforms are checked concurrently using Promise.allSettled, so checking 4 platforms takes roughly the same time as checking 16.

Brand Scoring

curl -X POST https://namesniper.pro/api/v1/brand-score \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "acmebrand"}'

Returns a 0-100 overall score with breakdowns for memorability (length, phonetics, uniqueness, simplicity), SEO potential (keyword density, searchability, brandability, domain potential), and professional appeal (business appeal, international friendliness, industry neutrality, scalability). Each factor includes a score and a human-readable feedback string.

Trademark Screening

curl -X POST https://namesniper.pro/api/v1/trademark \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "acmebrand", "includeVariations": true}'

Screens the USPTO trademark database for conflicts. Returns a risk level (low, medium, high), matching trademarks, and similarity analysis using Levenshtein distance. The includeVariations flag also checks common misspellings and variations of the name.

AI Name Generation via API

The /generate endpoint uses GPT-4o-mini to create brand name candidates from a business description, then runs a batch DNS check on each one:

curl -X POST https://namesniper.pro/api/v1/generate \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "productivity tool for remote teams",
    "count": 10,
    "style": "modern"
  }'

The style parameter accepts values like modern, professional, creative, and playful. Generated names are cached for 24 hours, so repeated calls with the same description return instantly.

The response includes each generated name with a .comAvailable boolean indicating whether the .com domain is open:

{
  "success": true,
  "data": {
    "description": "productivity tool for remote teams",
    "names": [
      {
        "name": "FlowDesk",
        "tagline": "Where remote work flows",
        "comAvailable": true
      },
      {
        "name": "Teamshift",
        "tagline": "Shift how your team works",
        "comAvailable": false
      }
    ],
    "cached": false
  }
}

This is particularly useful for building naming tools: generate candidates, filter by .com availability, then run a full /check on the top picks.

Handle Monitoring via API

The monitoring API lets you watch taken usernames and get notified when they become available. This is useful for automating the "wait and grab" strategy when the handle you want is held by an inactive account.

Create a Watch

curl -X POST https://namesniper.pro/api/v1/watch \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"username": "acmebrand", "platforms": ["instagram", "twitter", "github"]}'

This creates one watch per platform. The API returns the created watches along with your current slot usage.

List Your Watches

curl https://namesniper.pro/api/v1/watch \
  -H "Authorization: Bearer ns_sk_your_key_here"

Webhook Notifications

For real-time alerts, register a webhook endpoint:

curl -X POST https://namesniper.pro/api/v1/webhooks \
  -H "Authorization: Bearer ns_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/namesniper",
    "events": ["handle_available", "handle_change"]
  }'

The response includes a signing secret. All webhook payloads are signed with HMAC-SHA256 via the X-NameSniper-Signature header. Verify the signature server-side to confirm the payload is authentic:

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(body: string, secret: string, signature: string): boolean {
  const expected = 'sha256=' +
    createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Watch slots are plan-dependent: Pro gets 15 slots with hourly checks, Business gets 50 slots with checks every 15 minutes. For a deeper look at monitoring strategy, see our handle monitoring guide.

MCP Server for AI Agents

NameSniper exposes a remote MCP server using Streamable HTTP transport. If you're building an AI agent or using an MCP-compatible tool like Claude Code, you can connect NameSniper as a tool provider with a single config block.

Add this to your MCP configuration (e.g., mcp.json or your agent's tool config):

{
  "namesniper": {
    "type": "url",
    "url": "https://namesniper.pro/mcp",
    "headers": {
      "Authorization": "Bearer ns_sk_your_key_here"
    }
  }
}

Or via the npm package:

npx @namesniper/mcp

The npm package reads your key from the NAMESNIPER_API_KEY environment variable.

Once connected, the agent gets access to tools like namesniper_check, namesniper_generate, namesniper_check_domains, namesniper_check_social, namesniper_trademark, namesniper_alternatives, and namesniper_watch. The practical use case: an AI business advisor agent checks name availability as part of its workflow, without the user ever leaving the conversation.

For more on the protocol itself, see the MCP specification and the Model Context Protocol documentation.

Error Handling

All error responses follow the same shape:

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Try again in 12 seconds."
  }
}

The status codes you'll encounter:

• 400 -- Invalid request body. Missing name field, invalid characters, or malformed JSON.
• 401 -- Missing or malformed Authorization header.
• 403 -- Invalid API key, or your plan doesn't include API access.
• 429 -- Rate limit exceeded. Check the Retry-After header for when to retry.
• 500 -- Server error. Retry after a short delay.

For robust integrations, implement exponential backoff on 429 and 500 responses. Here's a minimal retry wrapper in TypeScript:

async function checkWithRetry(name: string, maxRetries = 3): Promise<any> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://namesniper.pro/api/v1/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.NAMESNIPER_API_KEY}`,
      },
      body: JSON.stringify({ name }),
    });

    if (response.ok) return response.json();

    if (response.status === 429 || response.status >= 500) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    throw new Error(`API error: ${response.status}`);
  }
  throw new Error('Max retries exceeded');
}

Rate Limits and Pricing

API access requires a Pro or Business plan:

For current pricing and plan details, see the pricing page. Rate limit headers are included in every API response so you can track your usage programmatically.

Integration Ideas

Here are concrete patterns for integrating the API:

Onboarding username check. During your app's signup flow, call /check/social with the user's desired username. Display availability inline so they can pick a name that works everywhere before committing. Show the confidence score so users know which results to trust.

Brand naming pipeline. Call /generate with a business description, filter results by .com availability, run /check on the top 5, then present a ranked shortlist with full availability data and brand scores. This is a complete naming workflow in 3 API calls.

Business registration platform. Before a user files their LLC, run /trademark to check for USPTO conflicts. Surface the risk level and any matching trademarks so the user can make an informed decision before spending money on registration.

Slack or Discord bot. Parse messages like /checkname acmebrand, call the API, and format the results as an embedded message. A complete bot integration is under 100 lines of code.

CI/CD for brand assets. If you manage brand names in a config file, add a CI step that calls /check on every name and fails the build if a critical handle has been claimed since the last check.

Related Resources

• API Documentation -- Full endpoint reference, request/response schemas, and authentication details
• Pricing Plans -- Compare Pro and Business API access tiers
• Username Availability Checker -- The web UI for manual checks
• Handle Monitoring Guide -- Strategy and setup for watching taken handles
• How to Check Username Availability -- Platform-by-platform reference for manual checking