Create Vault with Enhanced Phone Number Support

POST https://tenants-gateway-api-sbx.sidedrawersbx.com/api/v1/tenants/tenant/tenant-id/{tenantId}/vaults

Create a new vault with comprehensive phone number support for owners and collaborators.

This endpoint creates a complete vault structure including filing cabinets, sidedrawers, and user accounts with enhanced phone number handling capabilities.

Phone Number Enhancement Features

Automatic Phone Extension Defaulting

• When phoneNumber is provided but phoneExt is omitted phoneExt automatically defaults to 1
• When both fields are provided phoneExt is preserved as specified
• When phoneNumber is not provided any phoneExt value is ignored and removed

Comprehensive Validation

• Format: Numeric only (no strings, formatting characters, or special symbols)
• Range: Positive integers only (0 to maximum safe integer)
• Type Safety: Strict validation prevents malformed data
• Error Handling: Detailed error responses with specific error codes

International Support

• US/Canada Numbers: phoneNumber: 5551234567 phoneExt: 1 (auto-default)

• UK Numbers: phoneNumber: 447123456789, phoneExt: 44

• Other Countries: Full support for international formats

• Extensions: Support for internal extensions and routing codes

Request Structure

Owner Phone Configuration

{
  "owner": {
    "fullName": "John Doe",
    "emailAddress": "[email protected]",
    "phoneNumber": 5551234567,     // Optional: Numeric format only
    "phoneExt": 1                  // Optional: Auto-defaults to 1 if omitted
  }
}

Collaborators Phone Configuration

{
  "collaborators": [
    {
      "fullName": "Jane Smith",
      "emailAddress": "[email protected]",
      "phoneNumber": 447123456789,  // UK number
      "phoneExt": 44                // UK country code
    },
    {
      "fullName": "Bob Johnson",
      "emailAddress": "[email protected]",
      "phoneNumber": 5551234567     // US number (phoneExt auto-defaults to 1)
    }
  ]
}

Phone Number Business Logic

Auto-Defaulting Scenarios

1. US Number (Auto-Default):

   • Input: { "phoneNumber": 5551234567 }
   • Result: { "phoneNumber": 5551234567, "phoneExt": 1 }

2. International Number (Explicit):

   • Input: { "phoneNumber": 447123456789, "phoneExt": 44 }
   • Result: { "phoneNumber": 447123456789, "phoneExt": 44 }

3. Extension Number:

   • Input: { "phoneNumber": 5551234567, "phoneExt": 123 }
   • Result: { "phoneNumber": 5551234567, "phoneExt": 123 }

4. No Phone (Cleanup):

   • Input: { "phoneExt": 1 } (without phoneNumber)
   • Result: {} (phoneExt removed)

Validation Rules

• Valid: 5551234567, 447123456789, 0, 123

• Invalid: "5551234567" (string), -123 (negative), 555.123 (float)

Error Handling

Phone Number Validation Errors

• Error Code: invalid_phone_number_format
• HTTP Status: 400 Bad Request
• Triggers: String values, negative numbers, float values

Phone Extension Validation Errors

• Error Code: invalid_phone_ext_format
• HTTP Status: 400 Bad Request
• Triggers: String values, negative numbers, float values

Example Error Response

{
  "statusCode": 400,
  "message": "invalid_phone_number_format",
  "error": "Bad Request"
}

Integration Flow

1. Request Validation: Phone numbers validated at gateway layer

2. Data Normalization: Phone extensions auto-defaulted as needed

3. User Account Creation: Phone data passed to user service

4. Invitation Processing: Phone data included in invitation flow

5. Account Linking: Phone numbers associated with user accounts

Backward Compatibility

• Existing Requests: Continue to work without modification

• Optional Fields: Phone fields are completely optional

• Legacy Support: No breaking changes to existing API contracts

• Migration: Seamless upgrade path for existing integrations

Performance & Security

• Validation: Minimal overhead with efficient numeric checks

• Security: Input sanitization prevents injection attacks

• Logging: Comprehensive audit trail for phone number operations

• Monitoring: Structured logs enable performance tracking

Use Cases

Enterprise Deployment

• Multi-national organizations with diverse phone number formats
• Internal extension systems for large corporations
• Country-specific routing and compliance requirements

Client Onboarding

• Automated account creation with phone verification
• International client support with proper country codes
• Seamless integration with existing CRM systems

Collaboration Workflows

• Team member invitation with phone contact information
• Cross-border collaboration with international phone support
• Emergency contact information for critical vault access .