Summary

The Membership Companies API is a representation of companies within Huddle.

Status

Operation
Retrieve a company
Retrieve all companies
Create a company
Retrieving company managers
Add company managers
Remove company managers
Bulk remove members
Retrieve all workspaces in a Company
Retrieve Company Settings
Retrieve Editable Company Settings
Update Company Settings
Get Company Members
Remove a member from a company
Merge Companies

Operations

Retrieve a company

You can GET a given company by its ID.

Example

Example request, asking for the company with ID 123:

GET /companies/123 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "alternate", "href": "..." },
    { "rel": "managers", "href": "..." },
    { "rel": "bulk-delete", "href": "..." },
    { "rel": "add-managers", "href": "..."},
    { "rel": "remove-managers", "href": "..." },
    { "rel": "settings", "href": "..."},
    { "rel": "create", "href": "..."}
  ],
  "name": "My company"
}

Response Properties

Name	Description
name	The name of the company

Response Link relations

Name	Description	Methods
self	The URI of this company.	GET
managers	The URI to request the list of Managers for the Company.	GET
bulk-delete	The URI to request the remove multiple members from the Company.	POST
add-managers	The URI to request adding company managers	POST
remove-managers	The URI to request removing company managers	POST
settings	The URI to request retrieving company settings	GET
create	The URI to request creating a company	POST

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Retrieve all companies

You can GET all companies you manage.

Example

Example request, asking for the companies that the user manages:

GET /companies HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links": [
    { "rel": "self", "href": "..."}
  ],
  "companies": [
    {
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "alternate", "href": "..." },
        { "rel": "managers", "href": "..." },
        { "rel": "bulk-delete", "href": "..." },
        { "rel": "add-managers", "href": "..." },
        { "rel": "remove-managers", "href": "..." },
        { "rel": "settings", "href": "..." },
        { "rel": "create", "href": "..." },
        { "rel": "members", "href": "..." },
        { "rel": "members-search", "href": "..." },
        { "rel": "members-export", "href": "..." },
        { "rel": "workspaces", "href": "..." },
        { "rel": "workspaces-export", "href": "..." },
        { "rel": "businessunits", "href": "..." },
        { "rel": "whitelist", "href": "..." },
        { "rel": "memberautocomplete", "href": "..." },
        { "rel": "published-documents", "href": "..." },
        { "rel": "edit", "href": "..." },
        { "rel": "internal-domains", "href": "..." },
        { "rel": "security-audit", "href": "..." },
        { "rel": "bulk-email-validation", "href": "..." },
        { "rel": "clients", "href": "..." }
      ],
      "name": "My company 1"
    },
    {
      "links": [ ... ],
      "name": "My company 2"
    }
  ]
}

Response Properties

Name	Description
companies	Set of companies managed by the user

Response Link relations

Name	Description	Methods
self	The URI of the set of companies.	GET
	See Retrieve a company

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden

Create a Company

Companies can be created by Huddle admins only.

Example

Request

POST /companies HTTP/1.1
Content-Type: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "name": "My brand new company!"
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.huddle.data+json
Location: .../companies/123

{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "managers", "href": "..." },
    ...
  ],
  "name": "My brand new company!"
}

Request Properties

Name	Description
name	The name of the company

Other Responses

Refer to General HTTP Status Codes.

Below are responses related to this resource

Case	Response
Invalid authorization token	401 Unauthorized
A non admin user request to create a company	403 Forbidden
Admin is sending the request without a name	400 Bad Request
The company name exceeds 255 characters	400 Bad Request
The company name already exits	409 Conflict

Retrieve Company managers

You can GET all company managers and the metadata of the managers in a company.

Example

Example request, asking for the Company managers from the Company with ID 123:

GET /companies/123/managers HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Rick Sanchez",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Response Properties

Name	Description
managers	The list of managers for the given company

Response Link relations

Property	Name	Description	Methods
	self	The URI of the company managers collection.	GET
	parent	The URI of the Company that the managers belongs to.	GET
	add-managers	The URI to add managers to the Company.	POST
	remove-managers	The URI to remove managers to the Company.	POST
	first	The URI of the first page of managers.	GET
	previous	The URI of the previous page of managers.	GET
	next	The URI of the next page of managers.	GET
managers	self	The URI of the user	GET
managers	avatar	The URI of the user's avatar	GET
managers	alternate	The URI of the user's profile	GET

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Add Company Managers

You can add managers to a company.

Example

Example request to add company managers for the Company with ID 123:

POST /companies/123/managers/add HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response:

If successful, this method will return with a 200 OK status code. The response body will be the updated Company Manager collection. This response uses the standard error codes and returns standard response headers.

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /companies/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "Bruce Wayne",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel" : "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Request Properties

Name	Description
rel	The relationship of the resource for the given context
href	The URI of the specified resource

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found
User/s manager/s does not exist	404 Not Found

Remove Company Managers

You can remove managers from a company.

Example

Example request for removing company managers from the company with ID 123:

POST /companies/123/managers/remove HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "manager", "href" : "..." },
    ...
  ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /companies/123/managers

{
  "links" : [
    { "rel" : "self", "href" : "..." },
    { "rel" : "parent", "href" : "..." },
    { "rel" : "add-managers", "href" : "..." },
    { "rel" : "remove-managers", "href" : "..." },
    { "rel" : "first", "href" : "..." },
    { "rel" : "previous", "href" : "..." },
    { "rel" : "next", "href" : "..." }
  ],
  "managers" : [
    {
      "name" : "David Bravo",
      "email" : "[email protected]",
      "links" : [
            { "rel" : "self", "href" : "..." },
            { "rel" : "avatar", "href" : "..." },
            { "rel": "alternate", "href": "..." }
      ]
    },
    ...
  ]
}

Request Properties

Name	Description
rel	The relationship of the resource for the given context
href	The URI of the specified resource

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found
User/s manager/s does not exist	404 Not Found

Bulk Remove Members

You can remove multiple members from a company in one call.

Example

Note that the links provided are for members, not users. For more details read about how to retrieve members of a company

Example request for removing members from the company with ID 123:

POST /companies/123/bulkdelete HTTP/1.1
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "links" : [
    { "rel" : "member", "href" : ".../people/companies/123/members/456" },
    { "rel" : "member", "href" : ".../people/companies/123/members/789" },
    ...
  ]
}

Example response:

If successful, this method will return with a 204 No Content.

HTTP/1.1 204 No Content

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found
Member does not exist	400 Bad Request
Member is not in that company	400 Bad Request

Retrieve Company Workspaces

You can GET the Workspaces for a given Company and it will display the first page of Workspaces for that Company.

Example

Example request for retrieving company workspaces for Company with ID 123:

GET /companies/123/workspaces HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "links" : [{ "rel" : "self", "href" : "..." }],
    "workspaces" : [
    {
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." },
        { "rel": "leave", "href": "..." },
        { "rel": "teams", "href": "..." },
        { "rel": "managers", "href": "..." },
        { "rel": "users", "href": "..."}
      ],
      "name": "My Important Workspace",
      "createdDate": "2014-07-04T14:13:57.447Z"
    },
    {
      "links": [
        { "rel": "self", "href": "..." },
        { "rel": "parent", "href": "..." },
        { "rel": "leave", "href": "..." },
        { "rel": "teams", "href": "..." },
        { "rel": "managers", "href": "..." },
        { "rel": "users", "href": "..."}
      ],
      "name": "My Important Workspace",
      "createdDate": "2014-07-04T14:13:57.447Z"
    }]
  }

Filters

Query string parameters are used to filter the company workspaces. Returns empty list of workspaces if no workspaces were found that match your query.

Request with parameters:

GET /companies/123/workspaces?q=technology&pagesize=20&skip=0&sort=name&order=desc HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Parameter	Description	Default
`pagesize`	The maximum number of elements to return, between 1 - 100.	20
`skip`	The number of elements to skip.	0
`q`	Query with which to filter results. Space delimited query terms will return results that match all terms on name. Multiple terms constitute a phrase. Comma delimited phrases will match across any phrases.
`sort`	The property you want to sort by. Currently only "name" is available	`name`
`order`	The direction (ascendent/descendent) you want to order by, i.e. `asc` or `desc`.	`asc`

Response Properties

Name	Description
`workspaces`	Set of workspaces that belongs to the supplied company.

Response Link relations

Name	Description	Methods
self	The URI of the Company Workspaces.	GET
first	The URI to move to the first page.	GET
previous	The URI to move to the previous page.	GET
next	The URI to move to the next page.	GET

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor does not have company manager permissions	403 Forbidden
Company does not exist	404 Not Found
Requested page does not exists (greater than last page)	404 Not Found
Requested page is invalid (less than 1)	400 Bad Request
Specified fieldName for sort does not exist or is not available for sorting	400 Bad Request
Sort order is not `:asc` or `:desc`	400 Bad Request

Retrieve Company Settings

You can retrieve the status of Company settings.

Example

Example request for retrieving company settings and their status for Company with ID 123:

GET /companies/123/settings HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
  "loginLogoutReportIsEnabled": false,
  "mobilePinIsEnabled ": true,
  "workspaceInvitationInternalOnlyEnabled": true,
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "update", "href": "..." }
  ]
}

Response Properties

Settings	Description
loginLogoutReportIsEnabled	Enabled or disabled the Login/Logout Report
mobilePinIsEnabled	Enabled or disabled requirement to use a pin in Huddle mobile apps
workspaceInvitationInternalOnlyEnabled	Enabled or disabled whitelist of email addresses or domains that can be invited into your workspaces

Response Link relations

Name	Description	Methods
self	The URI of the Company settings.	GET
parent	The URI of the Company that the settings belongs to.	GET
update	The URI to update Company settings.	PUT

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Retrieve Editable Company Settings

If the company settings has not been created for a company then a default template with settings disabled will be returned.

Example

Example request asking for editable settings for company with ID 123:

GET /companies/123/settings/editable HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization:  Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "mobilePin": {
        "enabled" : true
    },
    "loginLogoutReport": {
        "enabled" : false
    },
    "workspaceInvitationInternalOnly" : {
        "enabled" : true
    },
     "links": [
         { "rel": "self", "href": "..." },
         { "rel": "parent", "href": "..." }
  ]
}

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Update Company Settings

To update company settings first get the editable settings to show which company settings can be updated . Then to update them, make a call to the update company settings endpoint.

Example

Example request for updating Company settings for Company with ID 123

PUT /companies/123/settings/editable
Content-Type: application/vnd.huddle.data+json
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
    "mobilePin": {
        "enabled" : true
    },
    "loginLogoutReport": {
        "enabled" : false
    },
    "workspaceInvitationInternalOnly" : {
        "enabled" : true
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Content-Location: /companies/123/settings

{
  "loginLogoutReportIsEnabled": true,
  "mobilePinIsEnabled ": true,
  "workspaceInvitationInternalOnlyEnabled": true,
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "parent", "href": "..." },
    { "rel": "editable", "href": "..." }
  ]
}

Response Properties

Settings	Description
loginLogoutReportIsEnabled	Enable or disable the Login/Logout Report
mobilePinIsEnabled	Enable or disable requirement to use a pin in Huddle mobile apps
workspaceInvitationInternalOnlyEnabled	Enable or disable list of allowed email addresses or domains that can be invited into your workspaces

Response Link relations

Name	Description	Methods
self	The URI of the company settings	GET
parent	The URI of the company that the settings belong to	GET
editable	The URI of the company settings that can be updated	GET

Other Responses

Case	Response
Invalid company settings	400 Bad Request
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Get Company Members

Gets members that belong to a company.

Example

Example request for getting members that belong to company with ID 123:

GET /companies/123/members HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json

{
    "links" : [{
      "rel" : "self",
      "href" : "..."
    },{
      "rel": "search",
      "href": "..."
    }],
    "members" : [{
      "links" : [{
        "rel" : "self",
        "href" : "..."
      }, {
        "rel" : "edit",
        "href" : "..."
      }, {
        "rel" : "delete",
        "href" : "..."
      }, {
        "rel" : "company",
        "href" : "..."
      }, {
        "rel" : "user",
        "href" : "..."
      }, {
        "rel" : "avatar",
        "href" : ...
      }, {
        "rel" : "profile",
        "href" : ...
      }],
      "firstName" : "Andy",
      "lastName" : "McLoughlin",
      "displayName" : "Andy",
      "emailAddress" : "[email protected]",
      "role" : "Founder",
      "internal" : true,
      "companyManager" : false,
      "lastLoginDate" : "Tue, 14 Aug 2012 10:59:39 GMT"
    },{
      "links" : [{
        "rel" : "self",
        "href" : "..."
      }, {
        "rel" : "edit",
        "href" : "..."
      }, {
        "rel" : "delete",
        "href" : "..."
      }, {
        "rel" : "company",
        "href" : "..."
      }, {
        "rel" : "user",
        "href" : "..."
      }, {
        "rel" : "avatar",
        "href" : ...
      }, {
        "rel" : "profile",
        "href" : ...
      }, {
        "rel" : "companyManager",
        "href" : ...
      }],
      "firstName" : "Ali",
      "lastName" : "Mitchell",
      "displayName" : "Ali",
      "emailAddress" : "[email protected]",
      "role" : "Founder",
      "internal" : true,
      "companyManager" : true,
      "lastLoginDate" : "Tue, 14 Aug 2012 10:59:39 GMT",
    }],
    "filteredMembers": 2,
    "totalMembers": 2
  }

Parameters

Name	Description	Methods	Optional	Default
page	Page that you are requesting.	GET	Yes	1
pagesize	Can be used in conjuction with `page` or with `skip`. It can also be used on its own. However, specifying `page`, `pagesize` and `skip` is not allowed.	GET	Yes	If `page` present as a query parameter then default is 50. Otherwise, when no `pagesize` specified, it is 20.
skip	Can be used in conjunction with `pagesize` or on its own. If used with `page`, it will be ignored i.e. `page` will be used as the query parameter.	GET	Yes	0
q	Query with which to filter results. Space delimited query terms will return results that match all terms across the following field names: `first name`, `last name`, `display name`, `email address`, `email domain` and `role`.	GET	Yes
sort	Can either be in the form of `fieldName`, or `fieldName:asc/fieldName:desc`. If direction is omitted, then direction will use default. Can sort on `displayname` or `lastlogindate` fields. If the order field is included in the query parameters then sort should just specify the fieldname that should be used for ordering.	GET	Yes	`displayname`
order	Can specify if want to order in ascending (`asc`) or descending (`desc`) order.	GET	Yes	`asc`

Request with parameter

GET /companies/123/members?page=1&q=ali mitchell,andy&sort=displayname:desc HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Link relations

Name	Description	Methods
self	The current URI of this member list.	GET
search	Enpoint used to search members of the company	POST
next	The URI of the next page of members, using sort order specified.	GET
prev	The URI of the previous page of members, using sort order specified.	GET
first	The URI of the first page of members, using sort order specified.	GET

The prev link is not present on the first page of members.

The next link is not present on the last page of members.

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor does not have company manager permissions	403 Forbidden
Requested page does not exist (greater than last page)	404 Not Found
Requested page is invalid, less than 1	400 Bad Request
Specified fieldName for sort does not exist or is not available for sorting	400 Bad Request
Sort order is not `asc` or `desc`	400 Bad Request
page, pagesize and skip have all been specified	400 Bad Request

Remove a member from a company

Example

Example request, asking to remove a member from a company:

DELETE /companies/123/members/456 HTTP/1.1
Authorization: Bearer frootymcnooty/vonbootycherooty

Example response:

HTTP/1.1 204 No Content

Other Responses

Case	Response
Invalid authorization token	401 Unauthorized
Actor is not an authorised user	403 Forbidden
Company does not exist	404 Not Found

Merge Companies

This endpoint is used for merging one or more source Companies, into a target Company. This will move all Accounts, Workspaces, Teams, and Members into the target Company.

Request

The following request will merge Companies 456 and 789 into Company 123.

PUT /123/merge
Content-Type: application/json
Authorization: Bearer frootymcnooty/vonbootycherooty

{
  "companyIds": [
    456,
    789
  ]
}

Response

HTTP/1.1 200 OK

Other Responses

Case	Response
Invalid Company IDs supplied	400 Bad Request
Duplicate Company IDs supplied	400 Bad Request
Source Company does not exist	400 Bad Request
Invalid authorization token	401 Unauthorized
User is not a Huddle Admin	403 Forbidden
Target Company does not exist	404 Not Found

CompanyNew - Huddle/huddle-apis GitHub Wiki

Summary

Status

Operations

Retrieve a company

Example

Response Properties

Response Link relations

Other Responses

Retrieve all companies

Example

Response Properties

Response Link relations

Other Responses

Create a Company

Example

Request

Response

Request Properties

Other Responses

Retrieve Company managers

Example

Response Properties

Response Link relations

Other Responses

Add Company Managers

Example

Example response:

Request Properties

Other Responses

Remove Company Managers

Example

Example response:

Request Properties

Other Responses

Bulk Remove Members

Example

Example response:

Other Responses

Retrieve Company Workspaces

Example

Filters

Response Properties

Response Link relations

Other Responses

Retrieve Company Settings

Example

Response Properties

Response Link relations

Other Responses

Retrieve Editable Company Settings

Example

Other Responses

Update Company Settings

Example

Response Properties

Response Link relations

Other Responses

Get Company Members

Example

Parameters

Link relations

Other Responses

Remove a member from a company

Example

Other Responses

Merge Companies

Request

Response

Other Responses

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️