Importing Phone Numbers

Truedy lets you use phone numbers you already own in Twilio or Telnyx — without migrating them or giving up your carrier relationship. This is called BYOC (Bring Your Own Carrier). Once imported, the number behaves like any other Truedy number: you assign it to an agent, use it for outbound campaigns, and receive inbound calls through your agent automatically.

Why import instead of buying through Truedy

Keep your existing number
Regional or regulatory requirements
Carrier preference or pricing

Your customers, marketing materials, and internal systems may already reference a specific phone number. Importing lets you attach that number to a Truedy agent without changing the number your customers dial or see.

Supported providers

Provider	Supported	Notes
Twilio	Yes	Configure via Voice URL webhook
Telnyx	Yes	Configure via SIP connection

Other SIP-compatible providers may work but are not officially tested or supported. If you are using a provider other than Twilio or Telnyx, contact Truedy support before attempting an import.

Billing with imported numbers

With BYOC, billing is split:

What	Who charges you
Per-minute call costs (PSTN termination/origination)	Your provider (Twilio or Telnyx) — directly on their invoice
AI usage (voice model, transcription, inference)	Truedy — on your Truedy subscription invoice
Truedy platform fee for the imported number	Truedy — a reduced monthly fee vs. a Truedy-managed number

You will never be double-charged for call minutes. Truedy does not add a per-minute surcharge on calls that flow through BYOC numbers.

Importing a number that is currently live on another voice application (IVR, call center, SIP trunk, etc.) will immediately reroute all incoming calls to Truedy and break the existing application. Coordinate the cutover carefully, and if possible import during a low-traffic window.

General import flow

Configure your provider to forward to Truedy

Set up your Twilio or Telnyx number to send voice traffic to Truedy’s endpoint. The exact steps differ per provider — see the provider-specific sections below.

Add provider credentials to Truedy

In the Truedy dashboard, go to Settings → Integrations and add your provider credentials (Account SID + Auth Token for Twilio, or API key for Telnyx). Truedy uses these to validate inbound requests and place outbound calls through your provider account.

Call POST /telephony/numbers/import with the phone number and provider details. Truedy verifies connectivity and adds the number to your account.

Assign to an agent

Assign the imported number to an agent via the dashboard or PATCH /telephony/numbers/{id}. The number is now ready for inbound and outbound calls.

Twilio — step-by-step

Step 1: Set the Voice URL on your Twilio number

Log in to console.twilio.com.
Navigate to Phone Numbers → Manage → Active Numbers.
Click the number you want to import.
Under Voice & Fax → A Call Comes In, set the handler to Webhook and enter Truedy’s inbound webhook URL:
https://api.truedy.ai/telephony/inbound/twilio
Set the HTTP method to POST.
Save the configuration.

Step 2: Copy your Twilio credentials into Truedy

In the Twilio Console, find your Account SID and Auth Token on the dashboard home page.
In Truedy, go to Settings → Integrations → Twilio.
Paste your Account SID and Auth Token and click Save.

Truedy uses your Twilio Auth Token to verify the X-Twilio-Signature header on every inbound request, ensuring only genuine Twilio traffic is accepted.

Step 3: Import the number via the API

curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "provider": "twilio",
    "provider_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }'

import requests

response = requests.post(
    "https://api.truedy.ai/api/public/v1/telephony/numbers/import",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+14155550100",
        "provider": "twilio",
        "provider_account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
)

number = response.json()["data"]
print(f"Imported: {number['phone_number']} (id: {number['id']})")

Request body fields:

Field	Required	Description
`phone_number`	Yes	E.164 format (e.g. `+14155550100`)
`provider`	Yes	`twilio`
`provider_account_sid`	Yes	Your Twilio Account SID

Telnyx — step-by-step

Step 1: Create a SIP connection in Telnyx pointing to Truedy

Log in to portal.telnyx.com.
Navigate to Voice → SIP Connections (or Connections in newer portal layouts).
Create a new Credential-based SIP connection.
In the Inbound settings, set the SIP Registration URI or FQDN to Truedy’s SIP endpoint:
sip.truedy.ai
Under Outbound Voice Profile, create or select a profile that allows outbound dialing through your Telnyx account.
Assign your Telnyx phone number to this SIP connection.
Save the connection.

Step 2: Copy your Telnyx API key into Truedy

In the Telnyx portal, navigate to Account Settings → API Keys.
Copy your V2 API key.
In Truedy, go to Settings → Integrations → Telnyx.
Paste the API key and click Save.

Step 3: Import the number via the API

curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550200",
    "provider": "telnyx",
    "provider_connection_id": "YOUR_TELNYX_CONNECTION_ID"
  }'

import requests

response = requests.post(
    "https://api.truedy.ai/api/public/v1/telephony/numbers/import",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+14155550200",
        "provider": "telnyx",
        "provider_connection_id": "YOUR_TELNYX_CONNECTION_ID"
    }
)

number = response.json()["data"]
print(f"Imported: {number['phone_number']} (id: {number['id']})")

Request body fields:

Field	Required	Description
`phone_number`	Yes	E.164 format (e.g. `+14155550200`)
`provider`	Yes	`telnyx`
`provider_connection_id`	Yes	The ID of the SIP connection you created in Telnyx

Assigning the imported number to an agent

After import, the number exists in Truedy but is unassigned. Assign it exactly as you would a Truedy-managed number. Dashboard: Settings → Phone Numbers → click the number → select agent from Assigned Agent dropdown → Save. API:

curl -X PATCH https://api.truedy.ai/api/public/v1/telephony/numbers/NUMBER_UUID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_UUID"}'

import requests

response = requests.patch(
    f"https://api.truedy.ai/api/public/v1/telephony/numbers/{number_id}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"agent_id": "AGENT_UUID"}
)
print(response.json()["data"]["agent_id"])

Removing an imported number

Removing an imported number from Truedy deregisters it from the platform but does not delete it from your Twilio or Telnyx account. You remain the owner of the number at the carrier level. API:

cURL

curl -X DELETE https://api.truedy.ai/api/public/v1/telephony/numbers/NUMBER_UUID \
  -H "Authorization: Bearer YOUR_API_KEY"

After removal, you must update the Voice URL or SIP connection on your provider side if you want the number to route calls somewhere else. Until you do, incoming calls to that number will receive no answer or an error from your provider.

Troubleshooting

Symptom	Likely cause	Resolution
Import API returns `provider_verification_failed`	Truedy cannot reach your provider with the credentials provided	Double-check Account SID / API key in Settings → Integrations
Inbound calls are not reaching the agent	Voice URL or SIP connection not saved correctly in your provider portal	Re-verify provider configuration in Step 1 for your provider
Outbound calls through the BYOC number fail	Outbound voice profile not configured in Telnyx, or Twilio account lacks outbound calling permission	Check your provider account for outbound permissions
`number_already_imported` error	The number is already registered to your account (or another Truedy account)	Check your existing numbers list; contact support if you believe it’s an error

Next steps

Understand the full telephony model: Telephony Overview
Purchase a Truedy-managed number instead: Buying a Phone Number
Use your imported number in a campaign: Creating Your First Campaign

Getting Started

How Truedy Works

Agents

Calls

Outbound Campaigns

Telephony

Tools

Knowledge

Embed & Web Calls

Webhooks

Platform

Importing Phone Numbers

Importing Phone Numbers

Why import instead of buying through Truedy

Supported providers

Billing with imported numbers

General import flow

Twilio — step-by-step

Step 1: Set the Voice URL on your Twilio number

Step 2: Copy your Twilio credentials into Truedy

Step 3: Import the number via the API

Telnyx — step-by-step

Step 1: Create a SIP connection in Telnyx pointing to Truedy

Step 2: Copy your Telnyx API key into Truedy

Step 3: Import the number via the API

Assigning the imported number to an agent

Removing an imported number

Troubleshooting

Next steps

​Importing Phone Numbers

​Why import instead of buying through Truedy

​Supported providers

​Billing with imported numbers

​General import flow

​Twilio — step-by-step

​Step 1: Set the Voice URL on your Twilio number

​Step 2: Copy your Twilio credentials into Truedy

​Step 3: Import the number via the API

​Telnyx — step-by-step

​Step 1: Create a SIP connection in Telnyx pointing to Truedy

​Step 2: Copy your Telnyx API key into Truedy

​Step 3: Import the number via the API

​Assigning the imported number to an agent

​Removing an imported number

​Troubleshooting

​Next steps

Importing Phone Numbers

Why import instead of buying through Truedy

Supported providers

Billing with imported numbers

General import flow

Twilio — step-by-step

Step 1: Set the Voice URL on your Twilio number

Step 2: Copy your Twilio credentials into Truedy

Step 3: Import the number via the API

Telnyx — step-by-step

Step 1: Create a SIP connection in Telnyx pointing to Truedy

Step 2: Copy your Telnyx API key into Truedy

Step 3: Import the number via the API

Assigning the imported number to an agent

Removing an imported number

Troubleshooting

Next steps