Introduction OAuth Users Organisations Tags Private Tags Articles Images Videos Publications

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

Curators and owners are able to invite users to join the organisation. Owners are allowed to invite both curators and contributors, but curators are only allowed to invite contributors.

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 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 curator 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
  • curator
  • 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": "curator"
    },
    {
        "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 users in the organisation. They can promote contributors to curators, demote curators to contributors, 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, curator, or contributor

Example Request Body

{
    "role": "curator"
}

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