User APIs

1. 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.

1.1. Request

URI

POST /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"
  }
}

1.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
  }
}

2. Retrieve a User

This API is used to retrieve an existing Content User.

2.1. Request

URI

GET /content/user/{contentUserId}

Table 5. Request Parameters

contentUserId [UUID] Required

The Id of the Content User to retrieve.

2.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
  }
}

3. Update a User

This API is used to update an existing Content User.

3.1. Request

URI

PUT /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"
  }
}

3.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.

4. 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

4.1. Request

URI

DELETE /content/user/{contentUserId}

Table 12. Request Parameters

contentUserId [UUID] Required

The Id of the Content User to delete.

4.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.

5. 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".

5.1. Request

URI

POST /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 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"
  }
}

5.2. Response

include::docs/3.x/tech/apis/_standard-post-response-codes.adoc[]