Twilio Lookup Script

README.md

📞 linelookup — Twilio Phone Intelligence CLI Tool

Query phone number line type, carrier, SIM swap risk, and caller name using the Twilio Lookup API.

🔧 Requirements

• curl
• jq
• Environment variables:

  export TWILIO_ACCOUNT_SID=ACxxxxx
  export TWILIO_AUTH_TOKEN=your_auth_token

🛠 Setup

chmod +x linelookup.sh
mkdir -p ~/.local/bin
cp linelookup.sh ~/.local/bin/linelookup

Ensure ~/.local/bin is in your PATH.

🧪 Usage

linelookup 7141234567
echo 7141234567 | linelookup -m filter

🔍 Output Modes

• -m raw → Raw JSON
• -m jq (default) → Pretty JSON via jq
• -m filter → Colorized summary

---

Data from Twilio Lookup API.

linelookup.sh

#!/bin/bash
# Twilio Lookup API Script (Caller + Line Intelligence)
# Usage: linelookup.sh [-m raw|jq|filter] [PhoneNumber]
# Author: Ray Kooyenga
# Version: 0.3
# Dependencies: jq, curl
# TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN must be set in environment

# Color codes
RED="\e[1;31m"
YELLOW="\e[1;33m"
CYAN="\e[1;36m"
RESET="\e[0m"

print_usage() {
  echo -e "${YELLOW}Usage:${RESET} $0 [-m raw|jq|filter] [PhoneNumber]"
  echo -e "${YELLOW}Example:${RESET} echo 7141234567 | $0 -m filter"
  exit 1
}

colored_label() {
  echo -en "${CYAN}$1${RESET}"
}

lookup_phone_number() {
  local phone="$1"
  local mode="$2"

  if [[ -z "$phone" ]]; then
    echo -e "${RED}Error:${RESET} Please provide a phone number in the format 7141234567"
    print_usage
  fi

  if [[ -z "$TWILIO_ACCOUNT_SID" || -z "$TWILIO_AUTH_TOKEN" ]]; then
    echo -e "${RED}Error:${RESET} TWILIO_ACCOUNT_SID or TWILIO_AUTH_TOKEN environment variables are not set."
    exit 1
  fi

  echo -e "${YELLOW}Looking up:${RESET} $phone"
  echo "----------------------------------------"

  response=$(curl -s -X GET "https://lookups.twilio.com/v2/PhoneNumbers/$phone?Fields=caller_name,line_type_intelligence" \
    -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN")

  if [[ -z "$response" ]]; then
    echo -e "${RED}Error:${RESET} No response received from Twilio API."
    exit 1
  fi

  case "$mode" in
    raw)
      echo "$response"
      ;;
    jq)
      echo "$response" | jq
      ;;
    filter)
      colored_label "Sim Swap Risk         : "; echo "$(echo "$response" | jq -r '.sim_swap // "N/A"')"
      colored_label "SMS Pump Risk         : "; echo "$(echo "$response" | jq -r '.sms_pumping_risk // "N/A"')"
      colored_label "National Format       : "; echo "$(echo "$response" | jq -r '.national_format')"
      colored_label "International         : "; echo "$(echo "$response" | jq -r '.phone_number')"
      colored_label "Country Code          : "; echo "$(echo "$response" | jq -r '.country_code')"
      colored_label "Line Type             : "; echo "$(echo "$response" | jq -r '.line_type_intelligence.type // "N/A"')"
      colored_label "Carrier               : "; echo "$(echo "$response" | jq -r '.line_type_intelligence.carrier_name // "N/A"')"
      colored_label "MCC (Mobile Country)  : "; echo "$(echo "$response" | jq -r '.line_type_intelligence.mobile_country_code // "N/A"')"
      colored_label "MNC (Network Code)    : "; echo "$(echo "$response" | jq -r '.line_type_intelligence.mobile_network_code // "N/A"')"
      colored_label "Caller Name           : "; echo "$(echo "$response" | jq -r '.caller_name.caller_name // "N/A"')"
      colored_label "Caller Type           : "; echo "$(echo "$response" | jq -r '.caller_name.caller_type // "N/A"')"
      colored_label "Caller Name ErrorCode : "; echo "$(echo "$response" | jq -r '.caller_name.error_code // "N/A"')"
      ;;
    *)
      echo -e "${RED}Error:${RESET} Unknown mode '$mode'"
      print_usage
      ;;
  esac
}

# Default mode
MODE="jq"
PHONE=""

# Parse arguments
while [[ $# -gt 0 ]]; do
  case "$1" in
    -m|--mode)
      MODE="$2"
      shift 2
      ;;
    -*)
      echo -e "${RED}Unknown option:${RESET} $1"
      print_usage
      ;;
    *)
      PHONE="$1"
      shift
      ;;
  esac
done

# Allow pipe input
if [[ -z "$PHONE" && ! -t 0 ]]; then
  read -r PHONE
fi

lookup_phone_number "$PHONE" "$MODE"