Documentation

Overview

NumberHub is a carrier-grade phone number management platform built for agencies and developers. It provides everything you need to programmatically provision, manage, and message on local and toll-free numbers — all through a single REST API and a clean dashboard UI.

Key platform capabilities include:

Quick Start

You can be up and running in under five minutes. Follow these three steps:

Authentication

All API requests must be authenticated using your API key. Include it in the X-Hub-Api-Key header of every request:

X-Hub-Api-Key: nh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys start with the nh_ prefix followed by 48 hex characters and are generated per sub-account. To create or revoke a key, go to Dashboard → Settings → API Keys.

Base URL

All requests must be directed to:

https://api.numberhub.ai/api/integration

Core Concepts

Numbers (DIDs)

A DID (Direct Inward Dialing number) is the fundamental resource on the platform. NumberHub supports two categories:

• Local numbers — standard 10-digit numbers tied to a specific geographic area code. Ideal for local presence campaigns and agency sub-accounts.
• Toll-free numbers — 800/833/844/855/866/877/888 prefixed numbers with no per-call charge to the caller. Common for customer-facing support lines.

Every number passes through a defined lifecycle:

1. Provisioned — number has been purchased and is associated with your account.
2. Assigned — number has been assigned to a sub-account and is ready for messaging.
3. Active — number is live, sending and receiving SMS.
4. Released — number has been removed from your account and returned to the available pool.

Sub-Accounts

NumberHub is built for multi-tenant use. Each sub-account gets an isolated number pool, usage logs, and message history. This maps directly to LeadConnector sub-accounts or your own customer hierarchy. Admins can create, suspend, or delete sub-accounts from the dashboard.

Credits

The platform runs on a prepaid credit model. Purchasing a number deducts its setup cost from your credit balance, and monthly renewals are automatically deducted on each number's anniversary date. Outbound SMS usage also draws from your balance. You can top up credits at any time from the Billing section of the dashboard.

SMS Messaging

NumberHub supports both inbound and outbound SMS on all provisioned numbers:

• Inbound — messages sent to your numbers are captured and delivered to a configured webhook URL, forwarded to a LeadConnector conversation, or stored for API retrieval.
• Outbound — send messages programmatically via the /send endpoint. Delivery receipts are emitted as webhook events.

Note: Local phone numbers used for high-volume SMS must be registered under the A2P 10DLC program. Toll-free numbers require toll-free verification. NumberHub provides guidance on the registration process — see our compliance documentation or contact support for assistance.

Webhooks

Webhooks let you react to platform events in real time. Configure a webhook URL per number or at the account level. NumberHub will POST a JSON payload to your endpoint whenever a subscribed event occurs.

Supported events:

• message.inbound — an SMS was received on one of your numbers
• message.outbound.delivered — an outbound SMS was confirmed delivered
• number.provisioned — a new number was purchased on your account
• number.released — a number was released from your account

Webhook Event Reference

Each webhook POST is a JSON object with an event field identifying the event type plus event-specific fields.

message.inbound

{
  "event": "message.inbound",
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Hello!",
  "numberId": "num_xxxxxxxxxxxxxxxx",
  "timestamp": "2026-06-03T12:00:00.000Z"
}

message.outbound.delivered

{
  "event": "message.outbound.delivered",
  "messageId": "msg_xxxxxxxxxxxxxxxx",
  "to": "+15559876543",
  "status": "delivered",
  "timestamp": "2026-06-03T12:00:05.000Z"
}

number.provisioned

{
  "event": "number.provisioned",
  "numberId": "num_xxxxxxxxxxxxxxxx",
  "phoneNumber": "+15551234567",
  "subAccountId": "sub_xxxxxxxxxxxxxxxx",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

number.released

{
  "event": "number.released",
  "numberId": "num_xxxxxxxxxxxxxxxx",
  "phoneNumber": "+15551234567",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Error Codes

The NumberHub API uses standard HTTP status codes. All error responses include a JSON body with a message field describing the issue.

SDK & Tools

The NumberHub REST API works with any HTTP client — no proprietary SDK required. Below is a Node.js example using the native fetch API to send an outbound SMS:

const res = await fetch('https://api.numberhub.ai/api/integration/send', {
  method: 'POST',
  headers: {
    'X-Hub-Api-Key': process.env.NUMBERHUB_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: '+15551234567',
    to: '+15559876543',
    body: 'Hello from NumberHub!',
  }),
});
const { messageId } = await res.json();
console.log(messageId);

You can use the same pattern in any language or runtime. The API returns consistent JSON envelopes: successful responses include a data object; errors include a message string and an optional code for programmatic handling.

For detailed endpoint schemas and request/response examples, see the full API Reference.

Support

Enterprise plan customers receive priority 24/7 support. Before submitting a ticket, we recommend:

• Checking the API Reference for complete endpoint schemas and up-to-date request/response examples.
• Reviewing the Integration Guides for step-by-step tutorials on connecting LeadConnector, configuring webhooks, and managing sub-accounts.
• Inspecting your webhook delivery logs in the dashboard — failed deliveries include the response status and body returned by your endpoint.

If you still need help, open a support ticket from the dashboard or email our team directly. Enterprise customers receive a dedicated Slack channel and a named support engineer.