2317: Update entity preferences for group

Owned by Nick Jensen
Last updated: Jul 10, 2018Version comment
1 min read

Update entity preference subscription status for all preferences in a group

Endpoint ID:2317
Method:

PUT

URL:

/preferences/entity/id/{entityID}/group/{groupID}

/preferences/entity/ext-key/{ext-key}/{ext-type}/group/{groupID}


entityIDRubiq master ID that uniquely identifies the entity

ext-keyExternal key that uniquely identifies the entity

ext-typeType of external key

groupIDA GUID string identifier for the group
Request body:

A JSON object containing the following propertes:

optOutReason The reason string which will be set for any preferences which are being opted-out of

preferences Optional: An array of preferenceIDs.

{
    "preferences": [
        "7a6776a3-9411-4d34-9866-99aa9ac7cc27",
        "dd9eaf78-18ff-44ea-9717-25b103060643"
    ],
    "optOutReason": "No longer interested"
}

The entity will be opted-in to any preferences in the preferences array.

The entity will be opted-out of any preferences in the group which are not in the preferences array.

If there is no preferences array in the request, then the entity will be opted-in to ALL group preferences.

There is an important difference between an empty preferences array and no preferences array. An empty array "preferences": [] means that the entity will be opted-out of all group preferences. Whereas excluding the preferences array entirely from the request means that the entity will be opted-in to all group references.

All preferences in preferences must be valid preferenceIDs belonging to this preference group. Any non-existant preference or preference not belonging to this group will cause a 404 (sub-code 404.4) response, with error message:

  Preference "preferenceID" not found

Response body:

None

Status codes:204OK

404

The entity or preference were not found.

The following sub codes may be returned:

404.1 Entity not found

404.2 External entity reference not found

404.4 Preference "preferenceID" not found

404.5 Group not found