Organisations

The various API methods for accessing organisation information.

Get an organisation

All authenticated Hail users can view the public information of an organisation. Owners have slightly more detail, including the date the organisation was created.

Endpoint

GET v1/organisations/{id}

Response Codes

200 OK	The request was successful

Response Body

All authenticated users will see the the following fields:

field	type	description
id	string	The unique identifier of the organisation
name	string	A name for the organisation
slug	string	The URL slug for the organisation
email	string	An email address for the public to contact the organisation
website_url	string	The URL to the organisation's website
facebook_url	string	The URL to the organisation's Facebook page
twitter_username	string	The organisation's Twitter username / handle. Omit the leading @ symbol.
youtube_url	string	The URL to the organisation's YouTube channel
google_url	string	The URL to the organisation's Google+ page
privacy_policy_url	string	The URL to the organisation's privacy policy
terms_url	string	The URL to the organisation's terms and conditions
avatar_url	string	The URL to the organisation's 500x500 avatar
small_avatar_url	string	The URL to the organisation's 75x75 avatar
country*	object	The country where the organisation is based. See the Countries documentation
is_suspended*	boolean	Whether the organisation is suspended or not
active_subscription*	boolean	Whether the organisation's subscription is active or not. If not, only billing resources will be available to the organisation owner to activate the subscription by paying overdue invoices
active_credit_card*	boolean	Whether the organisation has a working credit card
created_date*	string	The date (in format YYYY-MM-DD HH:MM:SS) the organisation was created

^*These fields are only available to members of the organisation.

Example Response Body

{
    "id": "q74kfel",
    "name": "Logan Park High School",
    "email": "office@lphs.school.nz",
    "website_url": "http:\/\/www.lphs.school.nz",
    "facebook_url": "https:\/\/www.facebook.com\/LoganParkHighSchool",
    "twitter_url": null,
    "youtube_url": "https:\/\/www.youtube.com\/channel\/UC5BQzdjSQOyUDlkBkANwPwA",
    "google_url": null,
    "privacy_policy_url": "http:\/\/www.lphs.school.nz\/sites\/lphs.school.nz\/files\/documents\/LPHS%202013%20All%20Policies%20Manual%20-%20working%20documentV5_0.pdf",
    "terms_url": null,
    "avatar_url": null,
    "small_avatar_url": null,
    "country": {
        "id": "NZ",
        "name": "New Zealand",
        "currency": "NZD"
    },
    "is_suspended": false,
    "active_subscription": true,
    "active_credit_card": true,
    "created_date": "2014-04-01 02:25:36"
}

Get an organisation's stats

Endpoint

GET v1/organisations/{id}/stats

Response Codes

200 OK	Organisation updated successfully
403 Not Authorised	The user is not a member of the organisation

Response Body

field	type	description
maximum_allowed_members	number	The maximum number of members allowed in the organisation, given the plan currently subscribed to
member_count	number	The current number of members in the organisation
invite_count	number	The number of outstanding invitations in the organisation

Create an organisation

Any user of Hail is able to create an organisation.

Endpoint

POST v1/organisations

Request Body

field	required	field	description
name	yes	string	The name for the organisation
plan_id	yes	string	The ID of the plan to subscribe to on creation
country_id	no	string	The ID of the country the organisation is based in, for billing purposes. We will automatically detect it if omitted.
email	no	string	The public email address for the organisation
website_url	no	string	The URL to the organisation's website
facebook_url	no	string	The URL to the organisation's Facebook page
twitter_username	no	string	The organisation's Twitter username / handle. Omit the @ symbol
youtube_url	no	string	The URL to the organisation's YouTube channel
google_url	no	string	The URL to the organisation's Google+ page
privacy_policy_url	no	string	The URL to the organisation's privacy policy
terms_url	no	string	The URL to the organisation's terms and conditions

Example Request Body

{
    "name": "School of Hard Knocks",
    "plan_id": "flock",
    "country_id": "NZ",
    "email": "office@hardknocks.school.nz",
    "website_url": "http:\/\/www.hardknocks.school.nz",
    "facebook_url": "https:\/\/www.facebook.com\/SchoolOfHardKnocks",
    "twitter_url": null,
    "youtube_url": "https:\/\/www.youtube.com\/channel\/bC5rQzdjSrOyUDlkBkANwPzZ",
    "google_url": null,
    "privacy_policy_url": "http:\/\/www.hardknocks.school.nz\/policy.pdf",
    "terms_url": null
}

Response Codes

201 Created	Organisation created successfully
400 Bad Request	Validation of the provided data failed

Response Body

The newly created organisation. See "Get an organisation" for fields and example body.

Edit an organisation

Owners can edit their organisations

Endpoint

PUT v1/organisations/{id}

Request Body

Same request body as for creating an organisation, except no plan_id field is accepted. A different endpoint is provided for changing subscriptions.

Response Codes

200 OK	Organisation updated successfully
403 Not Authorised	The authenticated user is not the owner of the organisation
400 Bad Request	Validation of the provided data failed

Response Body

The updated entity. Same fields as when creating an organisation.

Change organisation's slug

Owners can change their organisation's slug, which forms their 'Hail address'.

Endpoint

PUT v1/organisations/{id}/slug

Request Body

field	required	type	description
text	yes	string	The new slug

Example Request Body

{
    "text": "elephant-party"
}

Response Codes

200 OK	Slug updated successfully
400 Bad Request	The slug is not the correct format
403 Not Authorised	Not allowed to use that slug, or you aren't the owner of the organisation

Response Body

The updated organisation object.

Change organisation's avatar

Owners can change their organisation's avatar.

Endpoint

POST v1/organisations/{id}/avatar

Request Body

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

Response Codes

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

Response Body

The updated user object.

Delete an organisation's avatar

Owners can delete their organisation's avatar.

Endpoint

DELETE v1/organisations/{id}/avatar

Response Codes

204 No Content	Avatar deleted successfully.
403 Not Authorised	The authenticated user is not the owner of the organisation

List an organisation's notifications

Endpoint

GET v1/organisations/{id}/notifications

Response Codes

200 OK	Notifications listed successfully
403 Not Authorised	The user is not a member of the organisation

Response Body

An array of notifications. Notifications are identical to inbox messages for a user, however they aren't scoped to any user in particular.

Invite a user to the organisation

Owners and Admins are able to invite users of any permission role within the set Admin, Publisher, Contributor. Publishers can invite users of the Contributor role only. Contributors cannot invite other members.

Endpoint

POST v1/organisations/{id}/invitations

Request Body

field	required	type	description
name	required	string	The name of the person you're inviting
email	required	string	The email address of the person you're inviting
role	required	string	The role the person will take on in the organisation, either admin, curator or contributor

Example Request Body

{
    "name": "Hailey",
    "email": "hailey.the.pidgeon@hardknocks.school.nz",
    "role": "contributor"
}

Response Codes

201 Created	The invitation was created and sent successfully
403 Not Authorised	You aren't allowed to invite for that role in this organisation

Note that when the invitation is created, there will be a null body in the response.

List invites issued in an organisation

Endpoint

GET v1/organisations/{id}/invitations

Response Codes

200 OK	Listed the invitations successfully
403 Not Authorised	Not allowed to list invitations in the organisation

Response Body

An array of invitations. An invitation consists of:

field	type	description
id	string	The unique ID of the invitation
name	string	The name of the person invited
email	string	The email address of the person invited
role	string	The role the person was invited for, either admin, curator(Publisher) or contributor
inviter	object	The member who invited the person
last_resend_date	string	The date the invitation was last sent
created_date	string	The date the invitation was created / first sent

Get a member in an organisation

Endpoint

GET v1/organisations/{organisation_id}/members/{member_id}

Response Codes

200 OK	The request was successful
403 Not Authorised	Not a member of the organisation

Response Body

A user who is a member of the organisation, with an added role field for their role in the organisation, which will be one of:

• owner
• admin
• curator (referred to as Publisher with the Hail app)
• contributor

There can only be one owner of an organisation at a time.

Example Response Body

{
    "id": "iu34cvq",
    "first_name": "Ova",
    "last_name": "Zulauf",
    "avatar_url": "http://lorempixel.com/150/150/",
    "role": "curator"
}

List members in an organisation

Get all members in the organisation, including their role.

Endpoint

GET v1/organisations/{id}/members

Response Codes

Same as when getting one particular member, see above.

Response Body

An array of members with their roles.

Example Response Body

[
    {
        "id": "iu34cvq",
        "first_name": "Ova",
        "last_name": "Zulauf",
        "avatar_url": "http:\/\/lorempixel.com\/150\/150\/",
        "last_active_date": "2014-04-05 01:02:03",
        "role": "admin"
    },
    {
        "id": "tr34cRq",
        "first_name": "Ben",
        "last_name": "Dawson",
        "avatar_url": "http:\/\/lorempixel.com\/150\/150\/",
        "last_active_date": "2014-04-05 02:03:04",
        "role": "owner"
    }
]

Changing role of organisation members

Owners are able to change the role of any user in the organisation. The can promote or demote users, and set the owner of the organisation. All of these are facilitated by updating the membership to the organisation.

Endpoint

PUT v1/organisations/{organisation_id}/members/{member_id}

Request Body

field	required	type	description
role	yes	string	The new role for the member, either owner, admin, curator, or contributor

Example Request Body

{
    "role": "admin"
}

Response Codes

200 OK	Successfully changed the member's role
400 Bad Request	An invalid role change request was proposed
403 Not Authorised	The requester is not authorised to make that role change

Response Body

The updated membership, same as when getting a user in an organisation, see above.

Removing a member from an organisation

Used for users in power to remove other members, or for members to remove themselves.

Endpoint

DELETE v1/organisations/{organisation_id}/members/{member_id}

Response Codes

204 No Content	The member was successfully removed
403 Not Authorised	Not allowed to remove that member
400 Bad Request	The owner trying to remove themselves before reassigning ownership

Archive an organisation

Archiving an organisation pulls all content offline, removes all members, and marks the organisation as inactive.

Endpoint

DELETE v1/organisations/{id}

Request Body

field	required	type	description
reason	no	string	The reason for archiving

Example Request Body

{
   "reason": "It doesn't cost enough! You should have charged more!"
}

Response Codes

204 No Content	The organisation was archived successfully
403 Not Authorised	You aren't the owner of the organisation