Copy page

Sender IDs

📱 SenderId Acquisition Flow Documentation

Overview

The SenderId Acquisition Flow is a critical process in the Tech231 Platform that enables tenants to request, obtain approval for, and use custom sender IDs for their SMS communications. This process ensures regulatory compliance, prevents spoofing, and maintains platform integrity while providing flexibility for legitimate business use cases.

Key Concepts

SenderId Types

• Alphanumeric: Text-based sender IDs (e.g., "MyCompany", "BANK123")
• Shortcode: Dedicated numeric shortcodes (e.g., "12345")
• SharedShortcode: Shared numeric shortcodes with keyword routing (e.g., "54321" + "PROMO")

SenderId Status States

• Released: Available for allocation (initial state)
• PendingApproval: Request submitted, awaiting admin review
• Approved: Approved and active for use (expires after 1 year)
• Rejected: Request denied by administrator
• Suspended: Temporarily disabled
• Expired: Allocation has expired

Core Components

• SenderIdGrain: Orleans grain managing individual sender ID lifecycle
• TenantSenderIdDirectoryGrain: Orleans grain managing tenant's sender ID collection
• SmsWhitelistService: Service for pre-approved sender IDs that bypass approval
• Database: PostgreSQL with Marten for event sourcing and state persistence

Process Flow Overview

Detailed Sequence Diagrams

1. SenderId Request Flow

2. Admin Approval Flow

3. SenderId Usage Validation Flow

4. Expiration and Cleanup Flow

API Endpoints

Tenant Endpoints

• POST /api/v2/sender-ids/request - Request SenderId allocation
• GET /api/v2/sender-ids - List tenant's sender IDs
• GET /api/v2/sender-ids/{id} - Get SenderId details
• PUT /api/v2/sender-ids/{id}/metadata - Update metadata
• POST /api/v2/sender-ids/{id}/documents - Attach regulatory documents
• POST /api/v2/sender-ids/search - Search available sender IDs

Admin Endpoints

• POST /api/v2/admin/sender-ids/{id}/approve - Approve allocation
• POST /api/v2/admin/sender-ids/{id}/reject - Reject allocation
• POST /api/v2/admin/sender-ids/{id}/suspend - Suspend SenderId
• POST /api/v2/admin/sender-ids/{id}/extend - Extend expiration

Data Models

Request Model

Code
{
  "senderId": "MYCOMPANY",
  "type": "Alphanumeric",
  "keyword": null,
  "businessJustification": "Customer notifications for banking services",
  "intendedUseCase": "Account alerts and promotional messages",
  "expectedMonthlyVolume": 50000,
  "regulatoryDocuments": [
    {
      "type": "BusinessLicense",
      "fileName": "business-license.pdf",
      "uploadedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Response Model

Code
{
  "success": true,
  "status": "PendingApproval",
  "requestedAt": "2024-01-15T10:30:00Z",
  "allocationId": "MYCOMPANY"
}

State Model

Code
{
  "senderId": "MYCOMPANY",
  "type": "Alphanumeric",
  "status": "Approved",
  "tenantId": "tenant-123",
  "requestedByUserId": "user-456",
  "approvedByUserId": "admin-789",
  "requestedAt": "2024-01-15T10:30:00Z",
  "approvedAt": "2024-01-16T14:20:00Z",
  "expiresAt": "2025-01-16T14:20:00Z",
  "lastUsedAt": "2024-01-20T09:15:00Z",
  "usageCount": 1250,
  "keyword": null,
  "notes": "Approved for banking notifications"
}

Error Handling

Common Error Scenarios

1. Already Allocated: SenderId is already assigned to another tenant
2. Invalid Format: SenderId doesn't match type requirements
3. Insufficient Justification: Business justification doesn't meet requirements
4. Missing Documents: Required regulatory documents not provided
5. Expired: Attempting to use an expired SenderId
6. Unauthorized: Tenant doesn't own the SenderId

Error Response Format

Code
{
  "success": false,
  "errorMessage": "Sender ID MYCOMPANY is already allocated to another tenant",
  "status": "Allocated",
  "details": {
    "errorCode": "SENDER_ID_ALREADY_ALLOCATED",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Integration Points

Orleans Grains

• SenderIdGrain: Primary grain for sender ID lifecycle management
• TenantSenderIdDirectoryGrain: Manages tenant's collection of sender IDs
• SmsGrain: Validates sender ID before SMS submission

External Services

• WhitelistService: Pre-approved sender IDs that bypass approval
• Zitadel: Authentication and tenant context
• PostgreSQL: State persistence via Marten

Event Sourcing

• All state changes are recorded as events
• History is maintained for audit purposes
• Events include: RequestSubmitted, Approved, Rejected, Suspended, Expired, Used

Monitoring and Analytics

Key Metrics

• Allocation Requests: Number of requests per tenant/time period
• Approval Rate: Percentage of requests approved vs rejected
• Usage Statistics: Message volume per SenderId
• Expiration Tracking: Upcoming expirations requiring renewal

Logging Events

• Request submission
• Approval/rejection decisions
• Usage validation
• Expiration processing
• Error conditions

Security Considerations

Access Control

• Tenants can only manage their own sender IDs
• Admin endpoints require elevated permissions
• JWT-based authentication with tenant isolation

Validation

• Format validation prevents malformed sender IDs
• Business justification review prevents abuse
• Regulatory document verification ensures compliance

Audit Trail

• Complete history of all state changes
• User attribution for all operations
• Immutable event log for compliance

Best Practices

For Tenants

1. Clear Justification: Provide detailed business justification
2. Proper Documentation: Attach all required regulatory documents
3. Realistic Volume: Provide accurate expected monthly volume
4. Monitor Expiration: Track expiration dates and renew before expiry

For Administrators

1. Timely Review: Process requests within SLA timeframes
2. Thorough Validation: Verify business justification and documents
3. Clear Communication: Provide detailed rejection reasons
4. Regular Monitoring: Track usage patterns and compliance

For Developers

1. Error Handling: Implement proper error handling for all scenarios
2. Retry Logic: Implement exponential backoff for transient failures
3. Monitoring: Add comprehensive logging and metrics
4. Testing: Include both happy path and error scenarios in tests

Conclusion

The SenderId Acquisition Flow is a robust, multi-step process that balances business flexibility with regulatory compliance and platform security. The Orleans-based architecture provides scalability and resilience, while the comprehensive audit trail ensures full traceability of all operations.

The flow supports the platform's multi-tenant architecture while maintaining proper isolation and security boundaries, making it suitable for commercial SMS operations at scale.