Organisation

Organisation Object

Field	Type	Description
id	snowflake	the organisation's id
name	string	the organisation's name (2 - 100 characters)
description	string	a description of the organisation
location	string	the organisation's location
code	string	the organisation's code (max 12 characters)
default_branch_name	string	default branch name for documents
member_count	integer	number of members in the organisation
icon_hash	string	hash of the organisation's square icon file
banner_hash	string	hash of the organisation's banner file
logo_hash	string	hash of the organisation's logo file (used on printed documents)
storage_usage	integer	bytes of storage in use
created_at	ISO8601 timestamp	when the organisation was created
owned_by	object	the owner of the organisation (contains at minimum an id field)
is_protected	boolean	whether the organisation is protected against accidental deletion
is_verified	boolean	whether the organisation is a verified business
member_approval	boolean	whether all access requests require admin approval
restrict_email_domain	boolean	whether e-mail notifications are restricted to verified domains
is_deleted	boolean	whether the organisation is in a soft delete state
deleted_at	ISO8601 timestamp	when the organisation was deleted (if applicable)
deleted_by	object	who deleted the organisation (contains at minimum an id field)

Organisation Object (with subscriptions and permissions)

When returned with subscription and permission context, the organisation object includes additional fields:

Field	Type	Description
features	object	subscription features available to the organisation
permissions	item permissions	permission keys and their grant status for the current user
organisation_user	object	current user's membership information (see below)

Organisation User Object

Field	Type	Description
is_owner	boolean	whether the current user is the owner of the organisation
pending	boolean	whether the user's membership is pending approval
joined_at	ISO8601 timestamp	when the user joined the organisation
notification_email_id	string	id of the user's notification email

Organisation Object (partial)

When returned in a partial context, the organisation object only includes:

Field	Type	Description
id	snowflake	the organisation's id
name	string	the organisation's name
description	string	a description of the organisation
icon_hash	string	hash of the organisation's square icon file

Organisation Domain Object

Field	Type	Description
id	snowflake	the domain's id
organisation_id	snowflake	the organisation's id
domain	string	the domain name
challenge_token	string	DNS verification challenge token (only included when explicitly requested)
is_verified	boolean	whether the domain has been verified via DNS
is_approved	boolean	whether the domain has been approved

Organisation Member Object

Field	Type	Description
user	user object	the member (see Object or Id)
is_owner	boolean	whether the member is the owner of the organisation
pending	boolean	whether the member's membership is pending approval
joined_at	ISO8601 timestamp	when the member joined the organisation

{
    "user": {},
    "is_owner": false,
    "pending": false,
    "joined_at": "2020-01-01T00:00:00Z"
}

Organisation User Ban Object

Field	Type	Description
user	user object or id	the banned user
reason	string	reason for the ban
banned_at	ISO8601 timestamp	when the user was banned

{
    "user": {},
    "reason": "violation of code of conduct",
    "banned_at": "2020-01-01T00:00:00Z"
}

Create Organisation

POST /organisations

Parameters

Field	Type	Description
name	string	the organisation's name (2 - 100 characters)

Get Organisation

GET /organisations/{organisation.id}

Returns the organisation object for the given organisation id.

Get Organisation Member

GET /organisations/{organisation.id}/members/{user.id}

Returns the organisation member object for the specified user.

List Organisation Members

GET /organisations/{organisation.id}/members

Returns a list of organisation member objects that are members of the organisation.

Query filters

Field	Type	Description	default
filter	string	starts with filter for a members first name, last name, or email	null

List Organisation Roles

GET /organisations/{organisation.id}/roles

Returns an array of role objects for the organisation, ordered by their display order. The implicit @everyone role is included in the response. Requires membership in the organisation.

Error Responses

Status Code	Description
400	The organisation was not found
403	The user is not a member of the organisation

Create Organisation Role

POST /organisations/{organisation.id}/roles

Creates a new role in the organisation. Requires the MANAGE_ROLES permission.

Parameters

Field	Type	Description	Default
alias	string	the role's alias (up to 20 characters)	new role

Error Responses

Status Code	Description
400	The organisation was not found
403	The user lacks the MANAGE_ROLES permission

Change Organisation Role Order

PATCH /organisations/{organisation.id}/roles

Changes the display order of a role within the organisation. Requires the MANAGE_ROLES permission. Roles between the old and new order will be shifted accordingly.

Parameters

Field	Type	Description
id	snowflake	the role's id
order	integer	the new display order for the role

Error Responses

Status Code	Description
400	The organisation or role was not found
403	The user lacks the MANAGE_ROLES permission
403	The role does not belong to the organisation

Add Role to User

PUT /organisations/{organisation.id}/members/{user.id}/roles/{role.id}

Adds a role to a user. Requires the MANAGE_ROLES permission. The user must be a member of the organisation.

Error Responses

Status Code	Description
400	The organisation, role, or user was not found
400	The user is not a member of the organisation
403	The user lacks the MANAGE_ROLES permission
403	The role does not belong to the organisation

Remove Role from User

DELETE /organisations/{organisation.id}/members/{user.id}/roles/{role.id}

Removes a role from a user. Requires the MANAGE_ROLES permission.

Error Responses

Status Code	Description
400	The organisation, role, or user was not found
403	The user lacks the MANAGE_ROLES permission
403	The role does not belong to the organisation

Update Organisation Role Permission

PUT /organisations/{organisation.id}/permissions/{roleId}

Updates the permissions granted to a role, user, or the @everyone group within the organisation. The roleId parameter accepts the id of a role, a user, or the organisation itself (for the @everyone group). Requires the MANAGE_ROLES permission.

Parameters

Field	Type	Description
permissions	object<string, Permission Grant Type>	permissions to grant or revoke

Error Responses

Status Code	Description
400	The permissions object was not provided
403	The user lacks the MANAGE_ROLES permission
404	The organisation was not found

Create Project

POST /organisations/{organisation.id}/projects

Creates a new project in the organisation. Requires the CREATE_PROJECTS permission. The creator is automatically granted ADMIN_PROJECTS permission on the new project.

JSON Params

Field	Type	Description	Default
code	?string	the project's short code (max 12 characters)
name	?string	the project's name (max 200 characters)	new project
description	?string	a description of the project
readme	?string	the project's readme content (max 64000 characters)
status	?project status	the status to set for the project	open

Error Responses

Status Code	Description
400	Bad request (organisation does not exist)
403	Forbidden (insufficient permissions)
429	Failed to create new project (no quota)

List Projects

GET /organisations/{organisation.id}/projects

Returns an array of project objects for the organisation. Requires membership in the organisation. Only projects where the caller has the VIEW_PROJECTS permission will be included.

Query Parameters

Field	Type	Description
$filter	?string	OData filter expression (supports status)
$skip	?integer	number of records to skip
$top	?integer	maximum number of records to return

Error Responses

Status Code	Description
400	Bad request (organisation does not exist)
403	Forbidden (caller is not a member)

List Organisation Workgroups

GET /organisations/{organisation.id}/workgroups

Create Organisation Workgroup

POST /organisations/{organisation.id}/workgroups

Get Organisation Documents

GET /organisations/{organisation.id}/documents

Returns a list of document objects that are members of the organisation.

Get Organisation Work Items

GET /organisations/{organisation.id}/workitems

Returns a list of work item objects that are members of the organisation.

Parameters

Field	Type	Description