Skip to content

team-telnyx/ai / providers/claude/plugins/telnyx-platform/skills/telnyx-twilio-migration

telnyx-twilio-migration

Unverified

Migrate from Twilio to Telnyx. Orchestrates a complete 6-phase migration: discovery, planning, setup, code migration, validation, and cleanup. Covers voice (TwiML to TeXML, Call Control API), messaging, WebRTC, SIP trunking, verify, fax, video, IoT, number lookup, and porting. Includes automated scanners, validation scripts, and integration tests.

FileKindSize
SKILL.mdskill md43.3 KB
references/account-setup-guide.mdmarkdown17.8 KB
references/error-code-mapping.mdmarkdown11.0 KB
references/fax-migration.mdmarkdown14.7 KB
references/iot-migration.mdmarkdown17.9 KB
references/lookup-migration.mdmarkdown14.3 KB
references/messaging-migration.mdmarkdown36.5 KB
references/mobile-sdk-migration.mdmarkdown38.6 KB
references/number-porting.mdmarkdown17.0 KB
references/numbers-migration.mdmarkdown21.1 KB
references/product-mapping.mdmarkdown6.7 KB
references/sdk-api-details/10dlc.mdmarkdown9.8 KB
references/sdk-api-details/ai-assistants.mdmarkdown5.8 KB
references/sdk-api-details/messaging.mdmarkdown16.1 KB
references/sdk-api-details/numbers.mdmarkdown10.1 KB
references/sdk-api-details/voice.mdmarkdown9.6 KB
references/sip-trunking-migration.mdmarkdown18.1 KB
references/texml-verbs.mdmarkdown43.7 KB
references/unsupported-products.mdmarkdown3.5 KB
references/verify-migration.mdmarkdown18.4 KB
references/video-migration.mdmarkdown20.6 KB
references/voice-migration.mdmarkdown37.2 KB
references/webhook-migration.mdmarkdown20.3 KB
references/webrtc-migration.mdmarkdown50.0 KB
scripts/lint-telnyx-correctness.shexecutablescript31.4 KB
scripts/migration-state.shexecutablescript7.3 KB
scripts/post-test-diagnostic.shexecutablescript18.9 KB
scripts/preflight-check.shexecutablescript13.4 KB
scripts/run-discovery.shexecutablescript7.7 KB
scripts/run-validation.shexecutablescript13.1 KB
scripts/scan-twilio-deep.pyexecutablescript64.8 KB
scripts/scan-twilio-usage.shexecutablescript29.1 KB
scripts/test-migration/smoke-test.shexecutablescript10.0 KB
scripts/test-migration/test-fax.shexecutablescript8.7 KB
scripts/test-migration/test-lookup.shexecutablescript5.5 KB
scripts/test-migration/test-messaging.shexecutablescript18.8 KB
scripts/test-migration/test-sip.shexecutablescript29.6 KB
scripts/test-migration/test-verify.shexecutablescript13.6 KB
scripts/test-migration/test-voice.shexecutablescript22.4 KB
scripts/test-migration/test-webhooks-local.pyexecutablescript9.7 KB
scripts/test-migration/test-webrtc.shexecutablescript24.0 KB
scripts/test-migration/webhook-receiver.pyexecutablescript11.8 KB
scripts/validate-migration.shexecutablescript31.1 KB
scripts/validate-texml.shexecutablescript61.4 KB
sdk-reference/curl/10dlc.mdmarkdown25.8 KB
sdk-reference/curl/account-access.mdmarkdown15.6 KB
sdk-reference/curl/account-management.mdmarkdown9.5 KB
sdk-reference/curl/account-notifications.mdmarkdown11.0 KB
sdk-reference/curl/account-reports.mdmarkdown45.5 KB
sdk-reference/curl/account.mdmarkdown8.1 KB
sdk-reference/curl/ai-assistants.mdmarkdown34.3 KB
sdk-reference/curl/ai-inference.mdmarkdown34.5 KB
sdk-reference/curl/fax.mdmarkdown19.8 KB
sdk-reference/curl/iot.mdmarkdown49.4 KB
sdk-reference/curl/messaging-hosted.mdmarkdown23.3 KB
sdk-reference/curl/messaging-profiles.mdmarkdown14.2 KB
sdk-reference/curl/messaging.mdmarkdown29.1 KB
sdk-reference/curl/missions.mdmarkdown23.5 KB
sdk-reference/curl/networking.mdmarkdown39.8 KB
sdk-reference/curl/numbers-compliance.mdmarkdown30.2 KB
sdk-reference/curl/numbers-config.mdmarkdown29.7 KB
sdk-reference/curl/numbers-services.mdmarkdown12.6 KB
sdk-reference/curl/numbers.mdmarkdown24.0 KB
sdk-reference/curl/oauth.mdmarkdown15.6 KB
sdk-reference/curl/porting-in.mdmarkdown35.1 KB
sdk-reference/curl/porting-out.mdmarkdown9.8 KB
sdk-reference/curl/sip-integrations.mdmarkdown27.5 KB
sdk-reference/curl/sip.mdmarkdown47.6 KB
sdk-reference/curl/storage.mdmarkdown4.2 KB
sdk-reference/curl/texml.mdmarkdown31.4 KB
sdk-reference/curl/verify.mdmarkdown13.2 KB
sdk-reference/curl/video.mdmarkdown17.2 KB
sdk-reference/curl/voice-advanced.mdmarkdown32.8 KB
sdk-reference/curl/voice-conferencing.mdmarkdown41.6 KB
sdk-reference/curl/voice-gather.mdmarkdown14.7 KB
sdk-reference/curl/voice-media.mdmarkdown17.8 KB
sdk-reference/curl/voice-streaming.mdmarkdown13.3 KB
sdk-reference/curl/voice.mdmarkdown37.6 KB
sdk-reference/curl/webrtc.mdmarkdown6.5 KB
sdk-reference/go/10dlc.mdmarkdown29.0 KB
sdk-reference/go/account-access.mdmarkdown17.0 KB
sdk-reference/go/account-management.mdmarkdown9.9 KB
sdk-reference/go/account-notifications.mdmarkdown12.4 KB
sdk-reference/go/account-reports.mdmarkdown31.5 KB
sdk-reference/go/account.mdmarkdown9.1 KB
sdk-reference/go/ai-assistants.mdmarkdown37.7 KB
sdk-reference/go/ai-inference.mdmarkdown27.1 KB
sdk-reference/go/fax.mdmarkdown20.2 KB
sdk-reference/go/iot.mdmarkdown51.3 KB
sdk-reference/go/messaging-hosted.mdmarkdown24.5 KB
sdk-reference/go/messaging-profiles.mdmarkdown15.2 KB
sdk-reference/go/messaging.mdmarkdown30.1 KB
sdk-reference/go/missions.mdmarkdown26.9 KB
sdk-reference/go/networking.mdmarkdown42.5 KB
sdk-reference/go/numbers-compliance.mdmarkdown28.2 KB
sdk-reference/go/numbers-config.mdmarkdown29.5 KB
sdk-reference/go/numbers-services.mdmarkdown14.1 KB
sdk-reference/go/numbers.mdmarkdown26.7 KB
sdk-reference/go/oauth.mdmarkdown11.7 KB
sdk-reference/go/porting-in.mdmarkdown41.1 KB
sdk-reference/go/porting-out.mdmarkdown10.9 KB
sdk-reference/go/sip-integrations.mdmarkdown32.3 KB
sdk-reference/go/sip.mdmarkdown49.1 KB
sdk-reference/go/storage.mdmarkdown4.8 KB
sdk-reference/go/texml.mdmarkdown35.7 KB
sdk-reference/go/verify.mdmarkdown14.4 KB
sdk-reference/go/video.mdmarkdown18.6 KB
sdk-reference/go/voice-advanced.mdmarkdown33.2 KB
sdk-reference/go/voice-conferencing.mdmarkdown42.3 KB
sdk-reference/go/voice-gather.mdmarkdown14.5 KB
sdk-reference/go/voice-media.mdmarkdown18.1 KB
sdk-reference/go/voice-streaming.mdmarkdown13.5 KB
sdk-reference/go/voice.mdmarkdown39.2 KB
sdk-reference/go/webrtc.mdmarkdown7.5 KB
sdk-reference/java/10dlc.mdmarkdown31.3 KB
sdk-reference/java/account-access.mdmarkdown18.5 KB
sdk-reference/java/account-management.mdmarkdown11.1 KB
sdk-reference/java/account-notifications.mdmarkdown14.3 KB
sdk-reference/java/account-reports.mdmarkdown36.5 KB
sdk-reference/java/account.mdmarkdown10.3 KB
sdk-reference/java/ai-assistants.mdmarkdown39.2 KB
sdk-reference/java/ai-inference.mdmarkdown30.7 KB
sdk-reference/java/fax.mdmarkdown21.5 KB
sdk-reference/java/iot.mdmarkdown57.5 KB
sdk-reference/java/messaging-hosted.mdmarkdown28.4 KB
sdk-reference/java/messaging-profiles.mdmarkdown15.7 KB
sdk-reference/java/messaging.mdmarkdown32.2 KB
sdk-reference/java/missions.mdmarkdown31.6 KB
sdk-reference/java/networking.mdmarkdown47.1 KB
sdk-reference/java/numbers-compliance.mdmarkdown31.1 KB
sdk-reference/java/numbers-config.mdmarkdown32.2 KB
sdk-reference/java/numbers-services.mdmarkdown15.9 KB
sdk-reference/java/numbers.mdmarkdown28.4 KB
sdk-reference/java/oauth.mdmarkdown13.0 KB
sdk-reference/java/porting-in.mdmarkdown46.2 KB
sdk-reference/java/porting-out.mdmarkdown11.9 KB
sdk-reference/java/sip-integrations.mdmarkdown38.1 KB
sdk-reference/java/sip.mdmarkdown51.9 KB
sdk-reference/java/storage.mdmarkdown5.7 KB
sdk-reference/java/texml.mdmarkdown41.3 KB
sdk-reference/java/verify.mdmarkdown16.0 KB
sdk-reference/java/video.mdmarkdown20.3 KB
sdk-reference/java/voice-advanced.mdmarkdown35.0 KB
sdk-reference/java/voice-conferencing.mdmarkdown46.0 KB
sdk-reference/java/voice-gather.mdmarkdown16.1 KB
sdk-reference/java/voice-media.mdmarkdown19.5 KB
sdk-reference/java/voice-streaming.mdmarkdown14.7 KB
sdk-reference/java/voice.mdmarkdown40.8 KB
sdk-reference/java/webrtc.mdmarkdown8.5 KB
sdk-reference/javascript/10dlc.mdmarkdown28.5 KB
sdk-reference/javascript/account-access.mdmarkdown15.9 KB
sdk-reference/javascript/account-management.mdmarkdown9.6 KB
sdk-reference/javascript/account-notifications.mdmarkdown11.7 KB
sdk-reference/javascript/account-reports.mdmarkdown29.3 KB
sdk-reference/javascript/account.mdmarkdown8.7 KB
sdk-reference/javascript/ai-assistants.mdmarkdown37.5 KB
sdk-reference/javascript/ai-inference.mdmarkdown24.4 KB
sdk-reference/javascript/fax.mdmarkdown19.9 KB
sdk-reference/javascript/iot.mdmarkdown47.4 KB
sdk-reference/javascript/messaging-hosted.mdmarkdown22.4 KB
sdk-reference/javascript/messaging-profiles.mdmarkdown14.8 KB
sdk-reference/javascript/messaging.mdmarkdown29.7 KB
sdk-reference/javascript/missions.mdmarkdown23.8 KB
sdk-reference/javascript/networking.mdmarkdown39.3 KB
sdk-reference/javascript/numbers-compliance.mdmarkdown25.9 KB
sdk-reference/javascript/numbers-config.mdmarkdown28.3 KB
sdk-reference/javascript/numbers-services.mdmarkdown13.0 KB
sdk-reference/javascript/numbers.mdmarkdown26.1 KB
sdk-reference/javascript/oauth.mdmarkdown10.8 KB
sdk-reference/javascript/porting-in.mdmarkdown37.4 KB
sdk-reference/javascript/porting-out.mdmarkdown10.2 KB
sdk-reference/javascript/sip-integrations.mdmarkdown28.5 KB
sdk-reference/javascript/sip.mdmarkdown47.4 KB
sdk-reference/javascript/storage.mdmarkdown4.5 KB
sdk-reference/javascript/texml.mdmarkdown31.9 KB
sdk-reference/javascript/verify.mdmarkdown13.3 KB
sdk-reference/javascript/video.mdmarkdown17.2 KB
sdk-reference/javascript/voice-advanced.mdmarkdown32.6 KB
sdk-reference/javascript/voice-conferencing.mdmarkdown40.4 KB
sdk-reference/javascript/voice-gather.mdmarkdown14.3 KB
sdk-reference/javascript/voice-media.mdmarkdown17.8 KB
sdk-reference/javascript/voice-streaming.mdmarkdown13.4 KB
sdk-reference/javascript/voice.mdmarkdown39.4 KB
sdk-reference/javascript/webrtc.mdmarkdown7.2 KB
sdk-reference/python/10dlc.mdmarkdown28.5 KB
sdk-reference/python/account-access.mdmarkdown15.0 KB
sdk-reference/python/account-management.mdmarkdown9.1 KB
sdk-reference/python/account-notifications.mdmarkdown10.9 KB
sdk-reference/python/account-reports.mdmarkdown28.1 KB
sdk-reference/python/account.mdmarkdown8.1 KB
sdk-reference/python/ai-assistants.mdmarkdown37.3 KB
sdk-reference/python/ai-inference.mdmarkdown23.4 KB
sdk-reference/python/fax.mdmarkdown19.5 KB
sdk-reference/python/iot.mdmarkdown45.3 KB
sdk-reference/python/messaging-hosted.mdmarkdown21.7 KB
sdk-reference/python/messaging-profiles.mdmarkdown14.1 KB
sdk-reference/python/messaging.mdmarkdown29.4 KB
sdk-reference/python/missions.mdmarkdown23.2 KB
sdk-reference/python/networking.mdmarkdown37.1 KB
sdk-reference/python/numbers-compliance.mdmarkdown24.6 KB

references/lookup-migration.md

View on GitHub
# Number Lookup Migration: Twilio Lookup v2 to Telnyx Number Lookup

Migrate from Twilio Lookup v2 to the Telnyx Number Lookup API for carrier, line type, and caller name (CNAM) lookups.

## Table of Contents

- [Overview](#overview)
- [Key Differences](#key-differences)
- [Concept Mapping](#concept-mapping)
- [Step 1: Basic Number Lookup](#step-1-basic-number-lookup)
- [Step 2: Carrier Lookup](#step-2-carrier-lookup)
- [Step 3: Caller Name (CNAM) Lookup](#step-3-caller-name-cnam-lookup)
- [Response Field Mapping](#response-field-mapping)
- [API Endpoint Mapping](#api-endpoint-mapping)
- [Common Pitfalls](#common-pitfalls)

## Overview

Telnyx Number Lookup provides carrier identification, line type detection, caller name (CNAM), and portability information for phone numbers. It is a direct replacement for Twilio Lookup v2, which provides similar carrier and caller-name lookups.

The Telnyx Number Lookup API uses one endpoint. A plain `GET /v2/number_lookup/{phone_number}` with **no** query parameters returns these top-level keys:

`caller_name`, `carrier`, `country_code`, `fraud`, `national_format`, `nnid_override`, `phone_number`, `portability`, `record_type`, `valid_number`

The keys are always present, but **`carrier` and `caller_name` are `null` unless explicitly requested** via the `type` query parameter. `portability` **is** fully populated by default.

| Request | `carrier` | `caller_name` | `portability` |
|---|---|---|---|
| `GET /v2/number_lookup/{number}` | `null` | `null` | populated |
| `GET /v2/number_lookup/{number}?type=carrier` | populated | `null` | populated |
| `GET /v2/number_lookup/{number}?type=caller-name` | `null` | populated | populated |
| Carrier request followed by caller-name request | populated across the two responses | populated across the two responses | populated in each response |


## Key Differences

1. **Single endpoint model** — Telnyx uses one `GET` endpoint whose optional `type` parameter accepts one value (`carrier` or `caller-name`) per documented request. Use separate requests when both enrichments are needed. Twilio Lookup v2 uses a similar model with `Fields` parameter.
2. **Portability data included** — Telnyx returns detailed portability information (LRN, ported status, ported date, OCN, SPID) alongside carrier data. Twilio requires separate Porting API access.
3. **Authentication** — Twilio uses Basic Auth (SID:Token). Telnyx uses Bearer Token.
4. **Response structure** — Telnyx nests data under `carrier`, `caller_name`, and `portability` objects. `carrier` and `caller_name` are `null` unless requested via `?type=`; `portability` is always populated. Twilio Lookup v2 nests under `line_type_intelligence`, `caller_name`, etc.
5. **Pricing model** — Both charge per-lookup. Telnyx pricing varies by lookup type requested.

## Concept Mapping

| Twilio Lookup Concept | Telnyx Equivalent | Notes |
|---|---|---|
| Lookup v2 `Fields=line_type_intelligence` | `?type=carrier` query param | Carrier and line type info |
| Lookup v2 `Fields=caller_name` | `?type=caller-name` query param | CNAM data |
| `line_type_intelligence.type` | `portability.line_type` | Line type (mobile, landline, voip) |
| `line_type_intelligence.carrier_name` | `carrier.name` | Carrier name |
| `line_type_intelligence.mobile_country_code` | `carrier.mobile_country_code` | MCC |
| `line_type_intelligence.mobile_network_code` | `carrier.mobile_network_code` | MNC |
| `caller_name.caller_name` | `caller_name.caller_name` | CNAM value |
| `caller_name.caller_type` | N/A | Telnyx does not return caller type |
| Phone Number SID | N/A | Telnyx returns data directly, no SID |
| `valid` field | `valid_number` | Top-level, returned by default |

## Step 1: Basic Number Lookup

A basic lookup without type parameters returns phone number formatting, country information, validity, fraud, and the fully populated `portability` object. `carrier` and `caller_name` come back as `null` — request them with `?type=` (see Steps 2 and 3).

### curl

```bash
# Twilio Lookup v2
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/+15551234567" \
  -u "$TWILIO_SID:$TWILIO_AUTH_TOKEN"

# Telnyx
curl -X GET "https://api.telnyx.com/v2/number_lookup/+15551234567" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

### Python

```python
# Twilio
from twilio.rest import Client
client = Client(account_sid, auth_token)
result = client.lookups.v2.phone_numbers("+15551234567").fetch()
print(result.valid)

# Telnyx
from telnyx import Telnyx
client = Telnyx(api_key="YOUR_TELNYX_API_KEY")

result = client.number_lookup.retrieve(phone_number="+15551234567")
if result.data is None:
    raise RuntimeError("Number Lookup response did not include data")
print(result.data.country_code)
print(result.data.national_format)
print(result.data.phone_number)
```

### JavaScript

```javascript
// Twilio
const twilio = require('twilio');
const client = twilio(accountSid, authToken);
const result = await client.lookups.v2.phoneNumbers('+15551234567').fetch();
console.log(result.valid);

// Telnyx
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_TELNYX_API_KEY' });

const result = await client.numberLookup.retrieve('+15551234567');
console.log(result.data.country_code);
console.log(result.data.national_format);
console.log(result.data.phone_number);
```

## Step 2: Carrier Lookup

Carrier lookup returns the carrier name, type, MCC, MNC, and line type information.

### curl

```bash
# Twilio Lookup v2
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/+15551234567?Fields=line_type_intelligence" \
  -u "$TWILIO_SID:$TWILIO_AUTH_TOKEN"

# Telnyx
curl -X GET "https://api.telnyx.com/v2/number_lookup/+15551234567?type=carrier" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

### Python

```python
# Twilio
result = client.lookups.v2.phone_numbers("+15551234567").fetch(
    fields=["line_type_intelligence"]
)
print(result.line_type_intelligence["carrier_name"])
print(result.line_type_intelligence["type"])  # "mobile", "landline", "voip", etc.

# Telnyx
result = client.number_lookup.retrieve(phone_number="+15551234567", type="carrier")
if result.data is None or result.data.carrier is None:
    raise RuntimeError("Carrier lookup response did not include carrier data")
print(result.data.carrier.name)           # e.g., "AT&T"
print(result.data.carrier.type)           # e.g., "voip", "mobile"
print(result.data.portability.line_type)  # e.g., "mobile", "fixed line", "voip"
```

### JavaScript

```javascript
// Twilio
const result = await client.lookups.v2.phoneNumbers('+15551234567')
  .fetch({ fields: ['line_type_intelligence'] });
console.log(result.lineTypeIntelligence.carrier_name);
console.log(result.lineTypeIntelligence.type);

// Telnyx
const result = await client.numberLookup.retrieve('+15551234567', {
  type: 'carrier'
});
console.log(result.data.carrier.name);
console.log(result.data.carrier.type);
console.log(result.data.portability.line_type);
```

## Step 3: Caller Name (CNAM) Lookup

CNAM lookup returns the registered name associated with a phone number.

### curl

```bash
# Twilio Lookup v2
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/+15551234567?Fields=caller_name" \
  -u "$TWILIO_SID:$TWILIO_AUTH_TOKEN"

# Telnyx caller-name lookup (make a separate `type=carrier` request if needed)
curl -X GET "https://api.telnyx.com/v2/number_lookup/+15551234567?type=caller-name" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

### Python

```python
# Twilio
result = client.lookups.v2.phone_numbers("+15551234567").fetch(
    fields=["caller_name"]
)
print(result.caller_name["caller_name"])
print(result.caller_name["caller_type"])  # "CONSUMER" or "BUSINESS"

# Telnyx
result = client.number_lookup.retrieve(
    phone_number="+15551234567",
    type="caller-name"
)
if result.data is None or result.data.caller_name is None:
    raise RuntimeError("Caller-name lookup response did not include caller-name data")
print(result.data.caller_name.caller_name)  # e.g., "ACME Corp"
```

### JavaScript

```javascript
// Twilio
const result = await client.lookups.v2.phoneNumbers('+15551234567')
  .fetch({ fields: ['caller_name'] });
console.log(result.callerName.caller_name);
console.log(result.callerName.caller_type);

// Telnyx
const result = await client.numberLookup.retrieve('+15551234567', {
  type: 'caller-name'
});
console.log(result.data.caller_name.caller_name);
```

## Response Field Mapping

The official response schema defines these sub-fields:

- `carrier` (only when `?type=carrier`): `error_code`, `mobile_country_code`, `mobile_network_code`, `name`, `normalized_carrier`, `type`
- `caller_name` (only when `?type=caller-name`): `caller_name`, `error_code`
- `portability` (always): `altspid`, `altspid_carrier_name`, `altspid_carrier_type`, `city`, `line_type`, `lrn`, `ocn`, `ported_date`, `ported_status`, `spid`, `spid_carrier_name`, `spid_carrier_type`, `state`

### Top-Level Fields

| Twilio Lookup v2 Field | Telnyx Field | Notes |
|---|---|---|
| `phone_number` | `phone_number` | E.164 format |
| `valid` | `valid_number` | Validity indicator, returned by default |
| `country_code` | `country_code` | ISO 3166-1 alpha-2 |
| `national_format` | `national_format` | Locally formatted number |
| `url` | N/A | No self-link in Telnyx response |
| `calling_country_code` | N/A | Included in `country_code` |
| N/A | `record_type` | Response object type discriminator |
| N/A | `fraud` | Fraud risk indicator (Telnyx-only) |
| N/A | `nnid_override` | NNID override (Telnyx-only), returned by default |

### Carrier / Line Type Fields

`carrier` is `null` unless the request includes `?type=carrier`. `portability.line_type` is available without it.

| Twilio Field (`line_type_intelligence`) | Telnyx Field | Notes |
|---|---|---|
| `carrier_name` | `carrier.name` | Carrier name string |
| `type` | `portability.line_type` | `mobile`, `fixed line`, `voip`, etc. |
| `mobile_country_code` | `carrier.mobile_country_code` | MCC |
| `mobile_network_code` | `carrier.mobile_network_code` | MNC |
| `error_code` | `carrier.error_code` | Error indicator |
| N/A | `carrier.type` | Carrier type (e.g., `voip`, `mobile`) |
| N/A | `carrier.normalized_carrier` | Normalized carrier name |

### Caller Name Fields

`caller_name` is `null` unless the request includes `?type=caller-name`. The object has exactly two sub-fields.

| Twilio Field (`caller_name`) | Telnyx Field | Notes |
|---|---|---|
| `caller_name` | `caller_name.caller_name` | CNAM value |
| `caller_type` | N/A | Not returned by Telnyx — there is no `caller_name.caller_type` |
| `error_code` | `caller_name.error_code` | Error indicator |

### Portability Fields (Telnyx-only)

Telnyx returns additional portability data not available in Twilio Lookup. `portability` is populated on every lookup — no `type` parameter required. These 13 sub-fields are the complete set:

| Telnyx Field | Description |
|---|---|
| `portability.lrn` | Local Routing Number |
| `portability.ported_status` | `Y` (ported) or `N` (not ported) |
| `portability.ported_date` | Date the number was ported |
| `portability.ocn` | Operating Company Number |
| `portability.line_type` | Line type (`mobile`, `fixed line`, `voip`, etc.) |
| `portability.spid` | Service Provider ID |
| `portability.spid_carrier_name` | SPID carrier name |
| `portability.spid_carrier_type` | SPID carrier type |
| `portability.altspid` | Alternative SPID |
| `portability.altspid_carrier_name` | Alternative SPID carrier name |
| `portability.altspid_carrier_type` | Alternative SPID carrier type |
| `portability.city` | City associated with the number |
| `portability.state` | State associated with the number |

### Fraud Fields (Telnyx-only)

| Telnyx Field | Description |
|---|---|
| `fraud` | Fraud risk indicator for the number |

## API Endpoint Mapping

| Operation | Twilio Endpoint | Telnyx Endpoint |
|---|---|---|
| Basic lookup | `GET /v2/PhoneNumbers/{number}` | `GET /v2/number_lookup/{number}` |
| Carrier lookup | `GET /v2/PhoneNumbers/{number}?Fields=line_type_intelligence` | `GET /v2/number_lookup/{number}?type=carrier` |
| CNAM lookup | `GET /v2/PhoneNumbers/{number}?Fields=caller_name` | `GET /v2/number_lookup/{number}?type=caller-name` |
| Carrier + CNAM | `GET /v2/PhoneNumbers/{number}?Fields=line_type_intelligence,caller_name` | Two requests: `?type=carrier`, then `?type=caller-name` |
| Bulk lookup | N/A (loop over numbers) | N/A (loop over numbers) |

**Authentication comparison:**

| Aspect | Twilio | Telnyx |
|---|---|---|
| Method | Basic Auth (`SID:Token`) | Bearer Token |
| Header | `Authorization: Basic <base64>` | `Authorization: Bearer <api_key>` |

## Common Pitfalls

1. **Query parameter syntax differs** — Twilio uses `Fields=line_type_intelligence`. Telnyx uses `type=carrier`. The parameter names and values are different.

2. **Line type is in `portability`, not `carrier`** — In Telnyx, the line type (`mobile`, `fixed line`, `voip`) is found at `portability.line_type`, not directly on the carrier object. The `carrier.type` field describes the carrier itself, not the line.

3. **`valid` maps to `valid_number`** — Twilio returns a `valid` boolean. The Telnyx equivalent is the top-level `valid_number` field, returned by default. Telnyx may also return an error response for malformed input, so keep error handling in place.

4. **`carrier` and `caller_name` are null unless requested** — This is the most common migration bug. A plain `GET /v2/number_lookup/{number}` returns the `carrier` and `caller_name` keys set to `null`; only `portability` is populated by default. Pass `?type=carrier` or `?type=caller-name`; make two requests if both are needed. Code that reads carrier data from a parameterless lookup will fail on a null dereference.

5. **CNAM availability is US-only** — Caller name (CNAM) data is primarily available for US numbers. International numbers may return null for `caller_name`.

6. **Carrier name normalization** — Telnyx provides both `carrier.name` (raw) and `carrier.normalized_carrier` (standardized). Use `normalized_carrier` for consistent matching across MVNOs and resellers.

7. **No caller type returned** — Twilio returns `caller_type` (CONSUMER/BUSINESS) alongside CNAM. Telnyx does not provide this field. If your application uses caller type for routing decisions, you will need an alternative data source.

8. **Rate limiting** — Both APIs have rate limits. Telnyx rate limits are documented in the API response headers. If migrating bulk lookup workloads, implement retry logic with exponential backoff.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall