Skip to content
shuffl
Get started

Searches the public product guides only. Nothing from a workspace is read, and questions are not saved.

Reference

HR requests API

20 operations. Generated from the OpenAPI document, so this page always matches the API.

OpenAPI documentErrors and rate limitsSDK and CLI recipes

On this page

hr.categories

Read the HR request categories and response target

POST/api/v1/manage/hr/categories

const result = await shuffl.hr.categories();
Request fields (none)

This operation takes no input.

Response object
  • canConfigure boolean required
  • categories object[] required
    • accessPersonIds string[] required
    • id string required
    • name string required
    • ownerPersonId null | string required
    • sensitive boolean required
  • generatedAt null | string required
  • responders object[] required
    • name string required
    • personId string required
  • responseTargetDays number required
  • source "hr" | "mello" | "starter" required

hr.get

Read one HR request and its messages

POST/api/v1/manage/hr/get

const result = await shuffl.hr.get({
  "caseId": "<caseId>"
});
Request fields (1)
  • caseId string required
Response object
  • case object required
    • articleProposalId null | string optional
    • articleSourceId null | string optional
    • categorizedBy null | "hr" | "mello" optional
    • category null | object optional
      • id string required
      • name string required
      • sensitive boolean required
    • closeOutcome null | "article" | "needs_article" | "no_article" optional
    • createdAt string (date-time) required
    • destinationName string required
    • dueAt null | string (date-time) optional
    • employeePersonId string required
    • id string required
    • ownerPersonId null | string required
    • reopenCount number required
    • replyChannel string required
    • resolvedAt null | string (date-time) required
    • revision number required
    • sharedText string required
    • status "open" | "resolved" | "waiting_on_employee" | "waiting_on_hr" required
    • ticket null | object optional
      • destination null | string required
      • provider string required
      • providerName string required
      • reconnect boolean required
      • state "not_opened" | "open" | "opening" | "resolved" required
      • ticketKey null | string required
      • url null | string required
  • coverage object required
    • approved number required
    • eligible number required
  • events object[] required
    • action string required
    • createdAt string (date-time) required
    • id string required
    • revision number required
  • followUp null | object required
    • hearBack object required
      • email boolean required
      • slack boolean required
    • lastRemindedAt null | string (date-time) required
    • remind "later" | "not_waiting" | "ready" required
    • remindFrom null | string (date-time) required
    • targetDays number required
  • messages object[] required
    • attemptCount number required
    • authorName null | string required
    • authorPersonId null | string required
    • body string required
    • createdAt string (date-time) required
    • deliveryStatus "delivered" | "failed" | "none" | "ready" | "sending" | "suppressed" | "unknown" required
    • id string required
    • kind "employee" | "hr_reply" | "internal_note" required
    • source "helpdesk" | "shuffl" required
  • owner null | object required
    • eligible boolean required
    • name null | string required
    • personId string required
  • ownerEligible boolean required
  • personId string required
  • responder boolean required

hr.list

List the HR requests you asked or can answer

POST/api/v1/manage/hr/list

const result = await shuffl.hr.list();
Request fields (none)

This operation takes no input.

Response object[]
  • category null | object required
    • id string required
    • name string required
    • sensitive boolean required
  • conversationId null | string optional
  • coverage object required
    • approved number required
    • eligible number required
  • createdAt string (date-time) required
  • destinationName string required
  • dueAt string (date-time) required
  • employeeName null | string required
  • employeePersonId string required
  • id string required
  • owner null | object required
    • eligible boolean required
    • name null | string required
    • personId string required
  • ownerPersonId null | string required
  • remindedAt null | string (date-time) required
  • sharedText string required
  • sourceOwnerId null | string optional
  • status "open" | "resolved" | "waiting_on_employee" | "waiting_on_hr" required
  • updatedAt string (date-time) required

hr.mine

List the HR requests you asked, with HR’s latest reply

POST/api/v1/manage/hr/mine

const result = await shuffl.hr.mine();
Request fields (none)

This operation takes no input.

Response object[]
  • createdAt string (date-time) required
  • destinationName string required
  • id string required
  • latestReply null | object required
    • body string required
    • createdAt string (date-time) required
  • sharedText string required
  • status "open" | "resolved" | "waiting_on_employee" | "waiting_on_hr" required
  • updatedAt string (date-time) required

hr.readiness

Check whether HR requests have a destination and someone to answer them

POST/api/v1/manage/hr/readiness

const result = await shuffl.hr.readiness();
Request fields (none)

This operation takes no input.

Response object

The response is object.

hr.settings

Read the HR team name and who answers HR requests

POST/api/v1/manage/hr/settings

const result = await shuffl.hr.settings();
Request fields (none)

This operation takes no input.

Response object
  • canConfigure boolean required
  • candidates object[] required
    • name string required
    • person_id string required
  • destination null | object required
    • categoriesClaimedAt null | string (date-time) required
    • categoriesGeneratedAt null | string (date-time) required
    • categoriesSource "hr" | "mello" | "starter" required
    • name string required
    • responseTargetDays number required
    • revision number required
    • teamId string required
    • updatedAt string (date-time) required
  • personId null | string required
  • responders object[] required
    • name string required
    • person_id string required

hr.shareSources

List your recent Mello conversations that an HR request can include

POST/api/v1/manage/hr/shareSources

const result = await shuffl.hr.shareSources();
Request fields (none)

This operation takes no input.

Response object[]
  • channel string required
  • conversationId string required
  • excerpt string required
  • sourceOwnerId string required

hr.command

Claim, release, reply to, note, categorize, resolve, reopen or remind HR about an HR request

POST/api/v1/manage/hr/command

const result = await shuffl.hr.command({
  "action": "categorize",
  "caseId": "<caseId>",
  "expectedRevision": 0,
  "requestId": "<requestId>",
  "requestKey": "a-new-unique-key"
});
Request fields (9)
  • action "categorize" | "claim" | "note" | "release" | "remind" | "reopen" | "reply" | "resolve" required
  • articleSourceId string optional
  • body string optional
  • caseId string required
  • categoryId string optional
  • closeOutcome "article" | "needs_article" | "no_article" optional
  • expectedRevision number required
  • requestId string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • articleDraft null | object required
      • proposalId null | string required
      • status "prepared" | "unavailable" required
    • caseId string required
    • messageId null | string required
    • revision number required

hr.configure

Change the HR request destination

POST/api/v1/manage/hr/configure

  • Write
  • Permission hr.configure
  • Needs a requestKey
  • Needs confirm set to hr.configure
const result = await shuffl.hr.configure({
  "expectedRevision": 0,
  "name": "<name>",
  "responderPersonIds": [
    "<responderPersonIds>"
  ],
  "confirm": "hr.configure",
  "requestKey": "a-new-unique-key"
});
Request fields (5)
  • expectedRevision number required
  • name string required
  • responderPersonIds string[] required
  • confirm "hr.configure" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • revision number required

hr.deliver

Deliver your HR reply to the employee

POST/api/v1/manage/hr/deliver

  • Write
  • Permission hr.deliver
  • Needs a requestKey
  • Needs confirm set to hr.deliver
const result = await shuffl.hr.deliver({
  "caseId": "<caseId>",
  "messageId": "<messageId>",
  "confirm": "hr.deliver",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • caseId string required
  • messageId string required
  • confirm "hr.deliver" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • queued boolean required

hr.rebuildCategories

Have Mello rebuild the HR request categories from published Knowledge

POST/api/v1/manage/hr/rebuildCategories

const result = await shuffl.hr.rebuildCategories({
  "confirm": "hr.rebuildCategories",
  "requestKey": "a-new-unique-key"
});
Request fields (2)
  • confirm "hr.rebuildCategories" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • categories number required

hr.renameTeam

Rename the HR team employees send requests to

POST/api/v1/manage/hr/renameTeam

const result = await shuffl.hr.renameTeam({
  "name": "<name>",
  "requestKey": "a-new-unique-key"
});
Request fields (2)
  • name string required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • changed boolean required
    • revision number required

hr.retryDelivery

Retry HR request delivery

POST/api/v1/manage/hr/retryDelivery

  • Write
  • Permission hr.retryDelivery
  • Needs a requestKey
  • Needs confirm set to hr.retryDelivery
const result = await shuffl.hr.retryDelivery({
  "messageId": "<messageId>",
  "confirm": "hr.retryDelivery",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • messageId string required
  • confirm "hr.retryDelivery" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • messageId string required

hr.route

Send a request category to a helpdesk queue or back to the Shuffl inbox

POST/api/v1/manage/hr/route

  • Write
  • Permission hr.route
  • Needs a requestKey
  • Needs confirm set to hr.route
const result = await shuffl.hr.route({
  "categoryId": "<categoryId>",
  "connectionId": "<connectionId>",
  "confirm": "hr.route",
  "requestKey": "a-new-unique-key"
});
Request fields (6)
  • categoryId string required
  • connectionId null | string required
  • destinationId string optional
  • sensitiveOptIn false | true optional
  • confirm "hr.route" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • categoryId string required
    • route null | object required
      • connectionId string required
      • destinationId string required
      • destinationLabel string required
      • sensitiveOptIn boolean required

hr.saveCategories

Save the HR request categories, their owners and the response target

POST/api/v1/manage/hr/saveCategories

  • Write
  • Permission hr.saveCategories
  • Needs a requestKey
  • Needs confirm set to hr.saveCategories
const result = await shuffl.hr.saveCategories({
  "categories": [
    {
      "name": "<name>"
    }
  ],
  "responseTargetDays": 0,
  "confirm": "hr.saveCategories",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • categories object[] required
    • accessPersonIds string[] optional
    • id string optional
    • name string required
    • ownerPersonId null | string optional
    • sensitive false | true optional
  • responseTargetDays number required
  • confirm "hr.saveCategories" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • categories number required

hr.share

Share this request with the selected HR responders

POST/api/v1/manage/hr/share

  • Write
  • Permission hr.share
  • Needs a requestKey
  • Needs confirm set to hr.share
const result = await shuffl.hr.share({
  "body": "<body>",
  "destinationRevision": 0,
  "requestId": "<requestId>",
  "responderPersonIds": [
    "<responderPersonIds>"
  ],
  "confirm": "hr.share",
  "requestKey": "a-new-unique-key"
});
Request fields (8)
  • body string required
  • conversationId null | string optional
  • destinationRevision number required
  • requestId string required
  • responderPersonIds string[] required
  • sourceOwnerId null | string optional
  • confirm "hr.share" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • caseId string required

hr.helpdesks.list

List the connected helpdesks and where each request category goes

POST/api/v1/manage/hr/helpdesks/list

const result = await shuffl.hr.helpdesks.list();
Request fields (none)

This operation takes no input.

Response object
  • categories object[] required
    • id string required
    • name string required
    • route null | object required
      • connectionId string required
      • destinationId string required
      • destinationLabel string required
      • sensitiveOptIn boolean required
    • sensitive boolean required
  • connections object[] required
    • connectedAt string (date-time) required
    • id string required
    • label string required
    • lastUsedAt null | string (date-time) required
    • provider "fixture_helpdesk" | "freshservice" | "jira_service_management" | "linear" | "zendesk" required
    • providerName string required
    • publicRule string required
    • routes number required
    • status "connected" | "disconnected" | "needs_attention" required
    • webhook object required
      • body null | string required
      • header null | string required
      • secretFrom "shuffl" | "vendor" required
      • signature "hmac" | "token" required
      • url string required
  • offered object[] required
    • destinationNoun string required
    • docsHref string required
    • fields object[] required
      • label string required
      • name string required
      • optional false | true optional
      • placeholder string optional
      • type "email" | "password" | "text" | "url" required
    • id "fixture_helpdesk" | "freshservice" | "jira_service_management" | "linear" | "zendesk" required
    • name string required
    • publicRule string required
    • steps string[] required

hr.helpdesks.queues

List the queues a connected helpdesk can take HR requests into

POST/api/v1/manage/hr/helpdesks/queues

const result = await shuffl.hr.helpdesks.queues({
  "connectionId": "<connectionId>"
});
Request fields (1)
  • connectionId string required
Response object
  • destinationNoun string required
  • queues object[] required
    • id string required
    • label string required

hr.helpdesks.connect

Connect a helpdesk for HR requests with its token

POST/api/v1/manage/hr/helpdesks/connect

const result = await shuffl.hr.helpdesks.connect({
  "fields": null,
  "provider": "fixture_helpdesk",
  "confirm": "hr.helpdesks.connect",
  "requestKey": "a-new-unique-key"
});
Request fields (4)
  • fields object required
  • provider "fixture_helpdesk" | "freshservice" | "jira_service_management" | "linear" | "zendesk" required
  • confirm "hr.helpdesks.connect" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • connection object required
      • connectedAt string (date-time) required
      • id string required
      • label string required
      • lastUsedAt null | string (date-time) required
      • provider "fixture_helpdesk" | "freshservice" | "jira_service_management" | "linear" | "zendesk" required
      • providerName string required
      • publicRule string required
      • routes number required
      • status "connected" | "disconnected" | "needs_attention" required
      • webhook object required
        • body null | string required
        • header null | string required
        • secretFrom "shuffl" | "vendor" required
        • signature "hmac" | "token" required
        • url string required
    • webhookSecret null | string required

hr.helpdesks.disconnect

Disconnect a helpdesk; its categories go back to the Shuffl inbox

POST/api/v1/manage/hr/helpdesks/disconnect

const result = await shuffl.hr.helpdesks.disconnect({
  "connectionId": "<connectionId>",
  "confirm": "hr.helpdesks.disconnect",
  "requestKey": "a-new-unique-key"
});
Request fields (3)
  • connectionId string required
  • confirm "hr.helpdesks.disconnect" required
  • requestKey string required1 to 128 characters
Response object
  • receipt object required
    • completedAt string (date-time) | null required
    • createdAt string (date-time) required
    • id string (uuid) required
    • operation string required
    • requestKey string required
    • status "running" | "succeeded" | "failed" | "unknown" required
  • result object | null required
    • disconnected boolean required