EnglishUser
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 |