Device Opt-out

Overview

The Device Opt-out API blocks or unblocks specific devices from receiving push notifications triggered from MoEngage.

To prevent push notifications from reaching a specific user or all devices associated with a user, call the API to block them. This is useful for reasons such as device theft or fraudulent activity.

For example, if a device is stolen, you can use this API to block it in MoEngage, ensuring that any scheduled push notifications with sensitive content do not get delivered. You can also use the API to unblock a device if it is recovered.

API Endpoint

Method: POST

https://api-0X.moengage.com/v1/devices/manage

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.

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 UI.

On the left navigation menu in the MoEngage UI, go to Settings > Account > APIs.
Copy the following details:
1. Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
2. Password: On the API keys section, click the copy icon in the Data tile to copy the API key.
Use these details to authenticate the API requests.

Request Parameter

Key

Required

Data Type

Description

app_id

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.

MOE-APPKEY

Yes

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. You must pass the MOE-APPKEY in the request. You can find your MoEngage Workspace ID in the MoEngage UI:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

{
"user_identifier_type": "customer_id",
"user_identifier_value": "customer_id_value",
"action_type":"block",
"reason": "Suspicious activity detected on device.",
"client_reference_id": "ALERT-20241027-002",
"device_identifiers": [{"GAID":"device-abc123"}, {"IDFV":"1234"}]
}

Request Body Fields

Key	Data Type	Required	Description
user_identifier_type	String	Yes	This field denotes the type of user identifier.
user_identifier_value	String	Yes	This field denotes the user identifier.
action_type	String	Yes	This field denotes the type of action to be achieved using this API. Supported values are: block unblock
reason	String	Optional	This field denotes the reason for blocking or unblocking a device.
client_reference_id	String	Optional	This field denotes the reference ID of the user.
device_identifiers	Array	Yes	This field denotes the device identifiers associated with the device you intend to block or unblock. Supported values are: unique_id (unique_id) device_unique_id (device_id) push_id (push_id) moe_gaid (GAID) Note: If you do not pass this value, the API blocks/unblocks all current devices of the user. Ensure to pass any one of the device identifiers for a particular device. When passing the device identifiers within the array, ensure to explicitly define each of them.

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, or 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

Success Response
{
    "status": "success",
    "message": "Your request has been accepted and will be processed soon." 
}

user_identifier_value is missing in the payload
{
"status": "fail",
"error":{
    "attribute": "user_identifier_value",
    "message": "user_identifier_value is not found in the payload",
    "type": "MissingAttributeError",
    "request_id": "YRJTbvRM"       
    }
 }

user_identifier_type is missing in the payload 

{
"status": "fail",
 "error":{
     "attribute": "user_identifier_type",
     "message": "user_identifier_type is not found in the payload",
     "type": "MissingAttributeError",
      "request_id": "nuJPehHC"
      }
    }

action_type is missing in the payload   

{
"status": "fail",
"error": {
    "attribute": "action_type",
    "message": "action_type is not found in the payload",
    "type": "MissingAttributeError",
    "request_id": "nuJPehHC"
    }
  }
      
device_identifiers is missing in the payload
      
{
"status": "fail",
"error": {
   "attribute": "device_identifiers",
   "message": "device_identifiers is not found in the payload",
   "type": "MissingAttributeError",
   "request_id": "jRwBuxdC"
    }
  }
device_identifier value is invalid
{
    "status": "fail",
    "error": {
        "attribute": "device_identifiers",
        "message": "device identifier can only be in ['moe_gaid', 'push_id', 'unique_id', 'device_unique_id'] ",
        "type": "ValueError",
        "request_id": "ZtrftlVn"
    }
}

Sample response for authorization errors
{
    "status": "fail",
    "error": {
        "message": "App Secret key mismatch. Please login to the dashboard to verify key",
        "type": "Authentication required",
        "request_id": "PVUDFisO"
    }
}

Sample response for missing authentication header
{
    "status": "fail",
    "error": {
        "message": "Authentication Header Required",
        "type": "Authentication required",
        "request_id": "PiSPjGQQ"
    }
}

Sample response for when your account is blocked
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "BlockedClient",
        "request_id": "ofHUEaEQ"
    }
}


Sample response for when your account is suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "Account Suspended",
        "request_id": "gqJvCNYu"
    }
}


Sample response for when your account is temporarily suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is temporarily suspended. Please contact MoEngage team.",
        "type": "Account Temporarily Suspended",
        "request_id": "ssSJjoyD"
    }
}

Sample response for payloads exceeding the size limit
{
    "status": "fail",
    "error": {
        "message": "Payload can not exceed 128KB",
        "type": "Payload too large",
        "request_id": "VFzDwhwt"
    }
}

Sample response for unsupported media type
{
    "status": "fail",
    "error": {
        "message": "Content type is not supported",
        "type": "Unsupported media type",
        "request_id": "SgBQfKJh"
    }
}

Sample response for rate limit breach
{
    "status": "fail",
    "error": {
        "message": "Rate limits for customers exceeded. Please Try After Some Time",
        "type": "Rate Limits Exceeded",
        "request_id": "onqucLYL"
    }
}

Sample response for unknown errors
{
    "status": "fail",
    "error": {
        "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team",
        "type": "Server Error",
        "request_id": "KovrwJiF"
    }
}

Response Body

Status	Key	Data Type	Description
success	message	String	This field denotes the success message.
fail	error	JSON Object	This field denotes the error. For more information, refer to Fail.

Fail

Fail JSON object contains the following information:

Key	Data Type	Description
attribute	String	This field denotes the attribute missing in the payload.
message	String	This field denotes the error message.
type	String	This field denotes the error type.
request_id	String	This field denotes the request ID.

Refer to the Sample Response section for examples.

Rate Limit

1000 API requests per min.

Sample cURL Request

curl --location 'https://api-0X.moengage.com/v1/devices/manage?app_id={{appId}}' \
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data '{
    "user_identifier_type": "customer_id",
    "user_identifier_value": "customer_id_value",
    "action_type": "block",
    "reason": "Customer reported device as lost.",
    "client_reference_id": "{{client_reference_id}}",
    "device_identifiers": [
        {
            "unique_id": "{{unique_id}}"
        },
        {
            "device_unique_id": "{{device_id}}"
        },
        {
            "push_id": "{{push_id}}"
        },
        {
            "moe_gaid": "{{GAID}}"
        }
    ]
}'

Postman Collections

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