Skip to main content
Geomatch automatically selects sender numbers that share the same area code as your recipients. When enabled, Telnyx matches your outbound messages with locally-recognized numbers—boosting trust and engagement with your customers.
Geomatch is part of Number Pool settings. You must have Number Pool enabled to use Geomatch.

​
When to Use Geomatch

Local Presence

Appear local to recipients—messages from familiar area codes are more likely to be read and trusted.

Higher Engagement

Local numbers typically see better response rates than out-of-area or toll-free numbers.

Multi-Region Campaigns

Automatically match senders across different geographic areas without manual routing logic.

Customer Support

Build rapport with customers who prefer communicating with local business numbers.
NANP only: Geomatch currently supports only North American numbers (US, Canada, Caribbean). International numbers don’t participate in geomatching.

​
How It Works

  1. Message sent: Your app sends a message without specifying a from number (using Number Pool)
  2. Area code lookup: Telnyx identifies the recipient’s area code
  3. Pool search: Telnyx searches your number pool for a matching area code
  4. Selection: If found, that number is used; otherwise, a number with a different area code is selected

​
Prerequisites

​
Configure Geomatch

Enable Geomatch by updating your Messaging Profile’s number_pool_settings. 
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "long_code_weight": 1,
      "geomatch": true
    }
  }'
The examples include long_code_weight to ensure Number Pool is active. If you already have Number Pool configured, you can omit weight fields—PATCH requests merge with existing settings.

​
Selection Behavior

Understanding how Geomatch selects senders helps you optimize your number pool coverage.

​
Selection Priority

When both Geomatch and Sticky Sender are enabled:
PriorityConditionBehavior
1Sticky mapping existsUse the mapped sender (geomatch ignored)
2No mapping + matching area code availableUse geomatched number, create sticky mapping
3No mapping + no matching area codeUse any available number, create sticky mapping
Sticky Sender takes precedence over Geomatch. Once a recipient is mapped to a sender, that sender is used regardless of area code matching.

​
Coverage Planning

For effective geomatching, ensure your number pool covers the area codes where your recipients are located:
Coverage LevelDescriptionExample
Full coverageNumbers in all target area codesPool: 415, 212, 312, 305 for SF, NYC, Chicago, Miami campaigns
Regional coverageNumbers per region, not every area codePool: 415 for CA, 212 for NY, 312 for IL
Minimal coverageSingle area codePool: Only 415 numbers (geomatch rarely activates)
Use the Phone Numbers API to audit your pool’s area code coverage. Search for numbers in missing area codes to improve geomatch rates.

​
Disable Geomatch

To disable Geomatch while keeping Number Pool active: 
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "geomatch": false
    }
  }'
Geomatch works best combined with other Number Pool features:
Maintain the same sender for each recipient. When combined with Geomatch:
  • First message uses geomatch selection
  • Subsequent messages use the “stuck” sender (even if area code no longer matches)
See Sticky Sender for details.
Exclude poorly performing numbers from the pool. A geomatched number will be skipped if:
  • skip_unhealthy: true is enabled
  • The number’s deliverability rate is below 25% OR spam ratio exceeds 75%
The next best geomatch candidate is used instead.
Control the ratio of long codes to toll-free numbers. Geomatch respects these weights—if you weight toll-free higher, toll-free numbers are preferred even when long codes have matching area codes.See Number Pool for configuration details.

​
Troubleshooting

Possible causes:
  • Geomatch not enabled on the profile
  • No numbers with matching area code in your pool
  • Sticky Sender is enabled and recipient already has a mapping to a different number
  • Matching number is unhealthy and skip_unhealthy is enabled
Solution: Verify Geomatch is enabled, then check your pool’s area code coverage. Use the portal or API to list numbers assigned to your messaging profile.
Cause: Geomatch only supports NANP (North American Numbering Plan) numbers—US, Canada, and Caribbean.Solution: For international messaging, use explicit from numbers or rely on weight-based Number Pool selection.
Possible causes:
  • Number Pool is not enabled (Geomatch requires Number Pool)
  • Only one number in the pool (nothing to match against)
  • Sending with explicit from number (bypasses Number Pool entirely)
Solution: Ensure Number Pool is enabled with at least one weight > 0, verify multiple numbers are assigned to the profile, and omit from when sending to use the pool.

​
Next Steps

Number Pool

Learn about multi-number distribution and weights

Sticky Sender

Maintain consistent sender numbers per recipient

Send Messages

Complete messaging quickstart

API Reference

Full Messaging Profiles API details