# Look up a phone number with Python

Read a phone number’s base information and two optional properties, checking each property’s status before using its value.

## 1. Prepare the workspace

Create a Bird API key with the Lookup scope and use a number you control in international format. Review [Lookup pricing](/products/lookup/pricing): the base lookup is billed, and requested optional properties are billed when delivered. This is a live lookup rather than a free sandbox request.

## 2. Install and configure

Use Python 3.10 or later. In a new project directory:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install messagebird-sdk
export BIRD_API_KEY="YOUR_API_KEY"
export BIRD_TEST_PHONE="YOUR_PHONE_NUMBER"
```

Replace the environment values with your own workspace credentials and test destination. The SDK selects the API region from the key. Run this example on your server or development machine.

## 3. Run the example

Save as `lookup.py`:

```python
import os

from bird import Bird

with Bird(api_key=os.environ["BIRD_API_KEY"]) as client:
    number = client.lookup.phone_number(
        phone_number=os.environ["BIRD_TEST_PHONE"], type=["porting", "score"]
    )
    print(number.country_code, number.line_type)
    if number.score is not None and number.score.status == "ok":
        print("Credibility:", number.score.value)
    if number.porting is not None and number.porting.status == "ok":
        print("Ported:", number.porting.ported)
```

```bash
python lookup.py
```

## 4. Inspect the outcome

The script prints the country and line type, then prints an optional property only when its status is `ok`. Missing output for a requested property means this example did not receive an answered value; it does not mean false or zero.

Use the [phone-number guide](/docs/guides/lookup/phone-numbers) to interpret each field. Number information does not prove possession; use [Verify](/verification-api) when the customer must demonstrate control of the destination.

## Next steps

- [Lookup API reference](/docs/api/reference/create-phone-number-lookup)
- [Use the result in signup](/docs/guides/lookup/application-flow)
- [Migration guides](/docs/guides/lookup/migrate)
- [Lookup resources](/lookup/resources)

## Related resources

- [Phone number lookup: check a number before you send](/learn/lookup/phone-number-lookup-check-a-number-before-you-send) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Phone number lookup](/phone-number-lookup-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=lookup-phone)