Skip to main content
The phone primitive gives your agents a real US phone number that can send and receive SMS. Numbers are provisioned through Surge and automatically registered with the carriers (10DLC) so messages actually deliver. Inbound SMS works the moment a number is provisioned. Outbound SMS is gated by carrier approval of the messaging campaign — this happens automatically (typically 1-2 business days) and unlocks sending with no further action.

​
CLI First

# Provision a US number + register the carrier campaign
naive phone provision --area-code 415 --label "Support"

# Watch the carrier-registration pipeline
naive phone status

# Once the campaign is approved, send SMS
naive phone send --from <phone-id> --to +14155551234 --body "Hello from my agent"

# Read what people text back
naive phone messages <phone-id>

​
Prerequisites

Provisioning a number requires a completed LLC formation and the company’s EIN — numbers are carrier-registered against your business entity, and the EIN is required for the carrier (10DLC) brand registration. The full chain is:
1

Verify identity (KYC)

naive verification start — verify the company’s members.
2

Form the company

naive formation submit — form the LLC (Surge registers the number against this business).
3

Provision the number

naive phone provision --ein 12-3456789 — buys the number and submits the carrier campaign.
The EIN is required the first time you provision (it registers the carrier brand). Provide it as 9 digits, with or without the hyphen (e.g. 12-3456789).

​
How SMS gating works

CapabilityWhen it works
VoiceOut of scope for this primitive
Inbound SMSImmediately on provisioning — no carrier gate
Outbound SMSAfter the 10DLC campaign is approved (auto, ~1-2 business days)
Attempting naive phone send before the campaign is approved returns compliance_pending — no message is sent and no credit is charged. The campaign auto-activates via a Surge webhook; check progress with naive phone status.

​
Provisioning a number

curl -X POST https://api.usenaive.ai/v1/phone/provision \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ein": "12-3456789", "area_code": "415", "label": "Support" }'
Response (202): 
{
  "phone": {
    "id": "phone-uuid",
    "e164": "+14155551234",
    "type": "local",
    "capabilities": { "voice": false, "sms_inbound": true, "sms_outbound": false, "mms": false },
    "status": "active"
  },
  "campaign": { "id": "campaign-uuid", "status": "created", "eta": "1-2 business days" },
  "credits_used": 50,
  "credits_remaining": 950
}

​
Sending SMS

naive phone send --from <phone-id> --to +14155551234 --body "Your order shipped!"

curl -X POST https://api.usenaive.ai/v1/phone/<phone-id>/sms \
  -H "Authorization: Bearer nv_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155551234", "body": "Your order shipped!" }'

​
Receiving SMS

Inbound texts are captured automatically (Surge message.received webhook) and stored against the receiving number. List and read them: 
naive phone messages <phone-id>          # newest first, cursor-paginated
naive phone read <message-id>            # full body + any media URLs
You can also subscribe to the sms.received webhook event to react in real time.

​
Agent assignment

Like cards and email, a phone number is a company resource that agents connect to with permissions (send_sms, receive_sms): 
naive phone assign <phone-id> --agent-id <agent-uuid>
naive phone assignments <phone-id>
naive phone unassign <phone-id> <agent-uuid>
An agent without send_sms on a number is refused with forbidden when it tries to send.

​
Campaign statuses

StatusMeaning
createdCampaign submitted, not yet in review
in_reviewUnder carrier review
activeApproved — outbound SMS unlocked
rejectedCarrier rejected the campaign (contact support)

​
Releasing a number

Release a number back to the provider when you no longer need it — this is permanent and stops further rental billing: 
naive phone release <phone-id>
JavaScript
await naive.phone.release(phoneId);

​
Pricing

ActionCredits
Provision your first number (one-time carrier registration + first month)~44
Provision an additional number (first month)~4
Monthly number rental (recurring, per number)~4
Outbound SMS (per 160-char segment)~0.04
Inbound SMSFree
Approval gating: provisioning a number is approval-gated by default (it spends credits and registers a carrier campaign) and can be toggled per Account Kit. Sending SMS is not approval-gated — it’s a routine action like sending email.

​
Error handling

ErrorCauseRecovery
invalid_input (no formation)No completed LLC formation for this userRun naive formation submit first
invalid_input (EIN required)No EIN provided on the first provisionPass --ein <ein> (9 digits)
compliance_pendingOutbound SMS attempted before campaign approvalWait for approval (auto) — retry after naive phone status shows active
forbiddenAgent lacks send_sms on the numberAssign the agent with naive phone assign
feature_not_configuredPhone provider not enabled on this environmentContact support / set SURGE_ENABLED
resource_not_foundPhone/message id doesn’t exist or belongs to another userUse naive phone list for valid ids