canonical: https://jentic.com/apis/interzoid.com/interzoid-get-global-phone-number-information-api

# Interzoid Get Global Phone Number Information API

The Interzoid Get Global Phone Number Information API returns geographic and demographic context for an international telephone number, including the primary city, country, region, primary and secondary languages, mobile-vs-landline classification, and a wealth indicator. It is intended as an enrichment step on inbound leads, account registrations, and CRM rows where a phone number is the most reliable identity signal. The single GET endpoint accepts an international number with country code and returns a structured JSON object suitable for routing, segmentation, or fraud-screening logic.

## For AI agents

Look up city, country, language, mobile classification, and wealth signals for an international phone number so an agent can enrich, route, or segment a contact record.

## Scope

Does not send SMS, validate carrier identity, or perform number portability lookups - use for geographic and demographic enrichment of an international phone number only.

## Capabilities

- Resolve a country and primary city for an international phone number to enrich a CRM lead row
- Detect whether a number is mobile or landline before sending an SMS
- Identify the primary and secondary spoken languages tied to a number for localized outreach
- Apply a wealth indicator returned by the API to segment inbound leads for sales follow-up
- Validate that an international number resolves to a known locale before persisting it on a customer record

## Use cases

### Inbound Lead Enrichment

Enrich an inbound lead form submission that captured only an international phone number with city, country, language, and mobile classification. The Get Global Phone Number Information API returns these fields from a single GET call, so the enrichment step can complete inside the form-submission webhook before the lead lands in the CRM. Agents typically write the returned PrimaryCity, Country, and Mobile fields to dedicated lead columns.

Example prompt: Call /getglobalnumberinfo with intlnumber=+447911123456 and write the returned Country, PrimaryCity, and Mobile values into the lead's enrichment fields.

### Pre-Send Mobile Classification

Decide whether to send an SMS to a captured number by first checking the Mobile field returned by the API. Numbers classified as landlines are routed to a voice-call workflow instead of the SMS gateway, avoiding wasted message spend and undelivered traffic. The same call returns Country so messaging can also be gated on regional compliance.

Example prompt: Call /getglobalnumberinfo with the customer's intlnumber and skip the SMS step if the Mobile field is not set to 'Yes'.

### Localized Outreach Routing

Route a contact to the correct localized outreach queue based on the primary language returned for their phone number. The API provides PrimaryLanguage, Language2, and Language3 so an agent can assign Spanish-speaking contacts to the Spanish queue and Portuguese-speaking contacts to the Portuguese queue without scraping country-to-language mapping tables. Region and Country are included for further segmentation.

Example prompt: Call /getglobalnumberinfo for each new contact and route them to the outreach queue matching the returned PrimaryLanguage value.

### Agent-Driven Lead Scoring via Jentic

An AI sales-assist agent uses Jentic to call the Interzoid Get Global Phone Number Information API as part of a lead-scoring workflow. The agent retrieves Country and Wealth, combines them with other CRM signals, and writes a score back to the lead row. Through Jentic the Interzoid license key is held in the credential vault and never enters the agent context.

Example prompt: Use Jentic to search for 'look up information for an international phone number', load /getglobalnumberinfo, and execute it for the 50 newest leads to populate Country, Wealth, and Mobile columns.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/getglobalnumberinfo` | Return country, city, language, mobile flag, and wealth signals for an international phone number |

## Key resources

- **Global Phone Number Information** — GET endpoint that accepts an international phone number and returns country, primary city, region, primary and secondary languages, mobile flag, and wealth indicator.

## Why Jentic

- **Setup:** Wiring the Interzoid Get Global Phone Number Information API by hand means obtaining a license key, appending it as a license query parameter on each call to /getglobalnumberinfo, and handling the request plumbing yourself. Through Jentic you install once, import this API from the API Directory, store the license key once, and your agent calls it.
- **Permission scoping:** This API exposes a single read-only GET /getglobalnumberinfo operation that takes an international phone number in the query, with no resource id in the URL path, so scoping is at the operation level: you limit the agent to the number-enrichment lookup it needs. It only reads geographic and demographic detail and writes nothing, so there is no destructive operation to include.
- **Credential handling:** Your Interzoid license key is stored once, encrypted, by your own Jentic One instance and injected as the license parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up information for an international phone number', and Jentic returns the Get Global Phone Number Information operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NumVerify** — Phone number validation and lookup with carrier and line-type detection in addition to country.
- **Interzoid Get Area Code From Number API** — Returns the area code component of a North American phone number, useful alongside global enrichment for US-focused workflows.
- **Twilio Lookups** — Twilio's phone-number lookup product with carrier, caller-name, and line-type intelligence.

## FAQ

### What authentication does the Interzoid Get Global Phone Number Information API use?

The API uses an Interzoid license key passed as the required `license` query parameter on /getglobalnumberinfo. Through Jentic the license key is held in the credential vault and injected at execution time, so the raw key never enters the agent context.

### Can I tell whether a number is a mobile or landline with this API?

Yes. The 200 response on /getglobalnumberinfo includes a Mobile field that indicates whether the number is classified as a mobile device. Agents commonly use this field to gate SMS sends or to split lead lists between voice and messaging workflows.

### What are the rate limits for the Interzoid Get Global Phone Number Information API?

The OpenAPI spec does not declare a numeric rate limit. Each successful call decrements a credit balance returned in the Credits response field, and a 402 status is returned when credits are exhausted. Refer to interzoid.com for current per-license-tier throughput.

### How do I enrich a phone number through Jentic?

Install the SDK with `pip install jentic`, search for 'look up information for an international phone number', load /getglobalnumberinfo, then execute it with intlnumber set to the E.164-style number. The Country, PrimaryCity, and Mobile fields can be written straight to the contact record.

### What happens if the number is not found?

The API returns a 404 status with no enrichment payload when the supplied intlnumber cannot be matched. Agents should treat this as a soft failure and leave the enrichment columns null rather than retrying.

### Does the API return the carrier name?

No. The 200 response contains Country, PrimaryCity, Region, PrimaryLanguage, Language2, Language3, Mobile, and Wealth. Carrier-level lookup is not supported by this endpoint.

### Can I limit what my agent is allowed to do with the Interzoid Get Global Phone Number Information API?

Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials your agent may use, and this API exposes only a single read-only GET /getglobalnumberinfo lookup, so you scope the agent at the operation level to just the phone-number enrichment it needs. That operation only reads geographic and demographic detail such as Country, PrimaryCity, PrimaryLanguage, Mobile, and Wealth for the supplied international number and writes nothing, so there is no destructive action to allow. You control this by granting your agent access to that one lookup and holding the Interzoid license key on your own instance.