User & Device Management

Push API allows you to manage device registration and notifications. By sending HTTP request you can register, tag, change profile attribute of user/devices. You can also send notification and get the details of sent notification via REST API.

Maximum 1000 Unique External IDs in a Single REST API Request:

When making a request, you can include up to 1000 unique external IDs for processing. This limitation is in place to ensure the efficiency and proper handling of requests. If you need to include more than 1000 different external IDs, you would need to split them across multiple requests. This helps maintain the performance and reliability of the API.

Delete a User

This request serves to completely delete all information about users from Netmera.

curl --location 'https://restapi.netmera.com/rest/3.0/deleteUsersPermanently' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "extIds": [
      "externalid"
    ]
  }'

⚠️ In order to benefit from this service, it is necessary to submit an offer from the panel. You can contact the success manager for the offer.

Disable Push

Following request can be used to opt-out the devices of a user or a single device from push notifications. If you opt-out a user using extId, all of the devices of that user will be opted-out from push notifications. You can opt-out a single device using deviceToken.

curl --location 'https://restapi.netmera.com/rest/3.0/disablePush' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extId": "id_in_my_system_1"
  }'

curl --location 'https://restapi.netmera.com/rest/3.0/disablePush' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "deviceToken": "my_device_token"
  }'

Enable Push

Following request can be used to opt-in the devices of a user or a single device from push notifications. If you opt-in a user using extId, all of the devices of that user will be opted-in from push notifications. You can opt-in a single device using deviceToken.

curl --location 'https://restapi.netmera.com/rest/3.0/enablePush' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extId": "id_in_my_system_1"
  }'

curl --location 'https://restapi.netmera.com/rest/3.0/enablePush' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "deviceToken": "my_device_token"
  }'

Tagging User

The following request is used to tag a user.

curl --location 'https://restapi.netmera.com/rest/3.0/tagUsers' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "Sport",
    "extIds": ["id_in_my_system_1", "id_in_my_system_2"]
  }'

Parameters

extIds (Required): Array of external ids of users to tag. External ids comes from your system. tag (Required): Name of the tag.

Remove Tag From User

The following request is used to remove a tag from given users.

curl --location 'https://restapi.netmera.com/rest/3.0/untagUsers' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "Sport",
    "extIds": ["id_in_my_system_1", "id_in_my_system_2"]
  }'

Parameters

extIds (Required) : Array of external ids of users to tag. External ids comes from your system. tag (Required) : Name of the tag.

Setting Category Preferences

You can set opt-in/opt-out preference for each category previously defined in Netmera panel. If any message with a category sent, opt-out users will be excluded.

curl --location 'https://restapi.netmera.com/rest/3.0/setCategoryPreferences' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "extId": "id_in_my_system_1",
      "category": "Shopping",
      "enable": true
    },
    {
      "extId": "id_in_my_system_1",
      "category": "Promotion",
      "enable": false
    }
  ]'

Parameters

extId (Required): External id of a user. External id comes from your system. category (Required): Name of the category which is defined in Netmera panel. enable (Required): Preference of category opt-in/out.

Adding Profile Attributes to Users

The following request is used to set profile attributes of given users.

curl --location 'https://restapi.netmera.com/rest/3.0/setProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "extId": "id_in_my_system_1",
      "profile": {
        "age": 24
      }
    },
    {
      "extId": "id_in_my_system_2",
      "profile": {
        "name": "John"
      }
    }
  ]'

Parameters

extId (Required): External id of user to set profile attribute. profile (Required): New profile attributes. Note that previously existing profile attributes with different keys will remain same whereas profile attributes with given keys will be overwritten.

Remove Profile Attributes From Users

The following request is used to unset profile attributes of given users.

curl --location 'https://restapi.netmera.com/rest/3.0/unsetProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "extId": "id_in_my_system_1",
      "profile": ["age"]
    },
    {
      "extId": "id_in_my_system_2",
      "profile": ["age", "name"]
    }
  ]'

Parameters

extId (Required): External id of user to remove profile attribute. profile (Required): Profile attribute keys to unset.

Remove Profile Attributes From All Users

The following request is used to delete given profile attributes of all users.

curl --location 'https://restapi.netmera.com/rest/3.0/deleteProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "profile": ["name", "age"]
    }
  ]'

profile (Required): Profile attribute keys to delete.

Get Profile Attributes

The following request is used get all profile attributes associated with given user.

curl --location 'https://restapi.netmera.com/rest/3.0/getProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --get \
  --data-urlencode 'extId=id_in_my_system'

Parameters

extId (Required): External id of user to get profile attributes.

Sample response:

{
    "extId": "id_in_my_system",
    "profile": {
        "surname": "Brown",
        "name": "John",
        "dateOfBirth": 624315600000
    }
}

Pushing Profile Attributes to User

The following request is used to push profile attributes of given users.

curl --location 'https://restapi.netmera.com/rest/3.0/pushProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "extId": "id_in_my_system_1",
      "profile": {
        "lastVisitedCategories": ["shopping", "promotion"]
      }
    },
    {
      "extId": "id_in_my_system_2",
      "profile": {
        "lastVisitedProducts": ["blouse", "skirt"]
      }
    }
  ]'

Parameters

extId (Required): External id of user to push values to profile attributes. profile (Required): Profile attributes to push values. Note that given profile attribute must be an array.

Pulling Profile Attributes From User

The following request is used to pull profile attributes of given users.

curl --location 'https://restapi.netmera.com/rest/3.0/pullProfileAttributes' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "extId": "id_in_my_system_1",
      "profile": {
        "lastVisitedCategories": ["promotion"]
      }
    },
    {
      "extId": "id_in_my_system_2",
      "profile": {
        "lastVisitedProducts": ["skirt"]
      }
    }
  ]'

Parameters

extId (Required): External id of user to pull values from profile attributes. profile (Required): Profile attributes to pull values. Note that given profile attribute must be an array.

Deleting Profile Attribute From All Users

The following request is used to delete all profile attributes with a specific value from all users.

curl --location 'https://restapi.netmera.com/rest/3.0/deleteProfileAttributeValue' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "key": "lastVisitedProducts",
      "value": "shirt"
    }
  ]'

Parameters

key (Required) : Name of the profile attribute. value (Required) : Value of the profile attribute.

Get Devices of a User

The following request is used get all device info which belongs to given user.

curl --location 'https://restapi.netmera.com/rest/3.0/getDevices' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --get \
  --data-urlencode 'extId=id_in_my_system' \
  --data-urlencode 'pushPermitted=true'

Parameters

extId (Required): External id of user to get devices. pushPermitted (Optional): If this is set as true, only opt-in devices will be returned. If push permitted set as false, don't check register status fetch all devices. You can see whether register or not register with push permitted parameter in response.

Sample response:

{
    "devices": [
        {
            "platform": "ANDROID",
            "token": "push_token",
            "deviceModel": null,
            "pushPermitted": true
        },
        {
            "platform": "IOS",
            "token": null,
            "deviceModel": "iPhoneX",
            "pushPermitted": false
        }
    ],
    "extId": "id_in_my_system"
}

Get Device Tokens

curl --location 'https://restapi.netmera.com/rest/3.0/getDeviceTokens' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --get \
  --data-urlencode 'max=10' \
  --data-urlencode 'offset=0'

Parameters

max (Optional): Default value is 10. Maximum number of device info to fetch per page. offset (Optional): Default value is 0. Offset to start fetch from.

Normally, for initially request, you don't need to send max or offset value. In response, you will a have link to fetch next page.

Response

{
    "nextPage": "https://restapi.netmera.com/rest/3.0/getDeviceTokens?offset=10&max=10",
    "total": 158329,
    "devices": [
        ...
    ]
}

Use nextPage value to fetch next page as :

curl --location 'https://restapi.netmera.com/rest/3.0/getDeviceTokens?offset=10&max=10' \
  --header 'X-netmera-api-key: your_rest_api_key'

Here, you can see that offset value is sent as 10 which is number of devices in a page.

Get Segments

Two new APIs, getSegments and getSegmentUsers, have been added to Netmera APIs. Thanks to these APIs, all segments in a panel and users in these segments can be reached. You can see the details below.

curl --location 'https://restapi.netmera.com/rest/3.0/getSegments' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-netmera-os: IOS'

Sample Response

{
   "list":[
      {
         "userCount":6,
         "name":"for_test_int",
         "id":5883,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":123321,
         "name":"int_brand",
         "id":5886,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":300450,
         "name":"int_product_brand",
         "id":5887,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":100,
         "name":"int_purcc",
         "id":5907,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":12500,
         "name":"int_purccc",
         "id":5908,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":800000,
         "name":"int_purcsca",
         "id":5909,
         "type":"PRODUCT_SEGMENT"
      },
      {
         "userCount":0,
         "name":"CHURN-PREDICT-SEGMENT",
         "id":5936,
         "type":"PREDICT_SEGMENT"
      },
      {
         "userCount":0,
         "name":"SPEND-PREDICT-SEGMENT",
         "id":5937,
         "type":"PREDICT_SEGMENT"
      },
      {
         "userCount":57,
         "name":"ttt_111",
         "id":5959,
         "type":"STANDARD"
      }
   ]
}

Get Segment Users

curl --location 'https://restapi.netmera.com/rest/3.0/getSegmentUsers?id=' \
--header 'X-netmera-api-key: your_rest_api_key' \
--header 'Content-Type: application/json' \
--header 'X-netmera-os: IOS'

Parameters

Id (Required): Segment Id. You can try one of the id's in the response returned with getSegments API. max (Optional) : Default value is 100. Maximum number of user info to fetch per page. Even if a value less than 100 is entered, it returns 100 users. You cannot enter a value greater than 1000. offset (Optional) : Default value is 0. Offset to start fetch from. Normally, for initially request, you don't need to send max or offset value. In response, you will a have link to fetch next page.

Sample Response

{
  "name": "name",
  "list": [
    {
      "externalId": "exid",
      "msisdn": "msisdn",
      "email": "[e-mail]"
    }
  ]
}

Push Approval

The Push Approval request allows you to approve push notifications before they are sent.

curl --location 'https://restapi.netmera.com/rest/3.0/sendPushApproval' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "messageId": 0
    }
  ]'

Email Opt-In Opt-Out Management

Enable Email:

curl --location 'https://restapi.netmera.com/rest/3.0/enableMail' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extIds": [
      "your_xid_id"
    ]
    // Or you can use email variable to change email permission
    /* 
    "emailList": [
      "your-email"
    ]
    */
  }'

Disable Email:

curl --location 'https://restapi.netmera.com/rest/3.0/disableMail' \
  --header 'X-netmera-api-key: your_rest_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extIds": [
      "your_xid_id"
    ]
    // Or you can use email variable to change email permission
    /* 
    "emailList": [
      "your-email"
    ]
    */
  }'

Update Email Information

You may update the email information for a user when we have their XID.

curl --location 'https://restapi.netmera.com/rest/3.0/updateEmail'
--header 'Content-Type: application/json'
--header 'X-netmera-api-key: your-api-key'
--data '{
"extId":"your ex id",
"email":"your your email"
}'

SMS Opt-In Opt-Out Management

Enable SMS:

curl --location 'https://restapi.netmera.com/rest/3.0/enableSms' \
  --header 'X-netmera-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extIds": [
      "your-extId"
    ] 
    // Or you can use MSISDN variable to change Sms Permission
    /* 
    "msisdnList": [
      "your-msisdn"
    ]
    */
  }'

Disable SMS:

curl --location 'https://restapi.netmera.com/rest/3.0/disableSms' \
  --header 'X-netmera-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "extIds": [
      "your-extId"
    ] 
    // Or you can use MSISDN variable to change Sms Permission
    /* 
    "msisdnList": [
      "your-msisdn"
    ]
    */
  }'

Update MSISDN Information

You may update the MSISDN information for a user based on their XID.

curl --location 'https://restapi.netmera.com/rest/3.0/updateMsisdn' \
  --header 'Content-Type: application/json' \
  --header 'X-netmera-api-key: your-api-key' \
  --data '{
    "extId": "your ex id",
    "msisdn": "your your msidin"
  }'