API Reference

Authentication

All API requests must include your API key in the X-Hub-Api-Key header. You can generate API keys in your Dashboard under Settings → API Keys. Keep your keys secret — never expose them in client-side code or public repositories.

API keys follow the format nh_ followed by 48 hex characters (e.g. nh_a1b2c3d4e5f6...). The key identifies your account — no separate sub-account ID is needed.

X-Hub-Api-Key: nh_a1b2c3d4e5f6...

Base URL

All endpoints are relative to the following base URL. Every request and response uses JSON; set Content-Type: application/json on all write operations.

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

Rate Limits

The API enforces a limit of 100 requests per second per account. Exceeding this limit returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying. Implement exponential backoff in your client to handle transient throttling gracefully.

Response Format

Responses are simple, flat JSON objects — there is no wrapping envelope. Each endpoint returns the relevant fields directly. For example, GET /numbers returns { "numbers": [...] } and GET /balance returns { "balance": 42.50, "currency": "USD" }.

The only exception is POST /send, which always includes a success: true field alongside messageId and costUsd.

Error responses return the appropriate HTTP status code (e.g. 400, 404, 422) with a flat JSON body:

{
  "error": "Number not found."
}

Numbers

Manage your purchased phone numbers, search available inventory, purchase new numbers, and release numbers you no longer need.

curl -X GET "https://api.numberhub.ai/api/integration/numbers" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..."

{
  "numbers": [
    { "id": "clxxxxxxxxxxxxxxxx", "phoneNumber": "+15551234567" },
    { "id": "clyyyyyyyyyyyyyyyy", "phoneNumber": "+15559876543" }
  ]
}

curl -X GET "https://api.numberhub.ai/api/integration/numbers/search?areaCode=415" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..."

{
  "numbers": [
    { "phoneNumber": "+14151234567", "monthlyFeeCents": 200 },
    { "phoneNumber": "+14159876543", "monthlyFeeCents": 200 }
  ]
}

curl -X POST "https://api.numberhub.ai/api/integration/numbers/purchase" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "forwardToNumber": "+15559876543"
  }'

{
  "phoneNumber": "+15551234567",
  "monthlyFeeCents": 200
}

curl -X DELETE "https://api.numberhub.ai/api/integration/numbers/%2B15551234567" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..."

{ "ok": true }

Forwarding

Configure inbound call forwarding for a specific phone number. When a call is received on the number, it will be forwarded to the destination number you specify.

curl -X PUT "https://api.numberhub.ai/api/integration/numbers/%2B15551234567/forwarding" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{ "forwardToNumber": "+15559876543" }'

{ "ok": true, "profileId": 12345, "forwardToNumber": "+15559876543" }

SMS

Send outbound SMS messages from any phone number on your account.

curl -X POST "https://api.numberhub.ai/api/integration/send" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello from NumberHub!"
  }'

{
  "success": true,
  "messageId": "msg_xxxxxxxxxxxxxxxx",
  "costUsd": 0.0075
}

Account Balance

Retrieve the current credit balance for your account. The balance is decremented when you purchase phone numbers or send messages.

curl -X GET "https://api.numberhub.ai/api/integration/balance" \
  -H "X-Hub-Api-Key: nh_a1b2c3d4e5f6..."

{
  "balance": 42.50,
  "currency": "USD"
}