This plugin validates phone numbers in a specified field against a corresponding country code from another field. It leverages the libphonenumber-js library for robust, country-specific validation. The primary use case is to ensure that phone number data ingested into Flatfile is correctly formatted and valid. It can automatically correct and reformat phone numbers into various standard formats (e.g., NATIONAL, INTERNATIONAL, E164) or simply add an error to the record if the number is invalid.

​
Installation

Install the plugin using npm: 
npm install @flatfile/plugin-validate-phone

​
Configuration & Parameters

The plugin accepts a configuration object with the following parameters:
ParameterTypeRequiredDefaultDescription
phoneFieldstringYes-The API key (name) of the field containing the phone number to validate
countryFieldstringYes-The API key (name) of the field containing the country code (e.g., ‘US’, ‘GB’)
sheetSlugstringNo'**'The slug of the sheet to apply the validation to. Defaults to all sheets
autoConvertbooleanNotrueIf true, automatically updates the phone number field with the correctly formatted version
formatstringNo'NATIONAL'The desired output format: ‘NATIONAL’, ‘INTERNATIONAL’, ‘E164’, ‘RFC3966’, or ‘SIGNIFICANT’
concurrencynumberNo10Number of records to process concurrently
debugbooleanNofalseEnables verbose debug logging in the console
formatOptionsobjectNo-Additional formatting options for libphonenumber-js library

​
Usage Examples

​
Basic Usage

import { FlatfileListener } from '@flatfile/listener';
import validatePhone from '@flatfile/plugin-validate-phone';

export default function (listener) {
  listener.use(validatePhone({
    phoneField: 'phone',
    countryField: 'country',
    autoConvert: false
  }));
}
This example validates the ‘phone’ field using the ‘country’ field in all sheets. It will add errors for invalid numbers but will not automatically reformat them.

​
Configuration Example

import { FlatfileListener } from '@flatfile/listener';
import validatePhone from '@flatfile/plugin-validate-phone';

export default function (listener) {
  listener.use(validatePhone({
    sheetSlug: 'contacts',
    phoneField: 'phone_number',
    countryField: 'country_code',
    autoConvert: true,
    format: 'INTERNATIONAL',
    debug: true
  }));
}
This example validates and formats phone numbers in the “contacts” sheet using the ‘phone_number’ and ‘country_code’ fields. Valid numbers are automatically converted to INTERNATIONAL format.

​
Advanced Usage with Format Options

import { FlatfileListener } from '@flatfile/listener';
import validatePhone from '@flatfile/plugin-validate-phone';

export default function (listener) {
  listener.use(validatePhone({
    sheetSlug: 'my-sheet',
    phoneField: 'phone_number',
    countryField: 'country_code',
    format: 'INTERNATIONAL',
    formatOptions: { formatExtension: 'national' }
  }));
}
This example demonstrates using the formatOptions parameter to provide more specific formatting rules from the underlying libphonenumber-js library.

​
Troubleshooting

If validation is not working as expected:
  1. Check field names: Ensure that the phoneField and countryField values in the configuration exactly match the field keys in your Sheet template.
  2. Verify country codes: Ensure the countryField in your data contains valid two-letter ISO 3166-1 alpha-2 country codes (e.g., “US”, “GB”, “DE”).
  3. Enable debug logging: Set the debug option to true in the configuration to see more detailed logging output in your environment’s console, which can help diagnose issues.

​
Notes

​
Default Behavior

  • By default, the plugin applies to all sheets (sheetSlug: '**')
  • Phone numbers are automatically converted to the specified format when autoConvert is true (default)
  • The default format is ‘NATIONAL’
  • Records are processed with a concurrency of 10

​
Error Handling

The plugin adds errors to specific fields rather than throwing exceptions:
  • Empty phone number: “Phone number is required”
  • Empty country field: “Country is required for phone number formatting”
  • Invalid phone number: “Invalid phone number format for [country]“

​
Requirements and Limitations

  • This plugin has an external dependency on libphonenumber-js
  • The countryField must contain a valid two-letter ISO 3166-1 alpha-2 country code
  • The plugin operates as a listener on the commit:created event, processing records in batches
  • While the documentation mentions specific support for US, UK, India, Germany, France, and Brazil, the underlying library supports a wider range of countries