> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing Phone Numbers

> Use your existing Twilio or Telnyx numbers with Truedy agents

# 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

<Tabs>
  <Tab title="Keep your existing number">
    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.
  </Tab>

  <Tab title="Regional or regulatory requirements">
    Some countries require you to own numbers directly at the carrier level (STIR/SHAKEN attestation, local DID ownership requirements, etc.). Maintaining your Twilio or Telnyx relationship satisfies those requirements while Truedy handles the AI layer.
  </Tab>

  <Tab title="Carrier preference or pricing">
    You may have negotiated per-minute rates with Twilio or Telnyx that are lower than Truedy-managed rates for high-volume markets, or you may use numbers in regions where Truedy's carrier inventory is limited.
  </Tab>
</Tabs>

## Supported providers

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

<Note>
  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.
</Note>

## 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.

<Warning>
  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.
</Warning>

## General import flow

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Register the number in Truedy">
    Call `POST /telephony/numbers/import` with the phone number and provider details. Truedy verifies connectivity and adds the number to your account.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Twilio — step-by-step

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

1. Log in to [console.twilio.com](https://console.twilio.com).

2. Navigate to **Phone Numbers → Manage → Active Numbers**.

3. Click the number you want to import.

4. 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
   ```

5. Set the HTTP method to **POST**.

6. Save the configuration.

### Step 2: Copy your Twilio credentials into Truedy

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

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

### Step 3: Import the number via the API

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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']})")
  ```
</CodeGroup>

**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

1. Log in to [portal.telnyx.com](https://portal.telnyx.com).

2. Navigate to **Voice → SIP Connections** (or **Connections** in newer portal layouts).

3. Create a new **Credential-based** SIP connection.

4. In the **Inbound** settings, set the **SIP Registration URI** or **FQDN** to Truedy's SIP endpoint:

   ```
   sip.truedy.ai
   ```

5. Under **Outbound Voice Profile**, create or select a profile that allows outbound dialing through your Telnyx account.

6. Assign your Telnyx phone number to this SIP connection.

7. Save the connection.

### Step 2: Copy your Telnyx API key into Truedy

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

### Step 3: Import the number via the API

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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']})")
  ```
</CodeGroup>

**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:**

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

## 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:**

```bash cURL theme={null}
curl -X DELETE https://api.truedy.ai/api/public/v1/telephony/numbers/NUMBER_UUID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  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.
</Warning>

## 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](/guides/telephony-overview)
* Purchase a Truedy-managed number instead: [Buying a Phone Number](/guides/buying-phone-numbers)
* Use your imported number in a campaign: [Creating Your First Campaign](/guides/creating-your-first-campaign)