Managing user custom data

The REST API allows you to store name-value pairs as custom data for the currently logged in user. These could be user preferences, user info, or whatever you want. The values can be simple types like integers, booleans, or strings. They can also be objects in JSON format. If you need to access custom data for other users (not just the currently logged in user), you should use system/user?related=user_custom_by_user_id. The rest of this wiki page assumes you are operating on custom data for the currently logged in user.

To add custom data to the current user you POST the name-value pairs to /user/custom. They must be elements of an array named 'resource'.

POST /api/v2/user/custom

{
	"resource": [{
		"name": "background_color",
		"value": "white"
	}, {
		"name": "text_color",
		"value": "black"
	}, {
		"name": "some_json_data",
		"value": {
			"field1": "value1",
			"field2": "value2"
		}
	}]
}

To retrieve all custom data for the current user use GET /user/custom.

GET /api/v2/user/custom

{
	"resource": [{
		"name": "background_color",
		"value": "white",
		"created_date": "2016-09-20 13:45:05",
		"last_modified_date": "2016-09-20 13:45:05"
	}, {
		"name": "text_color",
		"value": "black",
		"created_date": "2016-09-20 13:45:05",
		"last_modified_date": "2016-09-20 13:45:05"
	}, {
		"name": "some_json_data",
		"value": {
			"field1": "value1",
			"field2": "value2"
		},
		"created_date": "2016-09-20 13:45:05",
		"last_modified_date": "2016-09-20 13:45:05"
	}]
}

To modify custom data you can POST the updated or new name-value pairs to /user/custom. If the name already exists, the value will be updated. If the name does not exist, a new name-value pair will be created.

POST /api/v2/user/custom

{
	"resource": [{
		"name": "background_color",
		"value": "red"
	}]
}

To retrieve a single value you can include the name in the URL as the identifier. It returns only the value.

GET /api/v2/user/custom/background_color

"red"

To modify a single value you can include the name in the URL as the identifier. The payload is the value in JSON format.

PATCH /api/v2/user/custom/background_color

{
	"value": "green"
}

To delete a single name-value pair you can include the name in the URL as the identifier.

DELETE /api/v2/user/custom/background_color