Phone (Semantic Module)

← Back to Modules Reference

The Phone semantic module validates, standardizes, and optionally verifies telephone numbers across your application.

Instead of dealing with messy user inputs, inconsistent area codes, and country prefixes, decorating a property with Phone automatically parses inputs using Google’s industry-standard libphonenumber library, normalizes them into standard formats (such as international E.164), and can even coordinate SMS/phone verification One-Time Passwords (OTPs).

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text or string property)
Data Type	String
Validation Standard	Google libphonenumber
Default Format	International E.164 (e.g. +14155552671)
Verification Support	Built-in 6-digit OTP verification lifecycle

---

Key Capabilities

1. Automatic Sanitization & Formatting

Users enter phone numbers in dozens of formats: (415) 555-2671, 415-555-2671, +1 415 555 2671, or 4155552671.

The Serverless Engine automatically parses and normalizes the input before saving it to the database, ensuring clean, uniform data for SMS gateways (Twilio, MessageBird) and CRM integrations.

Supported formats:

• international (Default): Normalizes to E.164 standard with a leading plus sign (e.g. +14155552671).
• national: Formats the number according to the target country’s local style (e.g. (415) 555-2671).
• custom: Allows custom digit masks (e.g. ###-###-####).

2. Country Code Enforcement & Allow Lists

To prevent invalid registrations or fraud:

• Require Country Code: Enforces that input numbers must start with a + and valid international dialing prefix.
• Allowed Countries List: Restricts acceptable phone numbers to specific ISO 3166-1 alpha-2 country codes (e.g., only allowing ['US', 'CA', 'GB']). Any valid phone number from an unlisted country is rejected.

3. Extension Management

You can choose whether callers can provide extensions (such as +14155552671 ext. 104). When allowExtension is disabled, any extension input is rejected during schema validation.

4. Automated Phone Verification (OTP Lifecycle)

When requireVerification: true is configured on the property:

• Automatic Verification Workflow: When a record is created or when the phone number is updated, the platform automatically initiates a phone verification flow, generating a secure 6-digit One-Time Password (OTP) with a 24-hour expiration window.
• Verification Status Tracking: The record’s verification state is tracked automatically (verified: false until confirmed), and sensitive verification codes are always masked from public API responses to ensure end-to-end security.

---

Configuration Options

When configuring the Phone semantic in the Domain Modeler, you can adjust the following parameters:

Option	Type	Default	Description
format	'international' | 'national' | 'custom'	'international'	The storage and output format for the phone number.
customFormat	string	undefined	Mask pattern using # for digits (e.g., ###-###-####). Only used when format is custom.
requireCountryCode	boolean	true	Requires the input to start with a + followed by the country code.
allowedCountries	string[]	[] (all allowed)	Array of allowed two-letter country codes (e.g. ['US', 'CA']).
allowExtension	boolean	false	Whether to allow phone extension suffixes.
requireVerification	boolean	false	Enables the automated 6-digit OTP verification lifecycle.
verificationMethod	'sms' | 'call'	'sms'	Preferred verification delivery channel.

---

API Lifecycle Examples

1. Creating a Customer with International Phone

A client sends a phone number with various spaces and formatting:

POST /customers
Content-Type: application/json

{
  "name": "Sarah Connor",
  "phone": "+1 (415) 555-2671"
}

Server Response (201 Created): The number is automatically normalized to E.164:

{
  "data": {
    "id": "cust_901",
    "name": "Sarah Connor",
    "phone": "+14155552671"
  }
}

---

2. Validation Failure (Disallowed Country)

If allowedCountries is set to ['US', 'CA'] and a user enters a UK phone number (+44 20 7946 0958):

Server Response (422 Unprocessable Entity):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "code": "E_VALIDATION_ERROR",
  "detail": "The country 'GB' is not allowed for field 'phone'."
}

---

Validation Rules & Modeling Guidelines

• String Properties Only: The Phone semantic module can only be applied to a String property. Tagging a number or date property generates a Semantic Data Alignment [Error] during model validation.
• Property Length Constraints: In the Domain Modeler, string properties default to a Maximum Length of 255 characters, which easily accommodates all international phone formats and extensions. If you customize the property’s Maximum Length constraint, ensure it is set to at least 32 characters to prevent long international numbers or extension suffixes from being truncated or rejected.