Phone Number (Optional)

The primary phone number for the user in numeric format only. This field supports international phone numbers and must be provided as a positive integer without any formatting characters (no spaces, dashes, parentheses, or plus signs).

Key Features:

• Format: Numeric only (e.g., 5551234567, not "555-123-4567")
• Type: Positive integer
• Range: 0 to maximum safe integer
• Auto-Extension: When provided without phoneExt, phoneExt automatically defaults to 1
• Validation: Strict numeric validation prevents malformed data

Business Logic:

• If phoneNumber is provided but phoneExt is omitted/null phoneExt defaults to 1
• If phoneNumber is not provided any phoneExt value is ignored and removed
• Both fields work together to represent complete phone information

Usage Examples:

• US Number: 5551234567 (phoneExt auto-set to 1)
• UK Number: 447123456789 (typically paired with phoneExt: 44)
• Internal Extension: 5551234567 (paired with phoneExt: 123)

Error Handling:

• Invalid formats (strings, negatives, floats) return HTTP 400 with error code
• Comprehensive validation ensures data integrity
• Detailed error messages aid in debugging

Integration Notes:

• Seamlessly integrates with existing user account creation
• Maintains backward compatibility with existing API contracts
• Supports both domestic and international phone number formats
  .

Phone Extension/Country Code (Optional)

The phone extension or country code associated with the phone number. This field provides additional context for the phone number and supports various use cases including country codes, internal extensions, and routing information.

Key Features:

• Format: Numeric only (positive integer)
• Auto-Default: Automatically set to 1 when phoneNumber is provided but phoneExt is missing
• Smart Cleanup: Automatically removed when phoneNumber is not provided
• Flexible Usage: Supports country codes, extensions, and routing numbers

Business Logic & Behavior:

1. Auto-Defaulting: When phoneNumber is provided but phoneExt is null/undefined phoneExt = 1
2. Preservation: When both phoneNumber and phoneExt are provided phoneExt is preserved as-is
3. Cleanup: When phoneNumber is not provided phoneExt is ignored and removed
4. Validation: Must be a positive integer when provided

Common Use Cases:

Country Codes:

• US/Canada: 1 (default)
• UK: 44
• Australia: 61
• Germany: 49

Internal Extensions:

• Office extensions: 123, 456, 789
• Department codes: 100, 200, 300
• System routing: 1001, 2002, 3003

Special Values:

• 0: Valid edge case (some systems use 0 for specific routing)
• 1: Default value for US/Canada numbers
• Large numbers: Support for complex routing systems

Integration Examples:

// US number (auto-default)
{ "phoneNumber": 5551234567 }
// Result: { "phoneNumber": 5551234567, "phoneExt": 1 }

// UK number (explicit country code)
{ "phoneNumber": 447123456789, "phoneExt": 44 }
// Result: { "phoneNumber": 447123456789, "phoneExt": 44 }

// Internal extension
{ "phoneNumber": 5551234567, "phoneExt": 123 }
// Result: { "phoneNumber": 5551234567, "phoneExt": 123 }

// No phone (cleanup)
{ "phoneExt": 1 }
// Result: {} (phoneExt removed)

Error Handling:

• Invalid formats return HTTP 400 with specific error codes
• Comprehensive validation prevents data corruption
• Structured error responses aid in client-side handling
  .