npm package: @sharpapi/sharpapi-node-detect-phones
Description: SharpAPI.com Node.js SDK for detecting phone numbers in text
Author: Dawid Makowski
Latest version: 1.0.1

![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")

# Phone Number Detector API for Node.js

## 📞 Detect and extract phone numbers from text — powered by SharpAPI AI.

[![npm version](https://img.shields.io/npm/v/@sharpapi/sharpapi-node-detect-phones.svg)](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-phones)
[![License](https://img.shields.io/npm/l/@sharpapi/sharpapi-node-detect-phones.svg)](https://github.com/sharpapi/sharpapi-node-client/blob/master/LICENSE.md)

**SharpAPI Phone Number Detector** parses text content and extracts phone numbers in various international formats. Perfect for lead generation, data extraction, and contact management.

---

## 📋 Table of Contents

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [Usage](#usage)
4. [API Documentation](#api-documentation)
5. [Examples](#examples)
6. [License](#license)

---

## Requirements

- Node.js >= 16.x
- npm or yarn

---

## Installation

### Step 1. Install the package via npm:

```bash
npm install @sharpapi/sharpapi-node-detect-phones
```

### Step 2. Get your API key

Visit [SharpAPI.com](https://sharpapi.com/) to get your API key.

---

## Usage

```javascript
const { SharpApiDetectPhonesService } = require('@sharpapi/sharpapi-node-detect-phones');

const apiKey = process.env.SHARP_API_KEY; // Store your API key in environment variables
const service = new SharpApiDetectPhonesService(apiKey);

const text = `
For customer support, call us at +1-555-123-4567 or toll-free at 1-800-EXAMPLE.
Our international office can be reached at +44 20 1234 5678.
`;

async function detectPhones() {
  try {
    // Submit detection job
    const statusUrl = await service.detectPhones(text);
    console.log('Job submitted. Status URL:', statusUrl);

    // Fetch results (polls automatically until complete)
    const result = await service.fetchResults(statusUrl);
    console.log('Detected phones:', result.getResultJson());
  } catch (error) {
    console.error('Error:', error.message);
  }
}

detectPhones();
```

---

## API Documentation

### Methods

#### `detectPhones(text: string): Promise<string>`

Detects and extracts phone numbers from the provided text.

**Parameters:**
- `text` (string, required): The text content to scan for phone numbers

**Returns:**
- Promise<string>: Status URL for polling the job result

**Example:**
```javascript
const statusUrl = await service.detectPhones(textWithPhones);
const result = await service.fetchResults(statusUrl);
```

### Response Format

The API returns detected phone numbers with parsed components:

```json
{
  "phone_numbers": [
    {
      "detected_number": "+1-555-123-4567",
      "parsed_number": "+15551234567",
      "country_code": "+1",
      "national_number": "5551234567",
      "country": "United States",
      "format": "international",
      "is_valid": true,
      "type": "mobile"
    },
    {
      "detected_number": "+44 20 1234 5678",
      "parsed_number": "+442012345678",
      "country_code": "+44",
      "national_number": "2012345678",
      "country": "United Kingdom",
      "format": "international",
      "is_valid": true,
      "type": "landline"
    }
  ]
}
```

---

## Examples

### Basic Phone Detection

```javascript
const { SharpApiDetectPhonesService } = require('@sharpapi/sharpapi-node-detect-phones');

const service = new SharpApiDetectPhonesService(process.env.SHARP_API_KEY);

const businessCard = `
John Doe
Senior Manager
Mobile: (555) 123-4567
Office: +1 (555) 987-6543
`;

service.detectPhones(businessCard)
  .then(statusUrl => service.fetchResults(statusUrl))
  .then(result => {
    const phones = result.getResultJson();
    console.log(`Found ${phones.length} phone numbers:`);
    phones.forEach((phone, index) => {
      console.log(`${index + 1}. ${phone.detected_number} (${phone.type})`);
    });
  })
  .catch(error => console.error('Detection failed:', error));
```

### International Phone Number Extraction

```javascript
const service = new SharpApiDetectPhonesService(process.env.SHARP_API_KEY);

const globalContacts = `
US Office: +1 (212) 555-0100
UK Office: +44 20 7946 0958
Australia: +61 2 9876 5432
Germany: +49 30 1234567
`;

const statusUrl = await service.detectPhones(globalContacts);
const result = await service.fetchResults(statusUrl);
const phones = result.getResultJson();

phones.forEach(phone => {
  console.log(`${phone.country}: ${phone.parsed_number}`);
});
```

### Custom Polling Configuration

```javascript
const service = new SharpApiDetectPhonesService(process.env.SHARP_API_KEY);

// Customize polling behavior
service.setApiJobStatusPollingInterval(5);  // Poll every 5 seconds
service.setApiJobStatusPollingWait(120);    // Wait up to 2 minutes

const statusUrl = await service.detectPhones(text);
const result = await service.fetchResults(statusUrl);
```

---

## Use Cases

- **Lead Generation**: Extract phone numbers from websites, PDFs, and documents
- **Contact Management**: Build databases from unstructured data
- **Data Validation**: Verify phone number formats and validity
- **CRM Integration**: Automatically populate contact information
- **Marketing**: Extract phone numbers for outreach campaigns
- **Document Processing**: Parse phone numbers from scanned documents
- **Customer Support**: Extract callback numbers from support tickets

---

## Supported Formats

The detector recognizes various phone number formats:

- **International**: +1 (555) 123-4567, +44 20 1234 5678
- **National**: (555) 123-4567, 555-123-4567
- **Toll-free**: 1-800-EXAMPLE, 1-888-CALL-NOW
- **Extensions**: +1 (555) 123-4567 ext. 123
- **Mobile**: Various international mobile formats
- **Landline**: Fixed-line number formats

---

## API Endpoint

**POST** `/content/detect_phones`

For detailed API specifications, refer to:
- [Postman Documentation](https://documenter.getpostman.com/view/31106842/2sBXVeGsVd)
- [Product Page](https://sharpapi.com/en/catalog/ai/content-marketing-automation/phone-numbers-detector)

---

## Related Packages

- [@sharpapi/sharpapi-node-detect-emails](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-emails) - Email detection
- [@sharpapi/sharpapi-node-detect-urls](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-urls) - URL detection
- [@sharpapi/sharpapi-node-detect-address](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-address) - Address detection
- [@sharpapi/sharpapi-node-client](https://www.npmjs.com/package/@sharpapi/sharpapi-node-client) - Full SharpAPI SDK

---

## License

This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.

---

## Support

- **Documentation**: [SharpAPI.com Documentation](https://sharpapi.com/documentation)
- **Issues**: [GitHub Issues](https://github.com/sharpapi/sharpapi-node-client/issues)
- **Email**: contact@sharpapi.com

---

**Powered by [SharpAPI](https://sharpapi.com/) - AI-Powered API Workflow Automation**