Set user metadata

Sets metadata for the specified UUID. Returns the updated UUID object, optionally including custom properties.

Note:

  • You can change all of the UUID object's properties except its identifier.
  • Invalid property names are silently ignored and will not cause a request to fail.
  • If you set the custom property, you must completely replace it since partial updates are not supported.
  • The custom object can only contain scalar values.
Path Parameters
sub_key string — REQUIRED

Your app's subscribe key from Admin Portal.

uuid string — REQUIRED

A UTF-8 encoded string of up to 64 characters used to identify the client. Must not be empty and can contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

Query Parameters
include string[]

Possible values: [custom, type, status]

List of additional/complex UUID metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.

auth string

String which is either the auth key (PAM v2) or a valid token (Access Manager) used to authorize the operation if access control is enabled. Authorization token with permissions to perform the request.

signature string

Signature used to verify that the request was signed with the secret key associated with the subscribe key.

If Access Manager is enabled, either a valid authorization token or a signature are required. Check Access Manager documentation for details on how to compute the signature.

timestamp integer

Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 seconds offset from NTP. Required if signature parameter is supplied.

Request Body — REQUIRED

JSON object with UUID metadata to set.

name string

Possible values: 1 ≤ length

Name of the UUID. Must not be empty or consist only of whitespace characters.

externalId string

UUID's identifier in an external system.

profileUrl uri

URL for the UUID's profile picture. Syntax is as defined in RFC 3986.

email email

The UUID's email address. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).

type string

User type.

status string

User status.

custom object

JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

Responses
200

Successfully set UUID metadata.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

data object — OPTIONAL

Object with UUID metadata used in responses.

id string — OPTIONAL

Possible values: 1 ≤ length ≤ 92

A UTF-8 encoded string of up to 64 characters used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.

Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.

updated date-time — OPTIONAL

Date and time the object was last updated.

eTag string — OPTIONAL

The object's content fingerprint used in conditional requests.

name string — OPTIONAL

Possible values: 1 ≤ length

Name of the UUID. Must not be empty or consist only of whitespace characters.

externalId string — OPTIONAL

UUID's identifier in an external system.

profileUrl uri — OPTIONAL

URL for the UUID's profile picture. Syntax is as defined in RFC 3986.

email email — OPTIONAL

The UUID's email address. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).

type string — OPTIONAL

User type.

status string — OPTIONAL

User status.

custom object — OPTIONAL

JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.

400

The request body contains invalid data.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

403

Disabled - The subscribe key doesn't have App Context API enabled.

Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

412

Conditional operation cannot be performed because the target resource has changed since the last retrieval.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

429

Request rate limit exceeded.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

500

An internal server error occurred.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]

503

Request processing exceeded the maximum allowed time.

Schema — OPTIONAL
status integer — OPTIONAL

HTTP status code.

error object — OPTIONAL

Error response.

message string — OPTIONAL

User-facing error message.

source string — OPTIONAL

Possible values: [metadata, authz]

Internal source of the error.

details object[] — OPTIONAL
message string — OPTIONAL

A user-facing error message.

location string — OPTIONAL

Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.

locationType string — OPTIONAL

Possible values: [path, query, header, body]