Track Device

Overview

The Device API helps add or update devices and device properties in MoEngage.

Use Cases

  • Create a new device for an existing user
  • Create new device properties for an existing user
  • Update the device properties of existing user

API Endpoint

Method: POST

API Endpoint
https://api-{{0X}}.moengage.com/v1/device/{{appId}}?app_id={{appId}}

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage maintains different data centres for different clients. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

 

info

Information

The appId for your MoEngage account is available on the MoEngage dashboard. We've revamped our Settings UI; you can find the app_id using the following path:
Settings >   Account > APIs > Workspace ID

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

You can obtain the username and password details from the MoEngage Dashboard.

  1. Navigate to Settings > Account > APIs.
  2. Click Generate Key in the Data tile in the API Keys section, and click Save.
  3. Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Request Parameter

Key Required Data Type Description

appId

Yes

String

This is your MoEngage account's Workspace ID that must be included in the request. You can find your Workspace ID in the following navigation on the dashboard:

Revamped UI: Settings > Account > APIs > Workspace ID

Request Headers

Key Required Sample Values Description

Content-Type

Yes

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Yes

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

This authentication parameter, used for access control, must be included in the request. For more information on generating the authentication header, refer to Authentication.

X-Forwarded-For

Optional

Header Value Format: <IP Address>

The 'X-Forwarded-For' header is used to specify the IP address of the client that made the request. Proxy servers or load balancers may add this header. The header value must contain the IP address of the original client that initiated the request. Multiple IP addresses may be specified in the header value, separated by commas.

Request Body

JSON
{ "type": "device",
   
"customer_id": "123",
"device_id": "1234",
"attributes": {
"model": "Samsung",
"platform": "Android",
"push_id": "503561716740895900",
"app_version": "14.0",
"os_version": "6.1.1",
"moe_gaid": {{GAID} }
}

 

Key Data Type Required Description
type String Yes

This field denotes the type of request.  Supported value is: device

Example: "type": "device"

Note: This field is case-sensitive. When passing the value in the request, follow the case as in the example.

customer_id String Yes

This field denotes the unique identifier used to identify a user in MoEngage.

Note: Devices can be created for existing users only.

device_id String Yes This field denotes the unique identifier used to identify the device associated with a user in MoEngage.
attributes JSON Object - This field contains the device attributes to add or update in the device profile. For more information, refer to Device Attributes.

Device Attributes

The following device attributes are tracked for the Device API in MoEngage.

Key Data Type Required Description
model String No This field denotes the model of the device.
platform String Yes

This field denotes the platforms where the device is supported. Supported platform values are:

  • ANDROID
  • iOS
  • Web
  • TV

Other values may lead to an unsuccessful API response (400).

push_id String Yes This field denotes the ID of the push notifications sent to the device.
moe_push_opted String No This field denotes the optin status of the device of the user
moe_push_provisional_opted String No This field denotes the provisional push optin status of the user. Know more about provisional push here.
app_version String No This field denotes the version of the app on the device.
os_version String No This field denotes the device's operating system version.
moe_gaid String No This field denotes the unique advertising identifier for Android devices to measure user behavior and campaign performance.
idfv String No This field denotes the unique advertising identifier for iOS devices.

Rate Limit

You can track 10,000 devices per minute.

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the required parameters are missing from the request, attributes are not found, and incorrect values are passed.

401

Unauthorized

This response is returned when the request does not have valid authentication credentials.

403

Account Blocked

This response is returned when your MoEngage account is suspended or blocked.

413

Payload Size Exceeded

This response is returned when the payload size exceeds 128 KB.

415

Unsupported Media Type

This response is returned when the content type is not supported.

429

Rate Limit Breach

This response is returned when the number of requests has exceeded the rate limit.

500

Internal Server Error

This response is returned when the system runs into an unexpected error.

Sample Response

200 400 401 403 413 415 429 500
  {
    "status": "success",
    "message": "Your request has been accepted and will be processed soon." 
}

Sample cURL

cURL

curl--location'https://api-0X.moengage.com/v1/device/ {{APP_ID}} \ 
--header 'Content-Type: application/json' \ 
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} 
--data '{
    
"type": "device",
"customer_id": "64194550823",
"device_id": "1234",
"attributes": {
"model": "Samsung",
"platform": "Android",
"push_id": "710456912454690400",
"app_version": "8807",
"os_version": "812",
"active": "true",
"created_time": "1728966825790",

"moe_gaid": {{GAID}}
}
}'

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

arrow_drop_down Can I pass custom device attributes using the Device API?

No, you can pass only the device attributes mentioned above. Any additional custom attributes passed in the API payload are dropped during processing.

 

arrow_drop_down What happens if I pass the Identifier for Vendors (IDFV) value in the API?

The device will be created based on the Android platform, and the IDFV value passed in the API will be dropped. If the platform is iOS and a GAID value is passed, the device will be created with iOS, but the GAID attribute will be dropped. 

 

arrow_drop_down How many devices can I create for a user?

You can create a maximum of 1000 devices for a user. The user will be blocked if a 1001st device is created for the user.

 

arrow_drop_down What if I create a new device with a moe_gaid, idfv, or push_id value that already exists for an existing device attached to a user in my MoEngage workspace?

In such cases, the existing device will be deleted, and the new device will be added. 

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?