Skip to main content

Device App Register

The Device App Register API enables mobile and desktop applications to register themselves with the backend system, providing comprehensive device and user information for tracking, analytics, and user management purposes.

Base URL: https://gate.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Device App Register API is designed for applications to register themselves and their associated device information with the backend system during the initial setup or authentication process. This registration captures critical device metadata, network information, user credentials, and application details that enable the system to:

  • Device Tracking & Analytics: Collect comprehensive device fingerprints including IMEI, IMSI, MAC addresses, and device specifications for security and analytics purposes
  • Network Optimization: Capture mobile network information (MCC/MNC) to optimize services based on carrier and geographic location
  • Cross-Platform Support: Handle registration for multiple device types including desktops, laptops, tablets, and mobile phones
  • User Authentication Integration: Link device registrations with user accounts and external authentication systems
  • Push Notification Setup: Register push notification keys for real-time communication capabilities

This API is typically called once per application installation or when significant device/user changes occur. The comprehensive data collection enables backend systems to provide personalized experiences, security monitoring, and targeted communications.

Endpoints

POST /device_app_register/

Description: Registers a new application installation with the backend system, capturing comprehensive device metadata, network information, and user credentials. This endpoint is essential for establishing device identity, enabling push notifications, and linking applications to user accounts.

Use Cases:

  • Initial app installation and setup process
  • User authentication and account linking
  • Device fingerprinting for security purposes
  • Push notification service registration
  • Analytics and telemetry data collection

Full URL Example:

https://gate.zequenze.com/api/v1/device_app_register/

Parameters:

Parameter Type In Required Description
data string body Yes JSON string containing device and user registration information

Request Body Structure:

The data parameter should contain a JSON object with the following optional fields:

Field Type Description
number string Device phone number (MSISDN format)
generic_id string Unique identifier from OS/App store (e.g., UUID, advertising ID)
imei string International Mobile Equipment Identity
imsi string International Mobile Subscriber Identity
iccid string Integrated Circuit Card Identifier (SIM card ID)
mac_addr string Device MAC address
home_mobile_network_name string Name of the home mobile network carrier
home_mobile_network_mccmnc string Mobile Country Code and Mobile Network Code
app_version string Version of the application being registered
os_family string Operating system family (iOS, Android, Windows, etc.)
os_version string Operating system version number
os_api_version string Operating system API level or version
device_family string General device family classification
device_brand string Device manufacturer (Apple, Samsung, Google, etc.)
device_model string Specific device model name
device_type string Device category: 'de' (Desktop), 'la' (Laptop), 'tb' (Tablet), 'ph' (Mobile phone)
push_key string Push notification service token/key
username string User account username
password string User account password
user_external_id string External user identifier from third-party systems
user_class string User classification or service tier

cURL Example:

curl -X POST "https://gate.zequenze.com/api/v1/device_app_register/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+1234567890",
    "generic_id": "550e8400-e29b-41d4-a716-446655440000",
    "imei": "123456789012345",
    "device_brand": "Apple",
    "device_model": "iPhone 15 Pro",
    "device_type": "ph",
    "os_family": "iOS",
    "os_version": "17.2.1",
    "app_version": "2.1.0",
    "username": "john.doe",
    "push_key": "abc123def456ghi789",
    "home_mobile_network_name": "Verizon",
    "home_mobile_network_mccmnc": "31000"
  }'

Example Response:

{
  "number": "+1234567890",
  "generic_id": "550e8400-e29b-41d4-a716-446655440000",
  "imei": "123456789012345",
  "imsi": "310000123456789",
  "iccid": "8901260123456789012",
  "mac_addr": "02:00:00:00:00:00",
  "home_mobile_network_name": "Verizon",
  "home_mobile_network_mccmnc": "31000",
  "app_version": "2.1.0",
  "os_family": "iOS",
  "os_version": "17.2.1",
  "os_api_version": "17.2",
  "device_family": "iPhone",
  "device_brand": "Apple",
  "device_model": "iPhone 15 Pro",
  "device_type": "ph",
  "push_key": "abc123def456ghi789",
  "username": "john.doe",
  "user_external_id": "ext_user_12345",
  "user_class": "premium"
}

Response Codes:

Status Description
201 Created - Device and app successfully registered
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing authentication token
409 Conflict - Device or user already registered
500 Internal Server Error - Registration processing failed

Common Use Cases

Use Case 1: Mobile App First Launch

Register a new mobile application installation during the user's first launch, capturing device identifiers, network information, and basic user credentials for account creation or login.

Use Case 2: Cross-Platform User Migration

Register a new device when an existing user installs the application on an additional device, linking the new device to their existing account while maintaining separate device profiles.

Use Case 3: Enterprise Device Management

Register corporate devices with comprehensive hardware and network information for compliance tracking, security monitoring, and asset management in enterprise environments.

Use Case 4: Push Notification Enablement

Register device push notification tokens along with device metadata to enable targeted, personalized notifications based on device type, location, and user preferences.

Use Case 5: Analytics and Telemetry Setup

Establish device fingerprints and user associations for analytics tracking, enabling detailed usage analysis, performance monitoring, and user behavior insights across different device types and network conditions.

Best Practices

  • Gradual Data Collection: Only collect device information that your application actually needs. Start with essential fields and expand based on specific use cases
  • Privacy Compliance: Ensure user consent before collecting sensitive identifiers like IMEI, IMSI, or location-related network data, following GDPR, CCPA, and other privacy regulations
  • Secure Credential Handling: Never log or cache password fields. Consider using secure authentication flows instead of passing passwords directly
  • Error Handling: Implement robust error handling for network failures during registration, with retry logic and offline capability when possible
  • Device Type Detection: Use standardized device type codes ('de', 'la', 'tb', 'ph') consistently across your applications for proper categorization
  • Update Strategy: Plan for periodic re-registration or update mechanisms when device information changes (OS updates, network changes, etc.)
  • Rate Limiting: Implement client-side throttling to avoid overwhelming the registration endpoint, especially during mass deployments or app updates
Back to top