API Reference · Phone numbers

Add a phone number

Adds a number you already own — on Twilio, Plivo, Exotel or your own SIP trunk — and, optionally, the AI employee that answers it. For Twilio and Plivo numbers Daffy Voice also points the number's incoming calls at your AI employee for you.

POST/phone-numbers

https://calling.ubiqproject.com/api/v1/phone-numbers · Auth: API key (full access)

Request

Body

numberstringrequired

The phone number, in international format (+918046801234). For sip numbers Daffy Voice converts it to international format for you: a 10-digit or 0-prefixed number is read as Indian (+91).

providerstringrequired

One of twilio, plivo, exotel, sip.

namestring

A label for the number, such as “Collections line”.

locationstring

A note of its region or office.

agent_idstring (UUID)

The AI employee that answers calls to this number (from List AI employees). Omit to add the number without one.

account_idstring (UUID)

The telephony account or SIP trunk the number belongs to, as connected in the dashboard. Required. For sip it must be a SIP trunk; for Twilio, Plivo or Exotel it must be your own account of that provider, and for Twilio the number must be in that account.

Request

curl -X POST https://calling.ubiqproject.com/api/v1/phone-numbers \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+918046801234",
    "provider": "sip",
    "name": "Collections line",
    "location": "Bengaluru",
    "agent_id": "3f8c2a1e-6b4d-4c7a-9e21-5d0f7b8a9c34",
    "account_id": "c5e2b7a9-0d1f-4e36-b8c4-7a6f5e3d2c18"
  }'

Response

201 Created with the new number.

Response · 201

{
  "id": "a71d9e04-2c3b-4f58-8e6a-1b9c0d2e3f47",
  "number": "+918046801234",
  "provider": "sip",
  "name": "Collections line",
  "location": "Bengaluru",
  "agent_id": "3f8c2a1e-6b4d-4c7a-9e21-5d0f7b8a9c34",
  "agent_name": "Priya",
  "account_id": "c5e2b7a9-0d1f-4e36-b8c4-7a6f5e3d2c18",
  "account_label": "Tata SIP trunk",
  "webhook_configured": true,
  "webhook_detail": "Calls to this number now reach your AI employee"
}

What webhook_configured means depends on the provider:

sip — always true. Calls your carrier sends for this number now reach the AI employee.
twilio / plivo — true when Daffy Voice set the number's incoming-call URL in your provider account. When false, webhook_detail says why (for example "+14155550142 is not in this Twilio account"). The number is still added.
exotel — null. Set up incoming calls in your Exotel account.

Response fields

idstring (UUID)

The phone number's ID.

numberstring

The number as stored. SIP numbers are always stored in international format (+91…).

providerstring

twilio, plivo, exotel or sip.

namestring | null

Your label for the number.

locationstring | null

Your note of the number's region or office.

agent_idstring | null

The AI employee that answers calls to this number. null if none.

agent_namestring | null

That AI employee's name.

account_idstring | null

The telephony account or SIP trunk the number belongs to. null means Daffy Voice's own account.

account_labelstring | null

That account's name.

webhook_configuredboolean | null

Only set right after adding a number or changing its account: whether Daffy Voice pointed the provider's incoming calls at your AI employee. Always null in lists.

webhook_detailstring | null

A sentence explaining webhook_configured.

Errors

Responses

Already added409

"+918046801234 is already imported in this workspace." or "… is already registered with another workspace." A number can belong to only one company.

No account422

"Connect your Twilio account first…" (or Plivo / Exotel) when account_id is missing, or "… isn't in the connected Twilio account…" when the number belongs to a different account.

SIP without a trunk422

"Choose the SIP trunk this number belongs to (account_id)", or "A SIP number must be attached to a SIP trunk account" when account_id isn't a SIP trunk.

Bad ID422

"Invalid agent_id UUID" or "Invalid account_id UUID".

Not found404

"Agent not found" or "Telephony account not found" in your company.

Connect accounts in the dashboard

SIP trunks and your own Twilio or Plivo accounts are connected in the dashboard (see SIP trunks). The API adds numbers to them; it can't create them.