Skip to main content
GET
/
api
/
phone-numbers
Voice and Phone Numbers
curl --request GET \
  --url https://api.example.com/api/phone-numbers
These are dashboard-session endpoints for NearIQ business communication features. They use the signed-in app session, active business scoping, and plan limits. Provider webhooks are server-to-server endpoints and validate the provider signature.
Call recording and voicemail storage may require consent notices depending on the caller location. Keep customer-facing disclosure and retention settings aligned with your legal requirements.

​
Phone Numbers

GET /api/phone-numbers lists active business phone numbers. Add search=1 with country, type, areaCode, or contains to search available numbers. POST /api/phone-numbers provisions a number and configures SMS plus voice webhooks. DELETE /api/phone-numbers?id=<uuid> releases a number and soft-disables it in NearIQ. 
{
  "phoneNumber": "+15551234567",
  "type": "local",
  "friendlyName": "Austin front desk",
  "setPrimary": true
}

​
Call Forwarding

GET /api/call-forwarding lists forwarding rules for the active business. POST /api/call-forwarding creates a rule. PUT /api/call-forwarding updates a rule. DELETE /api/call-forwarding?id=<uuid> deletes a rule. 
{
  "phoneNumberId": "00000000-0000-4000-8000-000000000000",
  "forwardTo": "+15557654321",
  "label": "Manager",
  "ringTimeoutSeconds": 25,
  "priority": 0,
  "enabled": true,
  "schedule": {
    "days": ["mon", "tue", "wed", "thu", "fri"],
    "startHour": 9,
    "endHour": 17
  }
}

​
Call Logs

GET /api/call-logs returns recent calls for the active business. Optional filters: direction, status, from, to, and limit. Rows include recordingPlaybackUrl when an authenticated recording proxy is available.

​
Voicemails

GET /api/voicemails returns voicemail rows with transcription text when available and an authenticated recordingPlaybackUrl. PATCH /api/voicemails marks a voicemail read or unread. DELETE /api/voicemails?id=<uuid> deletes a voicemail row. 
{
  "id": "00000000-0000-4000-8000-000000000000",
  "isRead": true
}

​
Voice Webhooks

POST /api/voice/incoming receives inbound calls, logs the call, dials active forwarding rules, and falls back to voicemail recording when no forwarding rule is available. POST /api/voice/status receives call status callbacks and updates call_logs, including voice minute usage for completed calls. POST /api/voice/recording receives recording callbacks and stores call recording or voicemail metadata. GET /api/voice/recording?callLogId=<uuid> or GET /api/voice/recording?voicemailId=<uuid> proxies recording playback for authenticated users without exposing provider recording URLs.

​
Errors

StatusMeaning
400Invalid phone number, rule, query, or request body
401Missing dashboard session
403Plan does not include the requested communication feature
404Business, phone number, call log, rule, or voicemail not found
502Phone provider request failed
503Phone provider is not configured