Managing Mobile Users and Devices Without the SDK

This document describes how to manage mobile users and devices without using Iterable's mobile SDKs.

# Table of contents

# Creating and updating users

Mobile apps can use Iterable's API to create and update user profiles in Iterable. User profiles are identified by your project's unique identifier, which may be email, userId, or both. Read Project Types and Unique Identifiers to learn more.

To create or update an Iterable user profile, call POST /api/users/update.

Sample request body (using email, not userId):

{
  "email": "docs@iterable.com",
  "dataFields": {
    "catName": "Jimmy"
  },
  "mergeNestedObjects": true
}

When calling the POST /api/users/update, setting mergeNestedObjects to true (defaults to false) causes Iterable to merge top-level objects instead of overwriting them. For example:

• Consider a user profile with the following data:

  { "mySettings": { "mobile": true } } 
  

• Also, consider the following data passed in an update request:

  { "mySettings": { "email": true } }
  

• With mergedNestedObjects set to true, the resulting merged profile is:

  { "mySettings": { "mobile": true, "email": true } }
  

• With mergeNestedObjects set to false, the resulting merged profile is:

  { "mySettings": { "email": true } }
  

# Managing devices

Iterable provides an API for registering mobile devices for push notifications and another API for disabling devices (preventing them from receiving further push notifications).

# Registering a device token

To register a mobile device token (and enable push notifications from Iterable to that device), call POST /api/users/registerDeviceToken. In the request body, provide either email or userId (but not both) and a device object that contains a valid token, platform and applicationName.

Sample request body:

{
  "email": "docs@iterable.com",
  "device": {
    "token": "sampleToken123",
    "platform": "APNS",
    "applicationName": "Pizza Tracker",
    "dataFields": {
      "phoneType": "iPhone 6 Plus"
    }
  },
  "userId": "298398"
}

# Disabling a device

To disable a device, preventing it from receiving future push notifications from Iterable, call POST /api/users/disableDevice.

In the request body, include the device token that should be disabled. If the specified token exists on multiple user profiles, include email to disable it that single address only. Omit email to disable it on all Iterable profiles on which it can be found. The same idea applies when including or omitting userId.

Sample request body:

{
  "token": "sampleToken123",
  "email": "docs@iterable.com",
  "userId": "2"
}

If a user changes an app's settings to that it can no longer receive push notifications, but they do this after the app has already registered its device token with Iterable, the app's code should disable the device in Iterable by calling POST /api/users/disableDevice. This sets the device's endpointEnabled property to false, preventing Iterable from sending future push campaigns to that device. If the app does not disable the device, Iterable will continue to send it future campaigns. The user will never receive those campaigns, but they'll still be counted in the campaign's total send count.