DocumentApprovals - Huddle/huddle-apis GitHub Wiki

Summary

Use this API to manage approval workflows on a document's current version: retrieve approval state, add or replace approvers, set an optional due date/message, and allow each assignee to complete or reject their own assignment.

This endpoint group is intended for integrations that need approval lifecycle control in one place without directly orchestrating lower-level Tasks APIs.

Operations

Method Path Purpose Details
GET /approvalsbff/documents/123/approvals Get approval state for the document's current version. Jump
POST /approvalsbff/documents/123/approvals/request Create or upsert approval assignees/due date/message. Jump
POST /approvalsbff/documents/123/approvals/assignment Complete or reject the current caller's assignment. Jump
GET /approvalsbff/documentowners/123/approvals List open approvals created by a document owner with assignment detail. Jump
GET /approvalsbff/documentowners/123/approvals List open approvals created by a document owner with counts only. Jump
GET /approvalsbff/workspaces/555/approvals List open approvals across a workspace. Jump

GET document approvals

GET request

GET /approvalsbff/documents/123/approvals HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

GET response 200 

{
  "links": [
    { "rel": "self", "href": "https://api.huddle.net/approvalsbff/documents/123/approvals" },
    { "rel": "parent", "href": "https://api.huddle.net/files/documents/123" },
    { "rel": "updateassignees", "href": "https://api.huddle.net/approvalsbff/documents/123/approvals/updateassignees" },
    { "rel": "approvalrequest", "href": "https://api.huddle.net/approvalsbff/documents/123/approvals/request" }
  ],
  "status": "Open",
  "dueDate": "Thu, 30 Nov 2017 00:00:00 GMT",
  "requester": {
    "name": "Bob",
    "email": "[email protected]",
    "rel": "requester",
    "links": [{ "rel": "self", "href": "https://api.huddle.net/users/108" }]
  },
  "assignments": [
    {
      "actors": [
        {
          "name": "Jane",
          "email": "[email protected]",
          "rel": "assignee",
          "links": [{ "rel": "self", "href": "https://api.huddle.net/users/456" }]
        }
      ],
      "status": "Open",
      "created": "Wed, 29 Nov 2017 00:00:00 GMT",
      "links": [
        { "rel": "self", "href": "https://api.huddle.net/users/456" },
        { "rel": "edit", "href": "https://api.huddle.net/approvalsbff/documents/123/approvals/assignment" }
      ]
    }
  ]
}

Notes:

  • Assignment status values are Open, Complete, and Rejected.
  • Top-level status is Open if any assignment is open, Rejected if none are open and at least one is rejected, otherwise Complete.
  • dueDate is omitted when no due date exists.

POST approval request (create/upsert)

Creates approvals if none exist for the current document version, otherwise updates due date/message/assignees.

POST request

POST /approvalsbff/documents/123/approvals/request HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{
  "assignees": [
    { "href": "https://api.huddle.net/users/456" },
    { "href": "https://api.huddle.net/users/789" }
  ],
  "message": "Please review by Friday",
  "dueDate": "Thu, 30 Nov 2017 00:00:00 GMT"
}

POST response

200 OK (empty body).

Behavior:

  • If assignees is empty ([]), the existing workflow is removed.
  • assignees[].href must resolve to valid user URIs.
  • message and dueDate are optional.

POST assignment status

Updates the authenticated caller's own assignment status.

Use case: assignee actions from a "My approvals" UI where the current user chooses Approve or Reject on one document.

Assignment request

POST /approvalsbff/documents/123/approvals/assignment HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{
  "status": "complete"
}

or

{
  "status": "rejected"
}

Assignment response 200

Returns the same JSON shape as GET /approvalsbff/documents/{documentId}/approvals with updated assignment/status values.

Validation:

  • Supported values are complete and rejected (case-insensitive).
  • If the caller has no open assignment on the document, the API returns 400.

GET owner approvals

Lists approvals created by a specific owner (ownerId) with per-assignment detail.

Use case: a manager dashboard showing all active approvals they requested, including who is still pending.

Owner approvals request

GET /approvalsbff/documentowners/123/approvals HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Owner approvals response 200 

{
  "links": [
    { "rel": "self", "href": "https://api.huddle.net/approvalsbff/documentowners/123/approvals" }
  ],
  "approvals": [
    {
      "dueDate": "Thu, 01 Jan 2026 00:00:00 GMT",
      "assignments": [
        {
          "actor": {
            "name": "Jane",
            "email": "[email protected]",
            "rel": "assignee",
            "links": [{ "rel": "self", "href": "https://api.huddle.net/users/456" }]
          },
          "status": "Open"
        },
        {
          "actor": {
            "name": "Alex",
            "email": "[email protected]",
            "rel": "assignee",
            "links": [{ "rel": "self", "href": "https://api.huddle.net/users/789" }]
          },
          "status": "Complete"
        }
      ],
      "document": {
        "title": "Policy.docx",
        "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "extension": "docx",
        "links": [{ "rel": "self", "href": "https://api.huddle.net/files/documents/20" }],
        "workspace": { "links": [{ "rel": "self", "href": "https://api.huddle.net/workspaces/555" }] }
      }
    }
  ]
}

GET owner approvals (slim)

Lists approvals created by an owner, but returns counts (openAssignments, completedAssignments) instead of detailed assignment actors.

Use case: lightweight list views where you only need progress badges and document metadata.

Owner approvals slim request

GET /approvalsbff/documentowners/123/approvals-slim HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Owner approvals slim response 200 

{
  "links": [
    { "rel": "self", "href": "https://api.huddle.net/approvalsbff/documentowners/123/approvals" }
  ],
  "approvals": [
    {
      "dueDate": "Thu, 01 Jan 2026 00:00:00 GMT",
      "openAssignments": 2,
      "completedAssignments": 1,
      "document": {
        "title": "Policy.docx",
        "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "extension": "docx",
        "links": [{ "rel": "self", "href": "https://api.huddle.net/files/documents/20" }],
        "workspace": { "links": [{ "rel": "self", "href": "https://api.huddle.net/workspaces/555" }] }
      }
    }
  ]
}

GET workspace approvals

Lists open approvals within a workspace grouped by document.

Use case: workspace-level reporting widgets (for admins or coordinators) that need a single feed of outstanding approvals.

Workspace approvals request

GET /approvalsbff/workspaces/555/approvals HTTP/1.1
Accept: application/json
Authorization: Bearer <token>

Workspace approvals response 200 

{
  "links": [
    { "rel": "self", "href": "https://api.huddle.net/approvalsbff/workspaces/555/approvals" }
  ],
  "approvals": [
    {
      "dueDate": "Thu, 01 Jan 2026 00:00:00 GMT",
      "assignments": [
        {
          "actor": {
            "name": "Jane",
            "email": "[email protected]",
            "rel": "assignee",
            "links": [{ "rel": "self", "href": "https://api.huddle.net/users/456" }]
          },
          "status": "Open"
        }
      ],
      "document": {
        "title": "Q4 Plan.xlsx",
        "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "extension": "xlsx",
        "links": [{ "rel": "self", "href": "https://api.huddle.net/files/documents/10" }],
        "workspace": { "links": [{ "rel": "self", "href": "https://api.huddle.net/workspaces/555" }] }
      }
    }
  ]
}

Error responses

Status Meaning
400 Invalid documentId, invalid request body, or invalid assignment transition.
401 Unauthorized.
403 Forbidden.
404 Document not found.
504 Upstream timeout.
500 Unexpected server error.
⚠️ **GitHub.com Fallback** ⚠️