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 | |
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 |
contact.twitter | the user's twitter handle | |
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 |