Device Opt-out

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.

POST /devices/manage

Device Opt-out

cURL

curl --request POST \
  --url https://api-0{dc}.moengage.com/v1/devices/manage \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_identifier_type": "<string>",
  "user_identifier_value": "<string>",
  "reason": "<string>",
  "client_reference_id": "<string>",
  "device_identifiers": [
    {
      "GAID": "<string>",
      "IDFV": "<string>",
      "unique_id": "<string>",
      "device_unique_id": "<string>",
      "push_id": "<string>"
    }
  ]
}
'

import requests

url = "https://api-0{dc}.moengage.com/v1/devices/manage"

payload = {
    "user_identifier_type": "<string>",
    "user_identifier_value": "<string>",
    "reason": "<string>",
    "client_reference_id": "<string>",
    "device_identifiers": [
        {
            "GAID": "<string>",
            "IDFV": "<string>",
            "unique_id": "<string>",
            "device_unique_id": "<string>",
            "push_id": "<string>"
        }
    ]
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_identifier_type: '<string>',
    user_identifier_value: '<string>',
    reason: '<string>',
    client_reference_id: '<string>',
    device_identifiers: [
      {
        GAID: '<string>',
        IDFV: '<string>',
        unique_id: '<string>',
        device_unique_id: '<string>',
        push_id: '<string>'
      }
    ]
  })
};

fetch('https://api-0{dc}.moengage.com/v1/devices/manage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-0{dc}.moengage.com/v1/devices/manage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_identifier_type' => '<string>',
    'user_identifier_value' => '<string>',
    'reason' => '<string>',
    'client_reference_id' => '<string>',
    'device_identifiers' => [
        [
                'GAID' => '<string>',
                'IDFV' => '<string>',
                'unique_id' => '<string>',
                'device_unique_id' => '<string>',
                'push_id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-0{dc}.moengage.com/v1/devices/manage"

	payload := strings.NewReader("{\n  \"user_identifier_type\": \"<string>\",\n  \"user_identifier_value\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"device_identifiers\": [\n    {\n      \"GAID\": \"<string>\",\n      \"IDFV\": \"<string>\",\n      \"unique_id\": \"<string>\",\n      \"device_unique_id\": \"<string>\",\n      \"push_id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-0{dc}.moengage.com/v1/devices/manage")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_identifier_type\": \"<string>\",\n  \"user_identifier_value\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"device_identifiers\": [\n    {\n      \"GAID\": \"<string>\",\n      \"IDFV\": \"<string>\",\n      \"unique_id\": \"<string>\",\n      \"device_unique_id\": \"<string>\",\n      \"push_id\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-0{dc}.moengage.com/v1/devices/manage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_identifier_type\": \"<string>\",\n  \"user_identifier_value\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"client_reference_id\": \"<string>\",\n  \"device_identifiers\": [\n    {\n      \"GAID\": \"<string>\",\n      \"IDFV\": \"<string>\",\n      \"unique_id\": \"<string>\",\n      \"device_unique_id\": \"<string>\",\n      \"push_id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

200

success_response

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

Rate Limit

1000 API requests per min.

Postman Collections

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

Authorizations

Authorization · string · header · required

This authentication parameter, used for access control, must be passed along with the request. 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_WORKSPACEID_APIKEY=="}

The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:

1. Navigate to Settings -> Account -> APIs.
2. Copy the following details:
   • Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
   • Password: In 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.

Query Parameters

app_id · string · required

This is the Workspace ID of your MoEngage account that must be included in the request. You can find your Workspace ID in the following navigation on the dashboard: Settings > Account > APIs > Workspace ID.

Body

application/json

user_identifier_type · string · required

This field denotes the type of user identifier.

user_identifier_value · string · required

This field denotes the user identifier.

action_type · enum<string> · required

This field denotes the type of action to be achieved using this API.

Available options: block, unblock

reason · string

This field denotes the reason for blocking or unblocking a device.

client_reference_id · string

This field denotes the reference ID of the user.

device_identifiers · object[]

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.

Show child attributes

Response

200

application/json

This response is returned when the request is processed successfully.

status · string

This field contains the status of the request and specifies whether the request was successful.

Example:

"success"

message · string

Example:

"Your request has been accepted and will be processed soon."