Users

The various API methods for accessing user information.

Me

Find out who the currently logged in user is, based off the access key you're authenticating with. Mainly useful for restoring state, i.e. finding out who the logged in user is without having to store their unique identifier.

Endpoint

GET v1/me

Response Codes

200 OK	Successfully retrieved the logged in user

Response Body

If the request is successful, the details of the currently logged in user will be returned as the response.

field	type	description
id	string	The unique identifier of the user
email	string	The user's email address
first_name	string	The user's first name
last_name	string	The user's last name
avatar_url	string	The URL to the user's square avatar
sign_up_date	string	The date (in format YYYY-MM-DD HH:MM:SS) when the user registered
last_active_date	string	The date (in format YYYY-MM-DD HH:MM:SS) when the user last used Hail
wants_organisation_emails	boolean	Whether the user wishes to receive organisation-related email notifications
wants_promotion_emails	boolean	Whether the user wishes to receive promotion emails from Hail

Example Response Body

{
    "id": "rp2x5yn",
    "email": "test@test.com",
    "first_name": "Buck",
    "last_name": "Robel",
    "avatar_url": "http:\/\/lorempixel.com\/150\/150\/",
    "sign_up_date": "2014-01-01 01:02:03",
    "last_active_date": "2014-01-02 04:43:33",
    "wants_organisation_emails": true,
    "wants_promotion_emails": true
}

Get a user

Get a user's information. If the user happens to be the currently logged in user, this call will mimmic that of v1/me above. If not, a subset of that information will be returned that is suitable for public access.

Endpoint

GET v1/users/{id}

Response Codes

200 OK	Successful request

Response Body

If the request was successful, and the user requested is the logged in user, the response body will be the same as v1/me above. If not, the subset will be returned:

field	type	description
id	string	The unique identifier of the user
first_name	string	The user's first name
last_name	string	The user's last name
avatar_url	string	The URL to the user's avatar
last_active_date	string	The date (in format YYYY-MM-DD HH:MM:SS) the user was last active

Example Response Body

The subset returned for when the logged in user is not the user being requested:

{
    "id": "rp2x5yn",
    "first_name": "Buck",
    "last_name": "Robel",
    "avatar_url": "http:\/\/lorempixel.com\/150\/150\/",
    "last_active_date": "1992-01-10 04:05:06"
}

Update a user

Allows a user to update their settings. You must be authenticated as the user under edit for the request to be authorised.

Endpoint

PUT v1/users/{id}

Request Body

field	required	type	description
first_name	no	string	The user's first name
last_name	no	string	The user's last name
password	no	string	The user's password
wants_organisation_emails	no	boolean	Whether the user wants organisation-related email notifications
wants_promotion_emails	no	boolean	Whether the user wants promotional emails from Hail

Note that a subset of these fields can be provided. But if you're going to provide a field, it needs to be valid.

Example Request Body

{
    "first_name": "Sheldon"
}

Response Codes

200 OK	User successfully updated
400 Bad Request	Validation of the provided data failed
403 Not Authorised	The authenticated user is not the user being edited

Response Body

The updated user entity, see the response to v1/me above.

Change a user's avatar

There is a separate endpoint for changing a user's avatar.

Endpoint

POST v1/users/{id}/avatar

Request Body

field	required	type	description
image	yes	file	The image for the user's avatar (jpeg, gif, or png)

Response Codes

200 OK	The image was updated successfully
400 Bad Request	Validation of the provided data failed
403 Not Authorised	The authenticated user is not the user being edited

Response Body

The same as when editing a user.

Delete a user's avatar

Users can delete their avatars.

Endpoint

DELETE v1/users/{id}/avatar

Response Codes

204 No Content	Avatar deleted successfully.
403 Not Authorised	The authenticated user is not the user being edited

Deactivate a user

Allows a user to deactivate their account. Once deactivated, all access keys will be revoked and no new keys will be issued. The user will remain a member of their respective organisations should they be re-activated.

Endpoint

DELETE v1/users/{id}

Request Body

field	required	type	description
reason	no	string	The reason for deactivating (string, optional)

Example Request Body

{
    "reason": "Tom made fun of me too much."
}

Response Codes

204 No Content	User deactivated successfully
403 Not Authorised	The authenticated user is not the user being deactivated

List a user's organisations

Endpoint

GET v1/users/{id}/organisations

Response Codes

200 OK	Listing was successful
403 Not Authorised	The requester isn't the user being queried

Response Body

An array of organisations, with an extra role field indicating the user's role in that organisation. See the Organisations documentation for the field list.

List items in a user's inbox for an organisation

Endpoint

GET v1/users/{id}/messages/organisation/{org_id}

Response Codes

200 OK	Listing was successful
403 Not Authorised	The requester isn't the user being queried

Response Body

An array of messages. A message consists of:

field	type	description
id	string	The unique identifier of the message
type	string	The event that occurred, e.g. ARTICLE_PUBLISH
from_actor	object	The user that triggered the event, can be null for system-generated events
user	object	The recipient user
organisation	object	The organisation the event occurred in
read	boolean	Whether the message has been read or not
created_date	string	The date the event occurred, in the format YYYY-MM-DD HH:MM:SS
data	object	Miscellaneous data about the event, which changes depending on the type of message

Count items in a user's inbox for an organisation

Endpoint

GET v1/users/{id}/messages/organisation/{org_id}/count

Response Codes

200 OK	The request was successful
403 Not Authorised	The requester isn't the user being queried

Response Body

field	type	description
count	number	The number of unread inbox messages

Example Response Body

{
    "count": 7
}

Read items in a user's inbox for an organisation

Marks all unread messages in the inbox as read.

Endpoint

DELETE v1/users/{id}/messages/organisation/{org_id}/unread

Response Codes

204 No Content	The inbox was read successfully
403 Not Authorised	The requester isn't the user being queried