User APIs

1. Overview

This page contains the APIs that are used to maintain or take action on users:

Create a User
Retrieve a User
Update a User
Delete a User
Flag a User

2. Create a User

This API is used to create a Content User. Some examples of when this API would be used:

A new user has registered with your application
You need to bulk import your existing users into CleanSpeak

Content Users are also automatically created when content is sent to the Moderation API if the user does not yet exist.

2.1. Request

URI (3.x, deprecated in 4.0.0)

POST /content/user/{contentUserId}

URI (4.x)

POST /api/content/user/{contentUserId}

Table 1. Request Parameters
contentUserId [UUID] Required	The Id of the Content User to create.

Table 2. Request Body
user [Object] Required	The Content User object.
user.applicationIds [Array<UUID>] Optional	The applications identifiers assigned to this user.
user.attributes [Map<String, String>] Optional	The user attributes. This is a map of key value pairs of String, String.
user.birthDate [String] Optional	The birth date of the user. The format is yyyy-mm-dd
user.createInstant [Long] Optional defaults to now	The instant this user was created.
user.displayNames [Array<String>] Optional	The list of display names, or usernames for this content user.
user.email [String] Optional	The email address of the user.
user.imageURL [String] Optional	The image URL for the users avatar.
user.lastLoginInstant [Long] Optional	The instant this user last logged in.
user.name [String] Optional	The name of the user.
user.preferredLanguages [Array<String>] Optional	A list of languages this user prefers, ordered from most preferred to least. This is used in generating events and emails that are localized for the user. See Locales.
user.score [Integer] Optional defaults to 0	The user’s score.

Example Request JSON

{
  "user": {
    "score": 0,
    "attributes": {
      "Help Desk ID": "13"
    },
    "createInstant": 1473178111759,
    "email": "jsmith@example.com",
    "name": "John Smith",
    "imageURL": "http://www.avatarsdb.com/avatars/yoda_star_wars.gif",
    "displayNames": [
      "mr_smith"
    ],
    "birthDate": "1989-02-14"
  }
}

2.2. Response

Table 3. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 4. Response Body
user [Object]	The Content User object.
user.id [UUID]	The Id of the user.
user.applicationIds [Array<UUID>]	The applications identifiers assigned to this user.
user.attributes [Map<String, String>]	The user attributes. This is a map of key value pairs of String, String.
user.birthDate [String]	The birth date of the user. The format is yyyy-mm-dd
user.checkOutUser [Object] Deprecated	The CleanSpeak System User that currently has this user checked out.
user.checkOutUserId [UUID] Available Since 3.4.11	The CleanSpeak System User Id that currently has this user checked out.
user.checkoutInstant [Long]	If the user is currently checked out to a CleanSpeak System User, this is the The instant this user was checked out.
user.createInstant [Long]	The instant this user was created.
user.displayNames [Array<String>]	The list of display names, or usernames for this content user.
user.email [String]	The email address of the user.
user.imageURL [String]	The image URL for the users avatar.
user.lastLoginInstant [Long]	The instant this user last logged in.
user.name [String]	The name of the user.
user.preferredLanguages [Array<String>]	A list of languages this user prefers, ordered from most preferred to least. This is used in generating events and emails that are localized for the user. See Locales.
user.score [Integer]	The user’s score.

Example Response JSON

{
  "user": {
    "score": 0,
    "attributes": {
      "Help Desk ID": "13"
    },
    "createInstant": 1473178111759,
    "email": "jsmith@example.com",
    "name": "John Smith",
    "id": "3044fae2-575b-492a-b5da-0216644559a1",
    "imageURL": "http://www.avatarsdb.com/avatars/yoda_star_wars.gif",
    "displayNames": [
      "mr_smith"
    ],
    "birthDate": "1989-02-14",
    "lastLoginInstant": 1474300531759
  }
}

3. Retrieve a User

This API is used to retrieve an existing Content User.

3.1. Request

URI (3.x, deprecated in 4.0.0)

GET /content/user/{contentUserId}

URI (4.x)

GET /api/content/user/{contentUserId}

Table 5. Request Parameters
contentUserId [UUID] Required	The Id of the Content User to retrieve.

3.2. Response

Table 6. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 7. Response Body
user [Object]	The Content User object.
user.id [UUID]	The Id of the user.
user.applicationIds [Array<UUID>]	The applications identifiers assigned to this user.
user.attributes [Map<String, String>]	The user attributes. This is a map of key value pairs of String, String.
user.birthDate [String]	The birth date of the user. The format is yyyy-mm-dd
user.checkOutUser [Object] Deprecated	The CleanSpeak System User that currently has this user checked out.
user.checkOutUserId [UUID] Available Since 3.4.11	The CleanSpeak System User Id that currently has this user checked out.
user.checkoutInstant [Long]	If the user is currently checked out to a CleanSpeak System User, this is the The instant this user was checked out.
user.createInstant [Long]	The instant this user was created.
user.displayNames [Array<String>]	The list of display names, or usernames for this content user.
user.email [String]	The email address of the user.
user.imageURL [String]	The image URL for the users avatar.
user.lastLoginInstant [Long]	The instant this user last logged in.
user.name [String]	The name of the user.
user.preferredLanguages [Array<String>]	A list of languages this user prefers, ordered from most preferred to least. This is used in generating events and emails that are localized for the user. See Locales.
user.score [Integer]	The user’s score.

Example Response JSON

{
  "user": {
    "score": 0,
    "attributes": {
      "Help Desk ID": "13"
    },
    "createInstant": 1473178111759,
    "checkOutInstant": 1474664616928,
    "checkOutUserId": "c4be9117-8cb9-46bb-b805-0f0e612cd0c6",
    "email": "jsmith@example.com",
    "name": "John Smith",
    "id": "3044fae2-575b-492a-b5da-0216644559a1",
    "imageURL": "http://www.avatarsdb.com/avatars/yoda_star_wars.gif",
    "displayNames": [
      "mr_smith"
    ],
    "birthDate": "1989-02-14",
    "lastLoginInstant": 1474300531759
  }
}

4. Update a User

This API is used to update an existing Content User.

4.1. Request

URI (3.x, deprecated in 4.0.0)

PUT /content/user/{contentUserId}

URI (4.x)

PUT /api/content/user/{contentUserId}

Table 8. Request Parameters
contentUserId [UUID] Required	The Id of the Content User to update.

Table 9. Request Body
user [Object] Required	The Content User object.
user.applicationIds [Array<UUID>] Optional	The applications identifiers assigned to this user.
user.attributes [Map<String, String>] Optional	The user attributes. This is a map of key value pairs of String, String.
user.birthDate [String] Optional	The birth date of the user. The format is yyyy-mm-dd
user.displayNames [Array<String>] Optional	The list of display names, or usernames for this content user.
user.email [String] Optional	The email address of the user.
user.imageURL [String] Optional	The image URL for the users avatar.
user.lastLoginInstant [Long] Optional	The instant this user last logged in.
user.name [String] Optional	The name of the user.
user.preferredLanguages [Array<String>] Optional	A list of languages this user prefers, ordered from most preferred to least. This is used in generating events and emails that are localized for the user. See Locales.
user.score [Integer] Optional defaults to 0	The user’s score.

Example Request JSON

{
  "user": {
    "score": 0,
    "attributes": {
      "Help Desk ID": "13"
    },
    "createInstant": 1473178111759,
    "email": "jsmith@example.com",
    "name": "John Smith",
    "imageURL": "http://www.avatarsdb.com/avatars/yoda_star_wars.gif",
    "displayNames": [
      "mr_smith"
    ],
    "birthDate": "1989-02-14"
  }
}

4.2. Response

Table 10. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to update doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 11. Response Body
user [Object]	The Content User object.
user.id [UUID]	The Id of the user.
user.applicationIds [Array<UUID>]	The applications identifiers assigned to this user.
user.attributes [Map<String, String>]	The user attributes. This is a map of key value pairs of String, String.
user.birthDate [String]	The birth date of the user. The format is yyyy-mm-dd
user.checkOutUser [Object] Deprecated	The CleanSpeak System User that currently has this user checked out.
user.checkOutUserId [UUID] Available Since 3.4.11	The CleanSpeak System User Id that currently has this user checked out.
user.checkoutInstant [Long]	If the user is currently checked out to a CleanSpeak System User, this is the The instant this user was checked out.
user.createInstant [Long]	The instant this user was created.
user.displayNames [Array<String>]	The list of display names, or usernames for this content user.
user.email [String]	The email address of the user.
user.imageURL [String]	The image URL for the users avatar.
user.lastLoginInstant [Long]	The instant this user last logged in.
user.name [String]	The name of the user.
user.preferredLanguages [Array<String>]	A list of languages this user prefers, ordered from most preferred to least. This is used in generating events and emails that are localized for the user. See Locales.
user.score [Integer]	The user’s score.

5. Delete a User

This API is used to delete an existing Content User. This API does not delete CleanSpeak Users (moderators). When a Content User is deleted the content for this user is also deleted.

This might be necessary for COPPA compliance, or just to ensure that a user’s information is completely removed. However, it is usually a good idea to keep user information in CleanSpeak even if they have closed or deleted their account in your system. Some cases where you should use this API are:

A user deletes their account
A user or the parent of a user requests their account information to be deleted

5.1. Request

URI (3.x, deprecated in 4.0.0)

DELETE /content/user/{contentUserId}

URI (4.x)

DELETE /api/content/user/{contentUserId}

Table 12. Request Parameters
contentUserId [UUID] Required	The Id of the Content User to delete.

5.2. Response

Table 13. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid `Authorization` header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

6. Flag a User

This API is used to flag a Content User. Once a user has been flagged they will be queued for a moderator to review in the User Alert queue.

For example, a user may flag or report another user. In most forums and games, players have the option to report other players for various reasons such as "the user is being offensive" or "the user is bullying me".

6.1. Request

URI (3.x, deprecated in 4.0.0)

POST /content/user/flag/{contentUserId}

URI (4.x)

POST /api/content/user/flag/{contentUserId}

Table 14. Request Parameters
contentUserId [UUID] Required	The Id of the Content User to be flagged.

Table 15. Request Body
flag [Object] Required	The flag object.
flag.applicationId [String] Required	The Id of the application the flag was sent from. For example if the user flag originated from your chat application, you would specify the Id of the CleanSpeak application being used for your chat content.
flag.comment [String] Optional	An optional description to provide additional details for the reason the content user was flagged.
flag.createInstant [Long] Required	The instants the flag event occurred.
flag.reason [String] Optional	A free-form text field that can be used to indicate the reason the content user was flagged. For example, you may use reasons such as `abuse`, `bullying`, `grooming`, `spam` or `threatening`.
flag.reporterId [UUID] Required	The Id of the reporting user.

Example Request JSON

{
  "flag": {
    "applicationId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "comment": "this user keeps cheating",
    "createInstant": 1474496312000,
    "reason": "cheating",
    "reporterId": "91303ce2-ee40-48e7-98dc-354c051d0b78"
  }
}

6.2. Response

Table 16. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
402	Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.