Members - Huddle/huddle-apis GitHub Wiki

Summary

The members resource is the collection of people in a company. It is implemented by the People API at /people/companies/{companyId}/members. Use it to page and filter members, and (via the search link) to run a cached search: POST creates a search job; GET the returned URI retrieves results. That flow is distinct from the lightweight GET .../members/search?q=... behaviour described in Member-Search.

For a single member (read, edit, delete), see Member. For CSV export, see Member-Export.

Note: This document uses the /people API prefix. A newer /membership equivalent is also available — see CompanyNew.

Status

Operation Status
List members Live
Add member to company Live
Create member search Live
Get member search results Live
Page or sort search results Live

Operations

Operation Method Path (typical public URL)
List members (paging, q, sort) GET /people/companies/{companyId}/members
Add member POST /people/companies/{companyId}/members
Create cached search POST /people/companies/{companyId}/members/search
Get search results (page/sort) GET /people/companies/{companyId}/members/search/{searchGuid}

On the People service (without the people prefix), the same paths are /companies/{companyId}/members, .../members/search, and .../members/search/{searchGuid}.

Deleting a member: use the delete link (Membership URI); see Member.

List members of a given company

GET the collection to retrieve the first page (or a specific page via query parameters).

XML example

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<members>
  <link rel="self" href="people/companies/123/members" />
  <link rel="search" href="people/companies/123/members/search"/>

  <member>
    <link rel="self" href="..." />
    <link rel="edit" href="..." />
    <link rel="delete" href="..." />
    <link rel="company" href="..." />
    <link rel="user" href="..." />
    <link rel="avatar" href="..." />
    <link rel="profile" href="..." />

    <firstName>Andy</firstName>
    <lastName>McLoughlin</lastName>
    <displayName>Andy</displayName>
    <emailAddress>[email protected]</emailAddress>
    <role>Founder</role>
    <internal>true</internal>
    <companyManager>false</companyManager>
    <lastLoginDate>2013-04-04T23:50:34</lastLoginDate>
  </member>
  <member>
    <link rel="self" href="..." />
    <link rel="edit" href="..." />
    <link rel="delete" href="..." />
    <link rel="company" href="..." />
    <link rel="user" href="..." />
    <link rel="avatar" href="..." />
    <link rel="profile" href="..." />
    <link rel="companyManager" href="..." />

    <firstName>Ali</firstName>
    <lastName>Mitchell</lastName>
    <displayName>Ali</displayName>
    <emailAddress>[email protected]</emailAddress>
    <role>Founder</role>
    <internal>true</internal>
    <companyManager>true</companyManager>
    <lastLoginDate>2013-04-04T23:50:34</lastLoginDate>
  </member>
  <filteredMembers>2</filteredMembers>
  <totalMembers>2</totalMembers>
</members>

JSON example

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
  "links": [
    { "rel": "self", "href": "people/companies/123/members" },
    { "rel": "search", "href": "people/companies/123/members/search" }
  ],
  "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 (list)

Name Description Optional Default
page Page number (positive integer). Yes 1
q Comma-separated phrases; each phrase is split on spaces into terms. Results match those fields using the service’s search rules (name, role, email, display name, email domain, etc.). Yes —
sort fieldName or fieldName:asc / fieldName:desc (case-insensitive field name). Supported fields include displayname and lastlogindate. Yes ascending displayname

Example:

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

Link relations (list)

Name Description Methods
self This page of the member list. GET
search POST here to create a cached search. POST
next / prev / first / last Paging; omitted when not applicable. GET

Other responses (list)

Case Response
Invalid authorization 401 Unauthorized
Company does not exist, user not in company 404 Not Found
User in company but not manager/admin 403 Forbidden
page not a positive integer 400 Bad Request (“Page should be a positive integer”)
Page beyond last page 404 Not Found
Invalid sort field or direction 400 Bad Request

Add member to company

POST with a member body containing userId of an existing user. Requires company manager or administrator. Returns 201 Created with Location set to the new member.

Request

POST /people/companies/123/members HTTP/1.1
Content-Type: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
<member>
  <userId>999</userId>
</member>

Response

HTTP/1.1 201 Created
Location: .../people/companies/123/members/{newMemberId}
Content-Type: application/vnd.huddle.data+xml

The response body is the created member resource (same shape as Get member).

Create member search

POST application/x-www-form-urlencoded with q (required, non-empty). Requires company manager or admin.

Request

POST /people/companies/123/members/search HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer frootymcnooty/vonbootycherooty

q=Andy

Response

HTTP/1.1 201 Created
Location: /people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/vnd.huddle.data+xml
<memberSearch>
  <link rel="self" href="/people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />
  <query>Andy</query>
</memberSearch>

Other responses (create search)

Case Response
Missing or empty q 400 Bad Request with error body (“Need to POST a query string…”)
Not manager/admin / company access 404 / 403

Get member search results

GET the URI returned in Location (or self on the memberSearch resource).

Request

GET /people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Expires: Thu, 04 Dec 2014 10:59:39 GMT
<members>
  <link rel="self" href="/people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" />
  <link rel="search" href="people/companies/123/members/search"/>

  <member>
    <link rel="self" href="..." />
    <link rel="edit" href="..." />
    <link rel="delete" href="..." />
    <link rel="company" href="..." />
    <link rel="avatar" href="..." />
    <link rel="profile" href="..." />

    <firstName>Andy</firstName>
    <lastName>McLoughlin</lastName>
    <displayName>Andy</displayName>
    <emailAddress>[email protected]</emailAddress>
    <role>Founder</role>
    <internal>true</internal>
    <companyManager>false</companyManager>
    <lastLoginDate>2013-04-04T23:50:34</lastLoginDate>
  </member>
  <filteredMembers>1</filteredMembers>
  <totalMembers>2</totalMembers>
</members>

Other responses (get search)

Case Response
Unknown or expired searchGuid 404 Not Found (“Query not found”)

Page or sort search results

GET /people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=2 HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty
GET /people/companies/123/members/search/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?sort=lastlogindate:desc HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Related

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