Skip to main content
GET
/
app
/
launch
Bootstrap the mobile app session
curl --request GET \
  --url https://handauncle-backend-prod-205012263523.asia-south1.run.app/app/launch \
  --header 'x-device-id: <x-device-id>' \
  --header 'x-platform: <x-platform>'
{
  "success": true,
  "data": {
    "appLaunchResponseData": {
      "userData": {
        "userId": "<string>",
        "name": "<string>",
        "deviceId": "<string>",
        "platform": "android",
        "authProvider": "<string>",
        "isLoggedIn": true,
        "isVerified": true,
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "email": "jsmith@example.com",
        "phoneNumber": "<string>",
        "avatarUrl": "<string>",
        "accessTokenExpiry": "2023-11-07T05:31:56Z"
      },
      "auth": {
        "sessionExists": true,
        "refreshAllowed": true,
        "graceWindowSeconds": 123
      },
      "isOnboardingRequired": true,
      "freeThreshold": {
        "total": 123,
        "used": 123,
        "remaining": 123,
        "percentUsed": 50
      },
      "socialMediaUrls": {
        "facebook": "https://www.facebook.com/handauncle",
        "instagram": "https://www.instagram.com/handauncle",
        "linkedin": "https://www.linkedin.com/company/handauncle",
        "twitter": "https://twitter.com/handauncle"
      },
      "systemUrls": {
        "termsAndConditions": "https://www.handauncle.com/terms",
        "privacyPolicy": "https://www.handauncle.com/privacy",
        "faqs": "https://www.handauncle.com/faqs",
        "supportEmail": "hello@handauncle.com"
      }
    }
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "requestId": "<string>"
  }
}
Use this endpoint whenever the Handa Uncle mobile app boots. The backend will associate the provided device information with an existing user (if one can be identified) or create a lightweight record and respond with everything the app needs to decide whether to show onboarding, what limits apply, and which system links to surface.

​
Required headers

  • x-device-id: Stable device identifier or installation ID
  • x-platform: One of android, ios, web

​
Optional headers

  • x-user-id: Known user identifier (Auth0 / Mongo ID)
  • x-user-email: Known email address
  • x-user-phone: E.164‑formatted phone number
Providing user hints dramatically improves the chance of mapping the device to an existing account before falling back to device-based upsert logic.

​
Example request

curl -X GET https://api.handauncle.com/app/launch \
  -H 'x-device-id=ios-device-3f92' \
  -H 'x-platform=ios' \
  -H 'x-user-email=investor@example.com'

​
Response highlights

  • data.appLaunchResponseData.userData mirrors the canonical user profile, including verification, platform, and timestamps.
  • isOnboardingRequired flips to false once either an email or phone is attached to the user.
  • freeThreshold is derived from the FREE_MESSAGE_THRESHOLD environment value and the user’s current message count.
  • socialMediaUrls and systemUrls are dynamically loaded from the database, so no hard-coded URLs are required in clients. Administrators can update these URLs via the configuration endpoints without requiring app updates.
See the full schema in the OpenAPI reference panel on the right.

​
Configuration URLs

The socialMediaUrls and systemUrls returned in this response are centrally managed and can be updated by administrators. For more information:

Headers

​
x-device-id
string
required

Unique identifier for the physical device or installation.

Minimum string length: 1
​
x-platform
enum<string>
required

Platform the client is running on.

Available options:
android,
ios,
web
​
x-user-id
string

Known user identifier (Auth0 or Mongo ID) if available.

​
x-user-email
string<email>

Known user email address.

​
x-user-phone
string

Known phone number in E.164 format.

​
Authorization
string

Optional Bearer token for authenticated users. When provided, the response includes accessTokenExpiry in userData and validates device-user mapping. This enables silent refresh flows without blocking the UI.

Response

App launch payload returned.

​
success
enum<boolean>
required
Available options:
true,
false
​
data
object
required
​
meta
object
required