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
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: |
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.
- Navigate to Settings > Account > APIs.
- Click Generate Key in the Data tile in the API Keys section, and click Save.
- 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
{ "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:
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
{
"status": "success",
"message": "Your request has been accepted and will be processed soon."
}
{
"status": "fail",
"error": {
"attribute": "customer_id",
"message": "customer_id is not found in the payload",
"type": "MissingAttributeError",
"request_id": "kXwpDESb"
}
}
{
"status": "fail",
"error": {
"attribute": "attributes",
"message": "attributes is not found in the payload",
"type": "MissingAttributeError",
"request_id": "MwNnVDsC"
}
}
{
"status": "fail",
"error": {
"attribute": "platform",
"message": "'platform' is not a valid platform",
"type": "ValueError",
"request_id": "NDuFDLwS"
}
}
{
"status": "fail",
"error": {
"attribute": "push_id",
"message": "'push_id' is not found in payload",
"type": "MissingAttributeError",
"request_id": "dsLXpKgJ"
}
}
{
"status": "fail",
"error": {
"attribute": "platform",
"message": "'platform' is not found in payload",
"type": "MissingAttributeError",
"request_id": "gyLYpBFV"
}
}
{
"status": "fail",
"error": {
"message": "App Secret key mismatch. Please login to the dashboard to verify key",
"type": "Authentication required",
"request_id": "PVUDFisO"
}
}
{
"status": "fail",
"error": {
"message": "Authentication Header Required",
"type": "Authentication required",
"request_id": "PiSPjGQQ"
}
}
{
"status": "fail",
"error": {
"message": "Your account is suspended. Please contact MoEngage team.",
"type": "BlockedClient",
"request_id": "ofHUEaEQ"
}
}
{
"status": "fail",
"error": {
"message": "Your account is suspended. Please contact MoEngage team.",
"type": "Account Suspended",
"request_id": "gqJvCNYu"
}
}
{
"status": "fail",
"error": {
"message": "Your account is temporarily suspended. Please contact MoEngage team.",
"type": "Account Temporarily Suspended",
"request_id": "ssSJjoyD"
}
}
{
"status": "fail",
"error": {
"message": "Payload can not exceed 128KB",
"type": "Payload too large",
"request_id": "VFzDwhwt"
}
}
{
"status": "fail",
"error": {
"message": "Content type is not supported",
"type": "Unsupported media type",
"request_id": "SgBQfKJh"
}
}
{
"status": "fail",
"error": {
"message": "Rate limits for customers exceeded. Please Try After Some Time",
"type": "Rate Limits Exceeded",
"request_id": "onqucLYL"
}
}
{
"status": "fail",
"error": {
"message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team",
"type": "Server Error",
"request_id": "KovrwJiF"
}
}
Sample 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
No, you can pass only the device attributes mentioned above. Any additional custom attributes passed in the API payload are dropped during processing.
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.
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.
In such cases, the existing device will be deleted, and the new device will be added.