Device App Register

Endpoints Summary

Method Path Swagger POST /device_app_register/ Swagger ↗

---

The Device App Register API enablesprovides functionality for registering mobile and desktop applications to register themselves with the backend system,system. providingThis endpoint captures comprehensive device and user information forincluding tracking,hardware analytics,identifiers, network details, operating system information, and user credentials for device enrollment and 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 applicationsinitial todevice and application enrollment in the Zequenze platform. This API category handles the critical first step of device onboarding, where mobile apps, desktop applications, or other client software register themselves and their associated device informationdevices with the backend systemsystem.

during

Key the initial setup or authentication process. This registration captures critical device metadata, network information, user credentials, and application details that enable the system to:Capabilities:

• Device TrackingIdentification: &Captures Analytics:multiple Collecthardware identifiers (IMEI, IMSI, ICCID, MAC address) for comprehensive device fingerprintstracking

Operating System Detection: Records detailed OS information including IMEI,family, IMSI, MAC addresses,version, and deviceAPI specifications for security and analytics purposeslevel Network Optimization:Context: CaptureIdentifies home mobile network information (MCC/MNC) to optimize services based onand carrier and geographic location Cross-Platform Support: Handle registration for multiple device types including desktops, laptops, tablets, and mobile phonesdetails User AuthenticationAssociation: Integration:Links Linkdevices device registrations withto user accounts andwith externalflexible authentication systemsoptions PushDevice NotificationCategorization: Setup:Supports Registerclassification pushacross notificationdevice keystypes for(desktop, real-timelaptop, communicationtablet, capabilitiesmobile phone)

ThisCommon APIIntegration isScenarios:

Mobile app first-launch registration Desktop application installation and activation IoT device provisioning and enrollment User device inventory management Compliance and security auditing

The registration process typically calledoccurs once perduring application installation or whenfirst significantrun, device/userestablishing changesthe occur.device Theidentity comprehensivethat datawill collectionbe enablesused backendfor systemssubsequent toAPI provideinteractions, personalizedpush experiences, security monitoring,notifications, and targeteddevice communications.management operations.

---

Endpoints

POST /device_app_register/

Description: Registers a new device and application installationinstance with the backend system,system. capturingThis endpoint should be called during app installation or first launch to establish the device identity and associate it with user credentials. The registration captures comprehensive device metadata,information networkfor information,inventory management, security tracking, and user credentials. This endpoint is essential for establishing device identity, enabling push notifications,notification and linking applications to user accounts.delivery.

Use Cases:

• InitialMobile app installationfirst-time setup and setupdevice processenrollment

Desktop application activation and licensing IoT device provisioning in enterprise environments User authenticationdevice inventory for compliance and accountsecurity linkingauditing DeviceEstablishing fingerprinting for security purposes Pushpush notification servicedelivery registration Analytics and telemetry data collectionchannels

Full URL Example:

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

Request Body 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 No Device phone number (MSISDNMSISDN) format)for mobile devices generic_id string No Unique identifier from OS/App store (e.g., UUID,Android advertisingID, ID)iOS IDFA) imei string No International Mobile Equipment Identity for cellular devices imsi string No International Mobile Subscriber Identity from SIM card iccid string No Integrated Circuit Card Identifier (from SIM card ID) mac_addr string DeviceNo MAC address of primary network interface home_mobile_network_name string NameNo ofCarrier thename home(e.g., mobile"Verizon", network"AT&T", carrier"Vodafone") home_mobile_network_mccmnc string No Mobile Country Code and Mobile Network Code (e.g., "310410") app_version string No Version of the registering application being registered os_family string No Operating system family (iOS,e.g., Android,"Android", Windows,"iOS", etc."Windows", "macOS") os_version string No Operating system version number(e.g., "14.0", "Windows 11") os_api_version string OperatingNo systemOS API level or SDK version device_family string GeneralNo deviceDevice family classificationor series (e.g., "iPhone", "Galaxy", "ThinkPad") device_brand string No Device manufacturer (Apple,e.g., Samsung,"Apple", Google,"Samsung", etc."Lenovo") device_model string No Specific device model name(e.g., "iPhone 15 Pro", "Galaxy S24") device_type string No Device category: 'de' (Desktop), 'la' (Laptop), 'tb' (Tablet), 'ph' (Mobile phone) push_key string No Push notification servicetoken token/keyfor message delivery username string No User account username for device association password string No User account password for authentication user_external_id string No External system user identifier fromfor third-party systemsintegration user_class string No 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"android-id-12345",
    "imei": "123456789012345",
    "device_brand"mac_addr": "Apple"00:1B:44:11:3A:B7",
    "device_model"home_mobile_network_name": "iPhoneVerizon 15 Pro"Wireless",
    "device_type"home_mobile_network_mccmnc": "ph",
    "os_family": "iOS",
    "os_version": "17.2.1"311480",
    "app_version": "2.1.0",
    "os_family": "Android",
    "os_version": "14.0",
    "os_api_version": "34",
    "device_family": "Galaxy",
    "device_brand": "Samsung",
    "device_model": "Galaxy S24",
    "device_type": "ph",
    "push_key": "fcm-token-abc123xyz789",
    "username": "john.doe",
    "push_key"password": "abc123def456ghi789"securePassword123",
    "home_mobile_network_name"user_class": "Verizon",
    "home_mobile_network_mccmnc": "31000"premium"
  }'

Example Response:

{
  "number": "+1234567890",
  "generic_id": "550e8400-e29b-41d4-a716-446655440000"android-id-12345",
  "imei": "123456789012345",
  "imsi": "310000123456789"311480123456789",
  "iccid": "8901260123456789012"89014103271234567890",
  "mac_addr": "02:00:00:00:00:00"1B:44:11:3A:B7",
  "home_mobile_network_name": "Verizon"Verizon Wireless",
  "home_mobile_network_mccmnc": "31000"311480",
  "app_version": "2.1.0",
  "os_family": "iOS"Android",
  "os_version": "17.2.1"14.0",
  "os_api_version": "17.2"34",
  "device_family": "iPhone"Galaxy",
  "device_brand": "Apple"Samsung",
  "device_model": "iPhoneGalaxy 15 Pro"S24",
  "device_type": "ph",
  "push_key": "abc123def456ghi789"fcm-token-abc123xyz789",
  "username": "john.doe",
  "user_external_id": "ext_user_12345"ext-user-456",
  "user_class": "premium"
}

Response Codes:

Status	Description
201	Created - Device and app successfully registered with the system
400	Bad Request - Invalid data format or missing required fields
401	Unauthorized - Invalid or missing authentication token
409	Conflict - Device or user already registered (duplicate IMEI/MAC address)
500422	InternalUnprocessable Server ErrorEntity - RegistrationValid processingformat but business logic validation failed

---

Common Use Cases

Use Case 1: Mobile App First Launch Registration

RegisterWhen a newuser installs and first opens a mobile application installation duringapp, the user'sapplication first launch, capturingcollects device identifiers, network information,information and basicregisters userwith credentialsthe backend. This establishes the device identity for accountfuture creationAPI orcalls login.and enables push notifications.

Required endpoints: POST /device_app_register/

Use Case 2: Cross-PlatformEnterprise UserDevice MigrationEnrollment

RegisterIT aadministrators newdeploying company devices use the registration API to enroll devices in the corporate management system, associating them with employee accounts and applying appropriate device whenpolicies.

an

Required existingendpoints: userPOST installs the application on an additional device, linking the new device to their existing account while maintaining separate device profiles./device_app_register/

Use Case 3: EnterpriseIoT Device ManagementProvisioning

Register corporateSmart devices withand comprehensiveIoT endpoints register themselves during initial setup, providing hardware identifiers and network information for compliancedevice tracking, security monitoring,management and assetmonitoring.

management

Required inendpoints: enterprisePOST environments./device_app_register/

Use Case 4: PushCross-Platform NotificationDevice EnablementInventory

RegisterApplications devicerunning pushon notificationmultiple tokensplatforms along(mobile, withdesktop, deviceweb) metadataregister their host devices to enablemaintain targeted,a personalizedunified notificationsinventory basedacross onall deviceuser type,touchpoints location,for security and usercompliance preferences.reporting.

Required endpoints: POST /device_app_register/

Use Case 5: AnalyticsPush and TelemetryNotification Setup

EstablishMobile and desktop applications register their push notification tokens during the device fingerprintsregistration process, enabling the backend to deliver messages and useralerts associationsto forspecific analyticsdevices.

tracking,

Required enablingendpoints: detailedPOST usage analysis, performance monitoring, and user behavior insights across different device types and network conditions./device_app_register/

---

Best Practices

• GradualPrivacy Data Collection:Compliance: Only collect device informationidentifiers that are necessary for your application actually needs. Start with essential fields and expand based on specific use casescase. Be aware of privacy regulations (GDPR, CCPA) when collecting IMEI, MAC addresses, or other persistent identifiers.

• PrivacyUnique Compliance:Device Identification: EnsureUse user consent before collecting sensitivemultiple identifiers likewhen IMEI,available IMSI,(IMEI or+ location-relatedMAC networkaddress data,+ followinggeneric_id) GDPR,to CCPA,create androbust otherdevice privacyfingerprinting regulationswhile having fallback options if some identifiers are unavailable.

• Secure Credential Handling:Handling: NeverIf logpassing username/password in registration, ensure the API connection uses HTTPS and consider using temporary tokens or cache password fields. Consider using secure authenticationOAuth flows instead of passingpermanent passwordspasswords.

  directly

• Device Type Classification: Always specify the device_type parameter to enable proper device management policies and user experience optimization based on device capabilities.

Error Handling:Handling: Implement robustretry error handlinglogic for network failuresfailures, duringbut registration,avoid withre-registering retrydevices logicthat andreturn offline409 capability(Conflict) whenresponses, possibleas this indicates the device is already known to the system.

DevicePush TypeToken Detection:Management: UseKeep standardizedpush_key devicetokens typeupdated codesas ('de',they 'la',can 'tb',expire 'ph')or consistentlychange acrosswhen yourapps applicationsare updated or reinstalled. Consider implementing a separate endpoint update mechanism for propertoken categorizationrefresh.

UpdateData Strategy:Validation: Plan for periodic re-registration or update mechanisms whenValidate device informationidentifiers changesformat before sending (OSe.g., updates,IMEI networkshould changes,be etc.)

15 digits, RateMAC Limiting:addresses Implementshould client-sidefollow throttlingstandard format) to avoid overwhelmingunnecessary theAPI calls and improve registration endpoint,success especiallyrates. during mass deployments or app updates

---