# Look up a phone number with Node.js

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 Node.js 20.3 or later. In a new project directory:

```bash
npm init -y
npm install @messagebird/sdk tsx
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.mts`:

```typescript
import { BirdClient } from "@messagebird/sdk";

const apiKey = process.env.BIRD_API_KEY;
if (!apiKey) throw new Error("Set BIRD_API_KEY before running the sample.");
const bird = new BirdClient({ apiKey });

const phoneNumber = process.env.BIRD_TEST_PHONE;
if (!phoneNumber) throw new Error("Set BIRD_TEST_PHONE to your phone number.");
const number = await bird.lookup.phoneNumber({
  phone_number: phoneNumber,
  type: ["porting", "score"],
});
console.log(number.country_code, number.line_type);
if (number.score?.status === "ok") console.log("Credibility:", number.score.value);
if (number.porting?.status === "ok") console.log("Ported:", number.porting.ported);
```

```bash
npx tsx lookup.mts
```

## 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)