User

The user object represents a unique user on the platform. A user must be registered and authenticated by clicking on a confirmation email sent to the email address provided. No access to the platform is granted before successful confirmation.

A user object contains the following fields:

Name Field Description
accountId the user's account id. Used to id the user through the application especially with regards to contacts/ assigned tasks
email contact.email valid email address
title contact.title the user's title. Valid options are: Mr., Mrs., Ms.
firstName contact.firstName the user's first name
lastName contact.lastName the user's last name
company contact.company the user's company
address1 contact.address1 the user's address - line 1
address2 contact.address2 the user's address - line 2
city contact.city the user's city
zip contact.zip the user's zip code
country contact.country the ISO 8601 country code of the user
region contact.region applicable only for USA users. In the format of "us-ca" for California
location contact.location this is the public location of the user and is shown on their profile page
displayName contact.displayName the user's display name. This is used when publishing templates or reviews
timezone contact.timezone the timezone offset as per ISO 8601
language contact.language the user's default language (locale)
url the user's url. This is used when publishing templates or reviews to denote the user's profile url
avatar the user's picture url (avatar).
profile contact.profile the user's profile. This is used when publishing templates or reviews and includes free text about the user
hiddenProfile contact.hiddenProfile for users who wish to hide their public profile. True/ false values
twitter contact.twitter the user's twitter handle
facebook contact.facebook the user's facebook page
gender contact.gender the user's gender: m (male) / f (female)
settings settings.* the user's application settings in a key/value format
customs customs.* the user's custom settings. These can be used by 3rd party applications using the API
settings.dailyReminderTime the default time of day on which daily reminders should be sent. In the format of HH:mm (e.g. 08:00)

Note: in the above table, the field column refers to the field name to be used when trying to update the user's fields as described in the methods: getField & updateField.

 

Sample User XML

<user>
  <email>[email protected]</email>
  <title>Mr.</title>
  <firstName>Joe</firstName>
  <lastName>Smith</lastName>
  <company>Microsoft</company>
  <address1>200. Microsoft way.</address1>
  <address2>Entrance C.</address2>
  <city>Redmond</city>
  <zip>Smith</zip>
  <country>us</country>
  <displayName>JohnSmith</displayName>
  <timezone>Europe/Amsterdam</timezone>
  <language>en</language>
  <url>http://checklist.com/channels/google</url>
  <profile>this is my public profile</profile>
  <hiddenProfile>false</hiddenProfile>
  <avatar>http://media.checklist.com/channels/pictures/5432fsagds.png</avatar>
  <twitter>microsoft</twitter>
  <facebook>microsoft</facebook>
  <gender>m</gender>
  <settings>
    <settings.notify>via email</settings.notify>
    <settings.notify>via sms</settings.notify>
  </settings>
  <custom>
    <custom.memorial>off</custom.memorial>
    <custom.location>on the run</custom.location>
  </custom>
</user>

Supported methods

Get User

Method get
Description get the user object for the currently logged user
URL https://api.checklist.com/rest/v1/users/get [GET]
Authentication Required
Parameters
Response the user object is returned
Errors 401UnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
Throttling normal

Update Password

Method updatePassword
Description update the user's password
URL https://api.checklist.com/rest/v1/users/updatePassword?currentPassword={current_password}&password={new_password} [PUT]
Authentication Required
Parameters currentPasswordthe current password
newPasswordthe new password
Response 200
Errors 401UnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
400Invalid Parameters - returned if provided password is invalid (Length > 5 characters)
Throttling normal

Get Field

Method field
Description Returns a user's field value. This is used when a specific field value is required. Otherwise, use the get User object. Fields can have the following scopes: contact, application setting or custom fields.
URL https://api.checklist.com/rest/v1/users/field/{scope.fieldName} [GET]
Authentication Required
Parameters fieldNamethe request field. Names must start with scope (contact, settings or custom) followed by a dot. Cannot be longer than 100 chars and is case insensitive.
Response Field Value
Errors 401UnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
400Invalid Field - returned if provided field name is invalid (does not exist)
Throttling normal

Update Field

Method update
Description Updates a user's field value.
URL https://api.checklist.com/rest/v1/users/field/{scope.fieldName}?value={fieldValue} [PUT]
Authentication Required
Parameters fieldNamethe field name to be changed. Names must start with scope (contact, settings or custom)followed by a dot and the actual field name. Cannot be longer than 100 chars and is case insensitive.
fieldValuethe value to update the field with in string format. Cannot be longer than 5000 chars
Response 200
Errors 401UnAuthorizedUnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
400Invalid Field - returned if provided field name is invalid (does not exist)
400Invalid Parameters - returned if provided field value is invalid (see examples above as in add user)
Throttling normal

Search

Method search
Description Allows user to search within his account. Results retuned may include: tasks, checklist templates, checklist categories and shortly user contacts
URL https://api.checklist.com/rest/v1/users/search?q={query} [GET]
Authentication Required
Parameters qThe search query
langoptional language. Defaults to en (English)
Response The search results.
Errors 401UnAuthorized - returned if not authorized to perform this action or user already has a display name
400

Is Display Name Available

Method available
Description Checks to see if a display name is available to be selected by a user. Note: this method will only return results to users who have not yet selected a display name. A display name must be alphanumeric/ spaces and between 5 and 25 chars long. No leading or trailing spaces.
URL https://api.checklist.com/rest/v1/users/available?displayName={displayName} [GET]
Authentication Required
Parameters displayNamethe display name the user wants to check availability for
Response 200
Errors 401UnAuthorized - returned if not authorized to perform this action or user already has a display name
400

Set Avatar

Method setAvatar
Description Uploads the user's picture (avatar). If a picture already exists it will be overwritten. The following limitations apply: max size 700 kb and type: jpg, png, bmp or gif. A picture should have the ratio of 1:1 and preferably the size of 64×64 px.
URL https://api.checklist.com/rest/v1/users/avatar [POST]
Authentication Required
Parameters filepassed in the body of the request
Response 200The url where the image is available
Errors 401UnAuthorized - returned if not authorized to perform this action.
Throttling normal

Delete Avatar

Method deleteAvatar
Description Removes the user's avatar.
URL https://api.checklist.com/rest/v1/users/avatar [DELETE]
Authentication Required
Parameters
Response 200OK
Errors 401UnAuthorized - returned if not authorized to perform this action.
Throttling normal

Send Message

Method sendMessage
Description send a message via checklist.com. This is typically used to get help via Email functionality.
URL https://api.checklist.com/rest/v1/users/sendMessage?emails={email1,email2}&message={message} [POST]
Authentication Required
Parameters emailscomma separated list of email addresses to which the message should be sent. A maximum of 5 addresses are allowed
messagethe message body to be sent. Cannot be longer than 500 chars
Response 200
Errors 401UnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
Throttling a maximum of 10 emails per hour is permitted.

Close account

Method close
Description close the user's account
URL https://api.checklist.com/rest/v1/users/close [DELETE]
Authentication Required
Parameters
Response 200
Errors 401UnAuthorized - returned if not authorized to perform this action. User can load itself, no other user.
Throttling normal