Member Export - Huddle/huddle-apis GitHub Wiki

Summary

Asynchronously exports all members of a company to CSV. The People API implements this under /people/companies/{companyId}/members/export. A POST starts the job (202 Accepted with a progress link); clients poll progress until Finished, then follow content to download the file.

Membership advertises the entry point on the People resource as link relation members-export (absolute URI points at the People export URL for that company).

Limit: companies with 10,000 or more members receive 403 with MemberLimitExceeded (see below).

Status

Operation Status
Start member export Live
Get export progress Live
Download CSV Live

Operations

Operation Method Path (typical public URL)
Start export POST /people/companies/{companyId}/members/export
Poll progress GET /people/companies/{companyId}/members/export/{membersExportId}
Download CSV GET /people/companies/{companyId}/members/export/{membersExportId}/content

membersExportId is a server-generated GUID.

Start member export

POST checks company manager or administrator, enforces the configured maximum member count for export, then starts the job asynchronously.

Request (JSON)

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

Request (XML)

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

Response — accepted

HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+json
Link: <...>; rel="progress"
{
  "links": [
    { "rel": "self", "href": "..." }
  ],
  "status": "InProgress"
}
HTTP/1.1 202 Accepted
Content-Type: application/vnd.huddle.data+xml
Link: <...>; rel="progress"
<membersExport>
  <link rel="self" href="..." />
  <status>InProgress</status>
</membersExport>

Response — member limit exceeded

Companies with ≥ 10,000 members cannot use this export.

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.huddle.data+json
{ "errors": [ "MemberLimitExceeded" ] }
HTTP/1.1 403 Forbidden
Content-Type: application/vnd.huddle.data+xml
<errorResult>
  <error>MemberLimitExceeded</error>
</errorResult>

Other responses (start)

Status Reason
403 Not manager/admin
404 Company does not exist or user not in company

Get export progress

Poll until status is Finished (then use content) or Error.

Request (JSON)

GET /people/companies/123/members/export/d8a3d254-9b2a-40c0-b4f5-dbd94c13430a HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: Bearer frootymcnooty/vonbootycherooty

Request (XML)

GET /people/companies/123/members/export/d8a3d254-9b2a-40c0-b4f5-dbd94c13430a HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: Bearer frootymcnooty/vonbootycherooty

Response — in progress

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
  "links": [
    { "rel": "self", "href": "..." }
  ],
  "status": "InProgress"
}
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<membersExport>
  <link rel="self" href="..." />
  <status>InProgress</status>
</membersExport>

Response — finished

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
Link: <...>; rel="content"
{
  "links": [
    { "rel": "self", "href": "..." },
    { "rel": "content", "href": "..." }
  ],
  "status": "Finished"
}
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
Link: <...>; rel="content"
<membersExport>
  <link rel="self" href="..." />
  <link rel="content" href="..." />
  <status>Finished</status>
</membersExport>

Response — error (job failed)

Still 200 OK with status: Error (no CSV).

HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
  "links": [
    { "rel": "self", "href": "..." }
  ],
  "status": "Error"
}
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+xml
<membersExport>
  <link rel="self" href="..." />
  <status>Error</status>
</membersExport>

Other responses (progress)

Status Reason
403 Not manager/admin
404 Unknown membersExportId / no export progress available

Download CSV

Use the content link (or equivalent URI) from a Finished export.

Request

GET /people/companies/123/members/export/d8a3d254-9b2a-40c0-b4f5-dbd94c13430a/content HTTP/1.1
Accept: text/csv
Authorization: Bearer frootymcnooty/vonbootycherooty

Response

First row: column headers.

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="members.csv"
FirstName,LastName,Email,Role,LastLoginDate,IsCompanyManager,Status
Isidore,McHohenheim,[email protected],Manager,2015-12-31T23:59:59,Yes,Active
John,Doe,[email protected],CEO,2015-12-31T23:59:59,No,Inactive

Other responses (download)

Status Reason
403 Not manager/admin, or export status Error
404 Export still InProgress, unknown id, or progress not found

Related

  • Members — list and add members.
  • Member — single member operations.
⚠️ **GitHub.com Fallback** ⚠️