# Shuffl documentation
---
> Every Shuffl guide and HR playbook in one file. The index with the blog, changelog, glossary and HR templates is https://shuffl.ai/llms.txt; each guide and playbook is also served alone at its Markdown address.
---
# Companies and workspaces
> Keep one workspace for most companies, or add separate spaces for regions, subsidiaries and teams.
Audience: Company owners and administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/companies-and-workspaces
## One company, one or more workspaces
A company is your organization in Shuffl. It holds your company members, administrators, sign-in settings and billing. Most companies need one workspace.
A workspace is where people use Shuffl together. Each has its own People, Knowledge, HR requests, Mello chats, programs, Pulse, praise, communities and celebrations. Add another when a subsidiary, region or team needs to keep that work separate.
Your company shares verified email domains, single sign-on, SCIM provisioning, Slack connections, billing and the product analytics switch. Each workspace keeps its own name, logo, settings, API keys and activity log. Content does not move between workspaces.
## Open Company settings
Company settings are the Company group in Settings; owners and administrators can also open them from the account menu.
Name and logo also holds the product analytics switch and ownership, Members manages company roles and removal, and Billing the plan. Slack, single sign-on, email domains and provisioning are under Workspace → Integrations. Everyone else sees the company’s Workspaces.
## Add a workspace and choose the default
1. Open Settings → Company → Workspaces and choose New workspace. Enter a name, then follow its setup checklist. Owners and administrators also find New workspace in the workspace picker.
2. On the Workspaces page, open a workspace’s actions menu and choose Rename to change its name.
3. Choose Set as default on the workspace that new domain and single sign-on members should enter.
4. Changing the default affects future joins only. It does not move people or records, and Slack keeps its own mapping.
5. Delete workspace stops it immediately; type its name to confirm. You can restore it for 30 days, then Shuffl permanently erases its People, Knowledge, programs and history.
## Switch workspaces or companies
The workspace picker in your account menu lists the workspaces you can use in the current company. On a phone, tap your picture at the top right, then the workspace row.
To choose a company, click your picture at the top right, then the company row. It opens the last workspace you used there, or the company’s workspace list.
## Create another company
To start a separate organization, company owners and administrators choose New company in the account menu, enter the name and choose Create company. Shuffl creates it with a first workspace of the same name.
To add a workspace to your current company instead, use New workspace in the workspace picker.
## Delete or restore a company
A company owner can open Settings → Company → Name and logo, choose Delete company, review the affected workspaces and type the company name. The company and all its workspaces stop immediately. Your personal account and other companies stay.
An owner can choose the deleted company in the account menu and Restore company for 30 days. Workspaces return paused so you can review their programs, then resume each from Settings → Company → Workspaces.
After 30 days, Shuffl permanently erases the company and everything in it. A paid subscription must finish cancellation before company deletion is available.
## Who can manage what
A company owner or administrator can manage Company settings and every workspace in that company. Only owners can change company roles, transfer ownership or delete a company and all its workspaces. A company must always have at least one owner.
A workspace administrator manages their own workspace. That role does not grant Company settings or access to another workspace. Ordinary company members can use only the workspaces they have joined.
Settings → Company → Members lists these company roles. Use People inside a workspace to manage its employee access and workspace roles.
## How people join
An invitation joins the company and the workspace named in the invitation. An Administrator invitation grants a workspace role, not a company role.
A verified email domain joins people to the company and its default workspace. Single sign-on also uses the default workspace, where the person must already be listed with their work email and enabled access.
New SCIM provisioning goes to the default workspace under the company’s access policy. Changing the default leaves existing provisioning assignments in place.
Slack sign-in uses the Shuffl workspace mapped to that Slack connection. It may be different from the default. Employee access rules still apply.
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
## Move or remove people
To give someone access to another workspace, invite them from that workspace’s People page. Their Knowledge, chats and HR history stay with the original workspace.
Leaving a workspace keeps company membership. Someone who leaves their last workspace sees the company’s workspace list and can ask for an invitation.
Removing a member in Company settings removes their access to the company and all its workspaces. Only owners can remove administrators or other owners, and the last owner must transfer ownership first.
## Connect the right Slack workspace
In Settings → Workspace → Integrations → Slack, the Slack workspaces table lists each Shuffl workspace and its connection state. Choose Manage on a row, then connect the Slack workspace that should use it.
Connect individual Slack workspaces or one Enterprise Grid organization. On the same page, map granted Slack workspaces together to share people and settings, or separately for different regions or subsidiaries.
- [Connect Slack](https://shuffl.ai/docs/slack)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Connect Slack](https://shuffl.ai/docs/slack)
- [Workspace settings](https://shuffl.ai/docs/settings)
- [Roles and permissions](https://shuffl.ai/docs/roles-and-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Set up your workspace
> Name your company, set up its first workspace and pick up where you left off.
Audience: Workspace administrators
Kind: Tutorial
Canonical: https://shuffl.ai/docs/getting-started
## Name your company
1. Create your Shuffl account with your work email and a password, or sign in with Google or Slack. Verify your email, then sign in.
2. Name your company. Shuffl suggests a name from your work email and creates the company with its first workspace.
3. If you were invited, follow the invitation instead. Company owners and administrators can add another workspace later.
4. Shuffl opens workspace setup, one of the pages administrators, HR responders and Knowledge verifiers reach from the HR workspace. Employees use Home.
- [Create an account](https://shuffl.ai/sign-up)
- [Open workspace setup](https://shuffl.ai/app/setup)
## Work through the checklist
1. Connect Slack. Choose Connect Slack and approve the app in Slack. Everyone in your Slack workspace then appears in People, waiting for access.
2. Add your handbook. Choose Upload a file or Add a web page, or drop a file anywhere on the page. Check the draft, then publish it.
3. Try Mello. Ask something your handbook answers, on the web or in a direct message to Shuffl in Slack. A cited answer completes the step.
4. Invite a coworker. Their access turns on when they accept, or turn it on for people already waiting in People.
5. Owners get HR requests by default. If nobody can receive them, open People, choose a person and turn on HR responder under Roles.
6. To hand setup to Claude Code or another agent, choose Show prompt, then Copy prompt, and paste it into the agent.
7. It works through the steps over MCP and asks before it publishes or invites anyone.
8. Under Also turn on, start Pulse, Connections, Onboarding, Celebrations and Communities when you’re ready. Each has its own guide.
Workspace setup lists what a workspace needs before employees get value from it. Progress follows your saved settings, so you can leave and come back.
- [Open workspace setup](https://shuffl.ai/app/setup)
- [Publish your first source](https://shuffl.ai/docs/knowledge)
- [Choose HR responders](https://shuffl.ai/docs/hr-requests)
## Bring your Slack channels over
If another app already runs coffee chats, shoutouts or celebrations in your Slack, workspace setup offers Bring them over.
Intros become a Connections program, shoutouts become a praise channel with the past year imported, and a celebrations channel gets birthdays and anniversaries once you turn them on. Choose Leave it to skip a channel.
To avoid matching people who already met, add the other app’s CSV report of past intros on the same screen. Shuffl keeps only who met whom, never the names or emails in the file.
Then remove the other app from Slack. Each Connections program starts once that app leaves its channel, so nobody gets two introductions.
People whose birthday the other app celebrated are asked privately whether Shuffl should keep it. For a private channel, type /invite @Shuffl in it first.
Slack message, Keep your birthday? (Someone the previous app celebrated, privately; Once, after switching from another app):
```text
Your birthday was celebrated in #celebrations on 14 March. Want Shuffl to keep celebrating it?
```
- [Bring your Slack channels over](https://shuffl.ai/app/setup/slack-channels)
## Resume after an interruption
Sign back in and reopen Workspace setup in the same workspace. Retry the failed step there rather than creating a new workspace.
If progress moves backward, check the setting behind the step. A withdrawn document, a passed review date, a removed responder or a suspended employee reopens a step.
Slack’s Home tab for Shuffl shows the same progress to administrators, with a Continue setup button.
- [Open workspace setup](https://shuffl.ai/app/setup)
- [Find a recovery step](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Companies and workspaces](https://shuffl.ai/docs/companies-and-workspaces)
- [Connect Slack](https://shuffl.ai/docs/slack)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Roll out Shuffl to your company](https://shuffl.ai/docs/rollout)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Roll out Shuffl to your company
> One order for launching Shuffl: get Mello ready, invite people, tell your team, then turn on programs and watch the first week.
Audience: HR administrators and company owners
Kind: How-to guide
Canonical: https://shuffl.ai/docs/rollout
## Before launch: get Mello ready
1. Open Workspace setup from the HR workspace (Settings → Setup) and choose Connect Slack.
2. Everyone in your Slack workspace appears in People, waiting for access. Leave them waiting: turning access on sends each person a welcome message.
3. Add the 5 to 10 policies people ask HR about most, such as time off, expenses and benefits.
4. Start from a template or import your own file, check the text, set the audience to Everyone in this workspace and publish.
5. Choose who answers HR requests. Owners are HR responders from the start.
6. In People, turn on HR responder for the rest of the HR team, and Knowledge verifier for reviewers who aren’t administrators.
7. If another app already runs coffee chats, shoutouts or celebrations in your Slack, use Bring them over in workspace setup so nothing runs twice.
Do this a week or two before anyone else hears about Shuffl. Nothing here messages employees, so you can take your time.
- [Open workspace setup](https://shuffl.ai/app/setup)
- [Connect Slack](https://shuffl.ai/docs/slack#connect)
- [Add a source](https://shuffl.ai/docs/knowledge#add)
- [Choose HR responders](https://shuffl.ai/docs/hr-requests#responders)
## Ask Mello what your team will ask
1. Write down the ten questions HR hears most often, in employees’ words, like “how many days off do I get?”.
2. Ask each one in Chat, and a few in a direct message to Shuffl in Slack. A cited answer also completes Try Mello in workspace setup.
3. Open Supporting sources on each answer. If Mello found nothing or cited the wrong policy, fix the source: publish it, add the missing detail, or widen its audience.
4. Ask again until every question gets a cited answer. Reviewers see more than employees, so check each source’s audience.
- [Open Chat](https://shuffl.ai/app/chat)
- [What Mello can and cannot answer](https://shuffl.ai/docs/ask-mello#what-mello-knows)
- [Publish deliberately](https://shuffl.ai/docs/knowledge#publish)
- [Read citations and fix the source](https://shuffl.ai/docs/write-knowledge#test)
## Invite people and choose who manages
Choose one way in for most people, and get it ready now so it can be switched on at launch.
Slack: everyone is already in People. On launch day, enable them in People with Enable access for N people.
Email domain: verify your domain in Settings → Workspace → Integrations → Email domains, and anyone signing in with that work email joins with access. DNS can take a while, so verify it ahead.
SCIM: connect your identity provider in Settings → Workspace → Integrations → Provisioning and assign the people or groups that belong in Shuffl. Until you choose who gets workspace access, they arrive with access suspended.
Invitations suit a small group or a pilot: People → Invite, or Invite all beside it. Each is sent at once.
Keep administrators few: two or three people who run HR and IT. Company roles live in Settings → Company → Members, and HR responders and Knowledge verifiers don’t need to be administrators.
- [How people get in](https://shuffl.ai/docs/employee-access#ways-in)
- [Join by email domain](https://shuffl.ai/docs/employee-access#email-domains)
- [Provision people from your directory](https://shuffl.ai/docs/employee-access#provisioning)
- [Who can manage what](https://shuffl.ai/docs/companies-and-workspaces#roles)
## Launch: tell your team
Pick a day and send the announcement from someone people know, in a channel everyone reads and by email for anyone who doesn’t use Slack. Shuffl never posts it for you.
Today has a card, Tell your team what they can ask, with a post built from what Mello can do in your workspace.
Choose Copy post, edit and share it, then choose I posted it. The example below adds two lines; use questions from your own policies.
Send the announcement first, then turn access on in the same hour, so the welcome messages arrive while people are reading it.
```text
Meet Mello, our new HR assistant in Slack and Shuffl.
Ask it things like:
• What’s our time off policy?
• How do I submit an expense?
• Who should I talk to about benefits?
It answers from our approved policies and shows its sources. If it can’t help, it helps you send the question to HR. Your chats are private: managers, HR and admins can’t read them.
Message Mello in Slack (under Apps), or open Shuffl on the web. You’ll get a short welcome from Shuffl today with a few first steps.
Questions about the rollout? Reply here or message the People team.
```
- [Open Today](https://shuffl.ai/app/insights)
- [Launch announcement template](https://shuffl.ai/templates/mello-launch-announcement)
- [What employees see in Slack](https://shuffl.ai/docs/slack#welcome)
## What employees see on day one
In Slack, each person gets one welcome message when their access is turned on or they first open the app.
It says the chat is private and deleted after 30 days, and lists three first steps. People Shuffl can’t reach in Slack get an email instead.
On the web, Home’s For you list reads Your first week. It asks for a photo and a line about you, a community, a hello, a calendar and a first question for Mello. Each step ticks off as it’s done.
Expect the first questions within the hour. Keep an eye on the Inbox that day, so the first HR requests get a quick reply.
Slack message, Employee welcome (Each employee, once, in a DM from Shuffl; When their access is turned on or they first open Shuffl):
```text
Hi, I’m Mello. Ask me about time off, benefits, policies or who’s who. This chat is private.
```
- [Home and For you](https://shuffl.ai/docs/around-shuffl#home)
- [Who can read your chats](https://shuffl.ai/docs/ask-mello#privacy)
## Turn on programs in order
1. Pulse, in week one or two. Choose Start pulse; the default, every Tuesday and Thursday at 10:00, suits most teams.
2. Answers are confidential and results show only for groups of 7 or more.
3. Praise, next. Turn on Read praise channels and add the channel where people already thank each other; Shuffl brings in the last year of thanks.
4. Connections, once people know Mello. Start from Mello’s suggestion or a template, pick who takes part, and start with every 2 weeks.
5. Celebrations, at least a week before the first post, since each person is asked a week before their day whether to share it.
6. Start with private notes or a single channel.
7. Onboarding, before your next hire starts. Choose the accountable HR responder, enroll the hire with a buddy and approve their messages. Nothing goes out until you approve it.
Turn programs on one at a time, about a week apart, so each one gets noticed and you can see how people respond before the next. Every program is optional and each runs in Slack.
- [Run Pulse](https://shuffl.ai/docs/pulse#administrators)
- [Set up Praise](https://shuffl.ai/docs/praise#administrators)
- [Create an introduction program](https://shuffl.ai/docs/connections#program)
- [Turn on Celebrations](https://shuffl.ai/docs/celebrations#administrators)
- [Create a playbook](https://shuffl.ai/docs/playbooks#program)
## The first week: where to look and what to fix
1. Today, in the HR workspace, every morning: HR requests waiting, Knowledge drafts to review and sources to re-check. Enter Minutes a typical HR question takes you to see time saved.
2. Inbox. Answer HR requests and review Knowledge drafts: proposals Mello drafted from what your team asked and how HR replied.
3. Knowledge → Insights. Missing guidance and Questions to test Mello on show where Mello found nothing or got a Bad answer. Fix the source, then ask again in Chat.
4. People. Check Members awaiting access and anyone listed as Not invited or Suspended, and enable the people who should be in.
5. At the end of the week, set up the HR digest under Settings → Notifications so the numbers come to you, and decide which program to turn on next.
- [Today](https://shuffl.ai/docs/impact#today)
- [Knowledge Insights](https://shuffl.ai/docs/knowledge#insights)
- [Verify what Mello proposes](https://shuffl.ai/docs/knowledge#verify)
- [Set up the HR digest](https://shuffl.ai/docs/impact#digest)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Culture, what Mello handled and the HR digest](https://shuffl.ai/docs/impact)
- [Write Knowledge that Mello answers well](https://shuffl.ai/docs/write-knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Connect Slack
> Connect the Shuffl app to Slack, approve new permissions, and know what works on the web without it.
Audience: Workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/slack
## Connect Slack
1. As a company owner or administrator, open Settings → Workspace → Integrations → Slack.
2. Choose Manage on the Shuffl workspace’s row, then Connect Slack. A Slack owner or administrator may need to approve the app.
3. Shuffl reads messages sent to it, @Shuffl mentions and its own threads, and the member list with email addresses.
4. It also reads the praise channels an administrator picks, with up to 365 days of history, and no other channels. Privacy and data lists everything it reads.
5. Everyone in your Slack workspace, and anyone who joins later, appears in People waiting for access; bots, guests and deactivated accounts are left out.
6. Titles and time zones come from Slack profiles.
7. The person who connected Slack gets a welcome message with setup as a checklist. Send me the welcome again on that page resends it.
Shuffl is listed on the Slack Marketplace, where Slack admins can review the app and the permissions it asks for. Connect from Shuffl’s Slack settings so the app joins the right Shuffl workspace.
Each Slack connection belongs to a company. Enterprise Grid lets you connect the organization once and map its Slack workspaces to Shuffl workspaces; newly granted ones wait for a company administrator to map them.
Slack message, Welcome for whoever installs Shuffl (The person who connects Slack, in a DM from Shuffl; Right after Slack is connected):
```text
Welcome to Shuffl. Setup is 2 of 4 done: finish it so your team can ask Mello.
```
- [Open Slack settings](https://shuffl.ai/app/settings/company/slack)
- [Shuffl on the Slack Marketplace](https://slack.com/marketplace/A5W6QMNK0-shuffl)
## Approve new permissions
When a feature needs a new Slack permission, Manage shows Slack needs updated permissions and what the reconnect turns on. Choose Reconnect Slack and approve it; nothing else changes.
The Slack settings page shows the same state on the connection card: Connected, Connected, permissions needed, Reconnect required or Not connected.
## What employees see in Slack
The Shuffl app’s Messages tab is a private chat with Mello. Its Home tab leads with For you, the same list as Home on the web, three at a time.
Then come Today’s question, your people (buddy, mentor, latest introductions, people to meet), praise with its change and newest badge, and teammates’ days this week.
Managers also see their new hires’ 30/60/90 plans. Administrators see overdue Pulse actions and hires falling behind under Waiting on you, and Pulse answers as a bar with the change since the last question.
HR responders, Knowledge verifiers and administrators see a count of what waits on them first, then HR requests and Knowledge to review. Administrators also get Your workspace, with setup progress, Pulse participation and buttons to People, Praise and Settings.
Each employee gets one welcome message when their access is turned on or they first open the app. It says the chat is private and deleted after 30 days, and lists three first steps.
In a channel, mention @Shuffl for an answer in a thread from Knowledge published to everyone. Anything personal is answered only in a direct message.
In Slack’s Agent panel, Shuffl shows what it is doing while it answers, a Stop button and suggested questions.
The message examples in this guide show what employees receive and when.
Slack message, Employee welcome (Each employee, once, in a DM from Shuffl; When their access is turned on or they first open Shuffl):
```text
Hi, I’m Mello. Ask me about time off, benefits, policies or who’s who. This chat is private.
```
Slack message, Home tab for employees (Each employee, on the Shuffl app’s Home tab; Every time they open it):
```text
Shuffl Home
```
Slack message, Everything for you (An employee who pressed See all under For you; When they open it from the Home tab):
```text
For you
```
Slack message, All introductions (An employee who pressed See all under Recent introductions; When they open it from the Home tab):
```text
Your introductions
```
Slack message, Home tab for HR and admins (HR responders, Knowledge reviewers and administrators; Every time they open it):
```text
Shuffl Home
```
Slack message, Hello in a channel (A channel; When someone adds Shuffl to it):
```text
Mello is here. Mention <@UMELLO> with a question, or message me directly for private questions.
```
## Shuffl profile links on Slack profiles
Shuffl can link each person’s Shuffl profile on their Slack profile. It needs a paid Slack plan, profile-editing permission and a Link field named Shuffl profile; the Slack settings page shows which are in place. Turn the switch on and choose Sync now.
- [Open Slack settings](https://shuffl.ai/app/settings/company/slack)
## Enable people who join a program channel
Program channel access enables someone who is waiting for access as soon as they join a channel that a Connections program uses. Leave it off to enable people by hand in People.
## What works without Slack
Chat, HR requests, Knowledge, People, profiles, Praise and every report and setting work on the web. Pulse, HR replies, the HR digest and Shuffl’s emails can go by email. Connections intros, onboarding, praise and celebration messages are Slack only for now.
Connections introductions, praise captured from channels, celebration posts in a channel and community channels need Slack connected and the person’s Slack account linked in People.
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Invite and enable employees
> Invite people or let them join, check they arrived as the right person, and enable employee access.
Audience: Workspace administrators and invited employees
Kind: How-to guide
Canonical: https://shuffl.ai/docs/employee-access
## How people get in
People arrive four ways: from Slack, from a directory sync or SCIM provisioning, by joining with a verified email domain, or through Invite and Add person.
App access on each row says where someone stands, such as Active, Access pending, Invited or Suspended. A Not invited row has its own Invite button.
Someone who accepts an invitation or joins with a verified email domain gets access straight away. Everyone else waits under Members awaiting access until an administrator or a directory policy enables them.
## Send and accept an invitation
1. Administrator: open People and choose Invite. Paste work emails or add people from the directory, choose Employee or Administrator and select Send invitation.
2. Pending invitations lists open ones to copy or cancel.
3. Invite all, beside Invite on People, invites as employees everyone in the directory with an email and no account or pending invitation.
4. Employee: follow the invitation link, sign in or create an account with the invited email, and verify it. Choose Accept invitation.
5. The invitation page says whether the link is ready, expired, sent to a different account or already accepted.
6. Accepting joins the company and the workspace named in the invitation and turns your access on.
7. If an administrator suspended or denied access earlier, you see Your access is pending, with Check again.
- [Invite people](https://shuffl.ai/app/people?invite=1)
## Enable access for the right person
1. Administrator: open People and choose Review access under Members awaiting access.
2. Shuffl links each account to the person with the same work email, or offers Create employee profile. If two people share the email, pick the right one.
3. To move an account to a different person, open the person, expand Connected accounts, choose Disconnect app, then open the right person and choose Link app account.
4. Expand Employment and access, enable Employee access, enter a reason and choose Save access. Enable access for N people enables waiting Slack members at once.
5. Employee: reopen the workspace and try Chat. Once your Slack account is linked too, Slack chats show in your web history.
- [Open People](https://shuffl.ai/app/people)
- [Open Chat](https://shuffl.ai/app/chat)
## Let people at your company join by email domain
In Settings → Workspace → Integrations → Email domains, choose Add a domain and add the DNS record Shuffl shows at your registrar, then Check DNS record.
Once Verified, anyone who signs in with that domain joins the company’s default workspace with access. Remove a domain to stop new joins.
- [Open Email domains](https://shuffl.ai/app/settings/company/domains)
## Provision people from your directory
People → Sync connects HR systems and directories with a key or a sign-in and reads them daily, or when the provider sends a change. Shuffl never writes back.
Settings → Workspace → Integrations → Provisioning takes a SCIM 2.0 connection from Okta, Microsoft Entra ID, OneLogin, JumpCloud or another provider.
Choose New SCIM connection, copy the base URL and token into your identity provider and assign people or groups. Rotate tokens within 90 days.
Under Who gets workspace access choose Everyone assigned to this app or Selected groups only; until you do, people arrive suspended in the default workspace. Removing someone in your identity provider takes effect at once; restoring them doesn’t undo a manual suspension.
To bring a pushed group into People → Groups, choose Groups on the SCIM card under People → Sync and turn it on.
It comes into every workspace of the company, marked From provisioning, with members following your identity provider. Turned off, it stays as a list.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Sync people from your HR system](https://shuffl.ai/docs/people-sync)
## Sign in with your identity provider
In Settings → Workspace → Integrations → Single sign-on, choose Add connection, pick SAML or OpenID Connect and verify it with its DNS TXT record.
The dialog has steps for common providers and shows the values they ask for. SAML assertions must be signed with SHA-256.
Single sign-on proves who someone is; People still decides who gets in. It admits someone only when the default workspace lists exactly one person with that email and enabled access. Password sign-in keeps working while you test.
Everyone can also add a passkey or an authenticator app under Settings → Account, whichever way they sign in.
- [Open Single sign-on settings](https://shuffl.ai/app/settings/company/sso)
## Recover invitation or access problems
An expired or cancelled invitation needs a new one. An administrator who sees You’re not in People yet can choose Add me to People.
A personal email is a different account: invite the work email or link it. Suspended usually means a deactivated Slack account or ended employment; the access card says why.
- [Find a recovery step](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [People and the org chart](https://shuffl.ai/docs/people)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Set up single sign-on and directory provisioning
> Connect your identity provider so people sign in with their work account, verify your email domains, and provision and remove people with SCIM.
Audience: IT administrators and company owners
Kind: How-to guide
Canonical: https://shuffl.ai/docs/single-sign-on
## Before you start
Three company settings under Workspace → Integrations work together.
Single sign-on lets people sign in with your identity provider, Email domains lets anyone with a verified work email join, and Provisioning lets your identity provider create and suspend people. Only company owners and administrators can change them.
All three use the company’s default workspace. Check which one that is first: people who join or are provisioned land there.
Single sign-on proves who someone is; People decides who gets in. Someone gets in only when the default workspace’s People lists exactly one person with that email, with access enabled.
So set up People first, then add single sign-on. Email and password sign-in keeps working throughout.
- [Choose the default workspace](https://shuffl.ai/docs/companies-and-workspaces#workspaces)
## Add a single sign-on connection
1. In Settings, open Workspace → Integrations → Single sign-on and choose Add connection.
2. Under Identity provider, choose yours, or Another provider. The dialog’s steps change to match.
3. Enter the Email domain your people sign in with, such as example.com; subdomains are covered too. Each domain has one connection, up to five per company.
4. Choose a Protocol. OpenID Connect needs a client ID, client secret and issuer URL; SAML 2.0 needs your provider’s metadata XML.
5. Keep the dialog open. Under 1. Create the app, copy the Redirect URI (OpenID Connect) or the ACS URL and Entity ID (audience) (SAML), and the Login URL, into your provider.
6. Closing the dialog changes these addresses, so finish in one go.
7. Under 2. Paste what your provider gives you, enter the Issuer URL, Client ID and Client secret, or the Identity provider metadata XML, and choose Add connection.
8. The secret is never shown again.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
## Settings for each identity provider
Every provider must send the work email: the email claim with the email and profile scopes for OpenID Connect, or the NameID in email address format for SAML.
SAML assertions must be signed with SHA-256; a signed response alone, or SHA-1, is refused. Assign the app to the people or groups who should sign in.
JumpCloud: under SSO Applications, add a Custom Application with OIDC. Paste the redirect URI into Redirect URIs and login URL into Login URL, keep Client Authentication Type at Client Secret Basic and turn on the email and profile scopes.
Shuffl fills in the issuer. For SAML, set SAMLSubject NameID to email (emailAddress format) and sign Assertion and Response with RSA-SHA256.
Okta: under Applications, choose Create App Integration, then OIDC and Web Application. Paste the redirect URI into Sign-in redirect URIs and login URL into Initiate login URI; the issuer is your Okta domain.
For SAML 2.0, paste the ACS URL into Single sign-on URL and entity ID into Audience URI, with Name ID format EmailAddress and Application username Email.
Microsoft Entra ID: register an app (App registrations → New registration) with the redirect URI as a Web redirect URI, a client secret and the email optional claim (Token configuration).
Issuer: https://login.microsoftonline.com//v2.0. SAML: in a non-gallery Enterprise application, Identifier takes the entity ID, Reply URL the ACS URL, and Unique User Identifier (Name ID) is user.mail.
OneLogin: add the OpenId Connect (OIDC) app, paste the login URL into Login Url and redirect URI into Redirect URI’s, and set Token Endpoint Authentication Method to Basic.
The issuer is your OneLogin domain plus /oidc/2. For SAML, use SAML Custom Connector (Advanced): SAML nameID format Email, SAML signature element Both, SAML signature algorithm SHA-256 (not the default SHA-1).
Google Workspace (SAML only): in the Admin console, under Apps, then Web and mobile apps, add a custom SAML app and download the IdP metadata.
Paste the ACS URL, entity ID and, into Start URL, the login URL. Set Name ID format to EMAIL and Name ID to Primary email, then turn the app on for the right organizational units.
Rippling has steps in the dialog. For another provider, create an OpenID Connect web app with the authorization code flow and a client secret. Or create a SAML 2.0 app that sends the email as the NameID and signs the assertion with RSA-SHA256.
## Verify your domain and test sign-in
1. The new connection reads Waiting for DNS. Add the TXT record it shows (Record name and Record value) at your DNS provider. Single sign-on stays off until Shuffl finds it.
2. Choose Check DNS record. When it is found, the connection reads Verified; DNS can take a while, so try again later if not.
3. Make sure the tester is in the default workspace’s People, with the same work email and access enabled.
4. In a private browser window, open the Shuffl sign-in page, choose Sign in with SSO, enter the work email and choose Continue with SSO.
5. To start from your provider’s app launcher, use the Login URL.
6. Every value your provider needs stays under Identity provider settings on the connection, plus the Service provider metadata URL for SAML.
7. A connection cannot be edited. To change the secret, metadata or protocol, choose Remove, add it again and update your provider with the new addresses.
8. Removing it stops single sign-on for that domain; people already signed in stay signed in, but need another sign-in method next time.
- [Open the sign-in page](https://shuffl.ai/sign-in)
## Let people join by email domain
1. In Settings, open Workspace → Integrations → Email domains, enter your domain under Add a domain and choose Add domain. Public email providers such as gmail.com can’t be added.
2. Add the TXT record shown at your DNS provider and choose Check DNS record. A domain that a verified single sign-on connection already covers is verified straight away.
3. From then on, anyone who signs in with a verified email on that domain, by any method, joins the company and its default workspace with access.
4. Suspended people and people whose employment ended stay that way.
5. With single sign-on, that means anyone your identity provider lets through can join without being in People first.
6. To let People or provisioning decide who gets in, leave the domain out. Remove a domain to stop new joins.
- [Open Email domains](https://shuffl.ai/app/settings/company/domains)
## Provision people with SCIM
1. In Settings, open Workspace → Integrations → Provisioning. If it says Provisioning isn’t enabled yet, contact Shuffl from Help, and use People Sync in the meantime.
2. Choose New SCIM connection, tick I will store this token in an approved identity provider for this company, and choose Create provisioning token.
3. Copy the token, shown once, then choose I’ve saved the token.
4. In your identity provider, turn on SCIM 2.0 provisioning with the SCIM base URL and the token as a bearer token.
5. Okta calls these SCIM connector base URL and HTTP Header authentication; Entra ID, with Provisioning Mode Automatic, Tenant URL and Secret Token; OneLogin, SCIM Base URL and SCIM Bearer Token.
6. Turn on creating, updating and deactivating users, send the work email as the user name, assign the people who belong in Shuffl and push the groups you need.
7. Google Workspace doesn’t send SCIM to custom apps; connect it under People → Sync, where Microsoft 365 can also connect with one admin sign-in.
8. Back in Shuffl, under Who gets workspace access?, choose Everyone assigned to this app, or Selected groups only and tick groups after Refresh groups, then choose Save access policy.
9. Until then, provisioned people are in People without access.
10. To use a pushed group in Shuffl too, open People → Sync, choose Groups on the SCIM card and turn it on.
11. It becomes a synced group on People → Groups in every workspace of the company, marked From provisioning. Giving access and bringing a group in are separate choices.
12. Someone already in People with the same work email is matched, not added twice, and keeps their history.
13. Someone you suspended by hand stays suspended until you restore them. If two people share that email, change one first, or it can’t be provisioned.
14. Tokens expire after 90 days. Choose Rotate token, save and test the new token in your provider, then Revoke the old one. A connection can have two active tokens.
- [Open Directory provisioning](https://shuffl.ai/app/settings/company/provisioning)
## What provisioning changes when people leave
Provisioning creates each new person in the default workspace’s People, with member access when the access policy allows, and keeps their name and email current.
Managers, employment details and admin roles stay yours to manage in Shuffl. Changing the default workspace later doesn’t move people already provisioned.
Deactivating or deleting someone in your identity provider, or removing them from the app or every selected group, suspends their access and ends their Shuffl sessions right away.
They stay in People as Suspended, with their history; as with any suspension, queued messages are cancelled and agent keys revoked.
Reactivate or reassign them and access comes back by itself, unless an administrator changed it in Shuffl meanwhile or their employment ended.
Revoking a token stops requests made with it; people keep their access. Retire connection stops the connection for good and removes the access it granted, though people and their history stay.
- [Suspend or restore someone in People](https://shuffl.ai/docs/people#administrators)
## Fix sign-in and provisioning problems
Single sign-on is not set up for that email domain: no verified connection matches the email. Check the domain’s spelling, or add a connection for the other domain.
Your company’s single sign-on is not finished yet: the TXT record hasn’t been found; choose Check DNS record.
Your identity provider sent an email address your company’s single sign-on does not cover: often an Entra ID user principal name instead of the work email. Map the email as described above.
Your identity provider’s sign-in could not be verified: usually an unsigned or SHA-1 SAML assertion, or old metadata. Fix the signing, then remove and re-add the connection.
Someone signs in but cannot use the workspace: they aren’t in the default workspace’s People, their access is off, two people share their email, or an administrator disconnected that account. Fix them in People, or verify the domain under Email domains.
A provisioned person has no access: with Selected groups only, they must be in a ticked group; choose Refresh groups after pushing one. Someone an administrator suspended or marked as left stays that way until an administrator changes it.
Shuffl refuses a domain another Shuffl company has verified; if it is yours, contact Shuffl. If provider requests stop working, check the token hasn’t expired or been revoked; Connection history and each token’s Last used date show what happened.
- [Enable access for the right person](https://shuffl.ai/docs/employee-access#link)
- [Contact Shuffl](https://shuffl.ai/docs/troubleshooting#support)
## Related guides
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Companies and workspaces](https://shuffl.ai/docs/companies-and-workspaces)
- [People and the org chart](https://shuffl.ai/docs/people)
- [Find a recovery step](https://shuffl.ai/docs/troubleshooting)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Find a recovery step
> Fix common sign-in, setup, knowledge, access and HR sharing problems.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/troubleshooting
## I cannot sign in or accept an invitation
Use your invited work email, finish email verification and check you are opening the right workspace. If your invitation expired or was cancelled, ask an administrator for a new one. Email and password sign-in works when single sign-on is down.
- [Sign in](https://shuffl.ai/sign-in)
- [Reset your password](https://shuffl.ai/forgot-password)
- [Check invitation and access steps](https://shuffl.ai/docs/employee-access)
## I joined but cannot use the workspace
Check both the company and the workspace in the account menu. An invitation joins its named workspace, a verified email domain joins the default workspace, and Slack sign-in uses the workspace mapped to that Slack connection.
If you see Your access is pending, ask an administrator to link your account to the right person and enable access, then choose Check again.
If your access is suspended, ask them to check your record in People. With no workspace membership, the workspace list shows where to ask for an invitation.
An administrator with no person of their own sees You’re not in People yet on Me, Praise and Celebrations. Choose Add me to People. Anyone else sees Open People and should ask an administrator to add them.
- [Complete account linking and access](https://shuffl.ai/docs/employee-access#link)
## Setup stopped partway through
Reopen Workspace setup in the saved workspace and follow the step that needs attention; don’t create another workspace to retry. If Slack shows Reconnect required, choose Reconnect Slack and approve the scopes.
- [Open workspace setup](https://shuffl.ai/app/setup)
- [Resume workspace setup](https://shuffl.ai/docs/getting-started#resume)
## An answer or source is unavailable
Ask a Knowledge verifier to check that the source is published for your audience, effective and not past its review date. If nothing published fits your situation, send a reviewed request to HR.
An answer that stopped partway shows Retry answer; a stopped one shows Ask again. In Slack, send the question again.
If Mello can’t answer at all, Chat says Mello can’t answer right now. Choose Ask HR: your question is carried over, you review it, and Send to HR shares it as a private HR request.
- [Check publication and dates](https://shuffl.ai/docs/knowledge)
- [Recover a connected source](https://shuffl.ai/docs/connected-sources#recover)
- [When Mello can’t answer](https://shuffl.ai/docs/what-mello-can-do#offline)
## HR sharing is unavailable or interrupted
The workspace needs an HR responder; if there is none, contact HR the usual way. After an interrupted submission, check HR requests in your Chat history or the Slack thread before sending another.
- [Review the HR request flow](https://shuffl.ai/docs/hr-requests)
## Shuffl does not answer in Slack
If Shuffl does not answer in Slack, check that your Slack account is linked to your person in People and your access is enabled. The app’s Home tab says when it is not.
If a file you attached is ignored, an administrator needs to reconnect Slack with file access.
- [Connect Slack](https://shuffl.ai/docs/slack)
## I still need product help
In the app, choose Help in the account menu to open Help & feedback. Search help finds a guide.
Contact Shuffl asks about the product or reports a problem; Mello first shows any guide that answers it, then you choose That answers it or Send to Shuffl anyway. Your conversations has our replies.
Include the page, what you tried and the error you saw. Leave out passwords and private employee documents. Shuffl support cannot see your workspace’s HR requests.
Slack message, Support reply (Whoever wrote to Shuffl support; When support answers):
```text
Shuffl support replied to “Calendar times look off”
Thanks for flagging this. We fixed the calendar sync, so new rounds will show the right times.
```
- [Open your workspace](https://shuffl.ai/app)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Ask Mello
> Ask about work in Chat or Slack, read the sources behind an answer, and get help from HR without leaving the conversation.
Audience: Everyone using Shuffl
Kind: Tutorial
Canonical: https://shuffl.ai/docs/ask-mello
## Ask a question
1. On the web, type in the box at the top of Home or open Chat.
2. In Slack, send a direct message to Shuffl. On a phone, tap Mello, the raised button in the middle of the bottom bar.
3. While Mello works it shows what it is doing, such as Searching company knowledge. Choose Stop answer to stop it.
4. When a question could mean more than one thing, Mello offers two to four choices to tap, or you can type your own reply.
5. Open Supporting sources to see the passages it relied on; a citation opens the published source.
6. Ask a follow-up in the same chat, or tap one of up to three suggested questions under an answer.
7. A message sent while Mello is writing waits in a queue; choose Send now to interrupt with it.
8. Attach a PDF, Word, PowerPoint, Markdown or text file to ask about it. In Slack, an administrator may first need to reconnect Slack with file access.
Mello is Shuffl’s assistant. Ask it about time off, benefits, expenses, policies or who is who. It answers from the Knowledge your company published for you and from People, and cites its sources.
- [Open Chat](https://shuffl.ai/app/chat)
## What Mello can and cannot answer
Mello uses only sources published to an audience that includes you, between their effective and review dates. If nothing published covers your question, it says so and offers to bring in HR.
Mello also reads your own record in People, such as employment type, location, department, manager and start date, so it answers the part of a policy that applies to you.
It uses your record only in your own chats, never in a shared channel. Anything missing from People is missing for Mello too.
Mello reads your time-off balances only when your company connected BambooHR, Rippling, HiBob or Deel, and never guesses one. It does not book leave; it prepares an HR request with the dates.
Questions about Shuffl itself, such as who can see your Pulse answers, Mello answers from these guides and says so.
In a shared channel, Mello answers only from Knowledge published to everyone. Anything personal it answers in a direct message, and Open DM takes you there.
Mello writes with AI, so even an answer from verified Knowledge can be wrong or incomplete. Before you act on pay, leave or eligibility, open the source or ask HR.
Slack message, Ask me in a DM (Whoever mentions Mello in a channel, in the thread; When the answer needs company information only a DM can show):
```text
Please ask me in a direct message so I can answer using the company information you can access.
```
## Get help from HR
When a person needs to help, Mello prepares a short message for HR and shows who would receive it.
Edit it if you like; nothing is sent until you choose Share with HR on the web or Send to HR in Slack. HR gets that message, never your conversation, and replies arrive in the same chat.
Slack message, Handoff to HR (The person asking Mello, in their DM; When Mello can’t answer and offers to ask HR):
```text
Ready to send to HR
```
- [How a request reaches HR](https://shuffl.ai/docs/hr-requests)
## Let Mello do things for you
Mello can also act for you, within your role, such as joining a community or setting your profile visibility. Anything that changes something appears first as a Prepared action card and runs only when you press its button.
Slack message, Action Mello prepared (The person who asked Mello, in their DM; When Mello prepares a change for someone to run):
```text
Start onboarding for a new hire
```
- [What Mello can do for you](https://shuffl.ai/docs/what-mello-can-do#employees)
## Your chat history and feedback
Your chats lists everything you asked, grouped by day. Rename gives a chat a name only you see; Delete removes it. Search your chats searches your web chats.
HR requests, above your chats, lists every request you sent, open ones first, with HR’s latest reply. A request stays there after its chat is deleted.
A chat you started in Slack shows in the web list too, once your Slack account is linked. It is read from Slack each time, not saved in the browser, and is read-only here: Open in Slack to continue it.
Good answer shares your rating, optional note and the sources used with your workspace administrators; your question and the answer stay private. Bad answer also shares your question, unless you tick Keep my question private.
## Who can read your chats
Your manager, HR and administrators cannot read your chats, and Shuffl deletes them after 30 days. HR sees only what you share. Slack keeps its own copy of direct messages under your workspace’s retention settings.
- [Security and data handling](https://shuffl.ai/security)
## Related guides
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Find your way around](https://shuffl.ai/docs/around-shuffl)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Privacy and your data](https://shuffl.ai/docs/privacy-and-data)
- [What Mello can do for you](https://shuffl.ai/docs/what-mello-can-do)
Agent documentation index: https://shuffl.ai/llms.txt
---
# What Mello can do for you
> What Mello can look up and change in Shuffl for you, how you confirm each change, and what it never does.
Audience: Everyone using Shuffl, with a part for administrators
Kind: Explanation
Canonical: https://shuffl.ai/docs/what-mello-can-do
## How Mello acts for you
Mello can look things up in Shuffl and make changes for you, but only what your role lets you do in Shuffl yourself. When something needs a role you don’t have, Mello says so instead of trying.
Looking something up changes nothing and happens straight away. Anything that changes something, such as joining a community, is prepared first and runs only when you press its button.
Mello uses the same actions as the app, with the same checks, so the result is the same as doing it yourself.
- [Ask a question](https://shuffl.ai/docs/ask-mello#asking)
## The whole list
What Mello can do, under Help or Chat, lists what you can ask and do in your workspace, with what to say. Ask rows are answered; Do rows are prepared as a card you run once. Each row names the system it reaches.
Ask Mello “What can you do?” in Chat or Slack for the top five, and Slack’s Home tab shows a few with See everything.
### Ask, for everyone
- Policies and benefits: “What’s our parental leave policy?”
- Docs from your other tools: “Where’s the expense guide?”
- Time off balance: “How much time off do I have left?”
- People and teams: “Who’s on my team?”
- Who knows what: “Who knows about payroll?”
- Pulse: “What did we change after Pulse?”
- What Mello can do: “What can you do for me?”
### Do, for everyone
- Ask HR: “I need to ask HR something private.”
- Your profile: “Help me fill in my profile.”
- Communities: “Which communities could I join?”
- Badges: “Which badges could I earn?”
- Praise: “Thank Sam for the launch.”
- Meet coworkers: “Who should I meet at work?”
- Celebrations: “Whose birthday is this week?”
- Onboarding and buddies: “What should I do next this week?”
- Mentorship: “Find me a mentor.”
- Your notifications: “Stop the weekly reminder.”
### For managers
- Your reports: “Who reports to me?”
- New hire plans: “Draft a 30/60/90 plan for my new hire.”
### For HR
- Company guidance: “Help me draft a remote work policy.”
- Import from your tools: “Import our Notion handbook.”
- HR requests: “Set up HR request categories.”
- People and access: “Invite our three new hires.”
- Groups and automations: “Make a group for everyone in London.”
- People sync: “When did People last sync?”
- Connections: “Help me set up coworker introductions.”
- Playbooks: “Start onboarding for our new hire.”
- Playbooks from start dates: “Start onboarding on each start date.”
- Mentorship programs: “Start a mentorship program.”
- Celebrations: “Help me turn on Celebrations.”
- Pulse: “How is Pulse going?”
- Praise: “Which values got the most praise?”
- Insights: “How many questions did Mello answer this month?”
- Workspace settings: “Send the Slack welcome again.”
- [Open What Mello can do](https://shuffl.ai/app/mello)
## What connecting a system adds
Some rows need a system your company connects. Until then, the row says what it takes, and Mello says the same when you ask. Choose Tell HR, or say yes when Mello offers, and HR’s Inbox counts the asks, never with names.
People → Sync and Knowledge → Connections show what each system adds before you connect it. Once it is live, HR’s Home shows Mello now can, with a post to share.
### An HR system adds
- Time off balance: “How much time off do I have left?”
- People sync: “When did People last sync?”
- Playbooks from start dates: “Start onboarding on each start date.”
### A document tool adds
- Docs from your other tools: “Where’s the expense guide?”
- Import from your tools: “Import our Notion handbook.”
- [Connect an HR system](https://shuffl.ai/docs/people-sync)
- [Connect a document tool](https://shuffl.ai/docs/connected-sources)
## What you can ask Mello to do
Your profile: “Add SQL and pricing to what people can ask me about” or “Only my team should see my phone number”.
Praise and communities: “Thank Kwame for fixing the order sync in the praise channel” or “Join the Lunchtime runners community”.
Finding people: “Who knows about Kubernetes?” names coworkers whose profiles match, using only what each person shares. “Who should I meet?” suggests people you haven’t met.
Your HR requests: “Show my HR requests” lists each with where it stands. HR responders also see what waits on them, each with Draft a reply.
Time off: “How much vacation do I have left?” works when your company connected BambooHR, Rippling, HiBob or Deel. Mello does not book leave; it prepares an HR request with your dates.
Reminders and settings: “Turn off my Pulse reminders” or “Email me when HR replies to my requests”.
Badges, cards and onboarding: “Sign Mei Lin’s birthday card” or “Claim the badge with code ROCKET”.
Your playbooks, while you are new: “What should I do this week?” or “I enrolled in benefits, tick that off”. Mello answers from your own onboarding only, and checking off a to-do is prepared for you to confirm.
- [Choose who sees what](https://shuffl.ai/docs/your-profile#visibility)
## Check and run an action
1. Ask Mello in your own words, such as “I’d like to meet Kwame Mensah”. If it needs something you didn’t say, it asks first instead of guessing.
2. Under the answer, a Prepared action card shows Ready to run, what the action does and each value it will use.
3. Check the values and press the button, which is named after the action (or Run), or choose Dismiss. A button that removes or stops something is red.
4. To change a value, dismiss the card and tell Mello what to change.
5. The card then shows Done, or Could not run with the reason. Mello checks your role again when you press the button.
6. Each card runs once, even if pressed again or on another device.
- [Open Chat](https://shuffl.ai/app/chat)
## For administrators
Administrators can ask Mello for workspace changes too. Each is prepared the same way and runs only from its button.
Pulse: “Turn on Pulse”, “Ask the workload question to Engineering only” or “Plan an action on the workload result, owned by Nora, due end of month”.
Programs and celebrations: “Set up a Connections program for the new joiners channel” drafts one with a Review and create button in Chat on the web. “Pause the coffee chats program” or “Turn on work anniversaries” prepare the change.
People and access: “Invite Sam Patel as an employee” or “Move Diego to the Sales department”. Mello reads the current record first and changes only what you asked.
Knowledge and HR requests: save a Knowledge draft, publish a ready version or check which common HR policies Knowledge covers. Administrators can change HR request categories, owners and the response target.
Insights: “How did the last eNPS go?” or “What did Mello handle this month?”. Pulse and Praise totals are the published ones, for groups of seven or more.
- [Who can do what](https://shuffl.ai/docs/roles-and-permissions#who-can-do-what)
- [Who sees Pulse answers](https://shuffl.ai/docs/pulse#who-sees-what)
## What Mello never does
Mello never answers or skips a Pulse question for you, and never answers your first 90 days check-in, so those answers stay apart from your name.
It never reads or tells anyone one person’s Pulse answer, only the published totals.
It never sends anything to HR on its own. You see the exact message and who receives it, and choose Share with HR or Send to HR.
It never takes a password, API key or token in chat; an administrator enters those under People → Sync or Knowledge → Connections. It does not upload pictures, but can draw a badge or cover with AI.
Choosing who answers HR requests and billing stay in Settings. Mello cannot book or approve leave or change pay. To change your own manager, team or title, it prepares a request to HR.
It never says something happened before you pressed the button and the card shows Done.
- [How a request reaches HR](https://shuffl.ai/docs/hr-requests#share)
- [First 90 days check-ins](https://shuffl.ai/docs/playbooks#first-90-days)
## Questions about Shuffl, and choosing between options
Ask how Shuffl works, such as “Who can see my Pulse answers?”, and Mello reads these guides and says so. The guides describe Shuffl in general, never your company’s policies. When they don’t cover it, Mello says it isn’t sure.
When a request could mean more than one thing, such as two people with the same name, Mello asks one question with two to four choices to tap. It never offers choices for anything sensitive, such as health, pay or a complaint.
## In Slack and on the web
Actions work in Chat on the web and in a direct message with Shuffl in Slack. In a channel or group message, Mello asks you to message it privately.
In Slack, Mello acts as your Shuffl account, so both accounts must belong to the same person in People. If they don’t, ask in Chat on the web, or ask an administrator to link your Slack account in People.
The Slack card has the same button, Dismiss and Open in Shuffl. For an action that removes or stops something, Slack asks Run this? once more. Program drafts appear only in Chat on the web.
- [Connect Slack](https://shuffl.ai/docs/slack#connect)
## When Mello is offline
1. When Mello can’t answer, Chat and Home show Mello is offline. Find people or policies still searches People and Knowledge.
2. Choose Ask HR. What you typed is already in Your question; edit it so it has what HR needs and nothing more.
3. Check Sent to and Who can read it, tick I approve this text and these responders, and choose Send to HR.
4. The request opens in Chat, where HR’s reply arrives. It also stays in HR requests above your chats.
5. Administrators see Contact Shuffl instead of Ask HR, to tell us the AI connection isn’t answering.
## Related guides
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Roles and permissions](https://shuffl.ai/docs/roles-and-permissions)
- [Privacy and your data](https://shuffl.ai/docs/privacy-and-data)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Your profile
> Fill in your profile, choose who sees what, and let coworkers find the right person to ask.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/your-profile
## Fill in your profile
1. In your first week, Me shows one card, Make your profile yours: what you are working on, Ask me about topics and your interests.
2. Fill them in and choose Save. Mello uses them to name you when someone asks who knows a topic.
3. Choose Let Mello draft it to fill the empty boxes from your role and team. Nothing is saved until you choose Save.
4. Empty sections stay hidden. Add to your profile, under the cards, adds a bio, your role, communities or badges. Edit profile changes everything, location and pronouns too.
5. Add links offers LinkedIn, GitHub, X and a website. The … menu copies your profile link and opens Your settings for account, notifications and calendar.
6. Add your birthday as a month and day if you want a note on the day. Shuffl never stores the year.
- [Open your profile](https://shuffl.ai/app/me)
## Your photo and cover
Choose Change photo to upload a picture or Create with Mello to make one. Every workspace shows the same photo.
In the … menu, Add a cover uploads a banner and Create a cover with Mello makes one. Remove photo and Remove cover take them away.
- [Open Account settings](https://shuffl.ai/app/settings/account)
## Choose who sees what
Who can see what sets whether Everyone, My team or Only me sees each field, such as Working on, location, phone, badges and birthday.
My team means anyone in one of the groups on your profile. Hidden fields stay out of search and Mello’s answers. View as shows what others see.
Your name, title, team, manager and work email come from People and are visible to everyone in the workspace.
## Who you know and who you want to meet
On a coworker’s profile, I know them and Want to meet are private. They shape who Mello suggests and show as People you both know on other profiles. Nobody is told you clicked.
Someone you thanked, or who thanked you, in a public praise channel in the last year is suggested, and joins your network when you both choose I know them.
Message on Slack opens a direct message. Schedule time proposes a 30-minute call when you both connected a calendar under Settings → Your calendar; opened on its own, it asks who you want to meet first. Praise opens the praise composer for them.
## Related guides
- [People and the org chart](https://shuffl.ai/docs/people)
- [Find your way around](https://shuffl.ai/docs/around-shuffl)
- [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/celebrations)
- [Privacy and your data](https://shuffl.ai/docs/privacy-and-data)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Find your way around
> Where things are on Home, in the menu and on a phone, and the settings that are yours alone.
Audience: Everyone using Shuffl
Kind: Explanation
Canonical: https://shuffl.ai/docs/around-shuffl
## Home
Home fits on about two screens. Mello’s panel greets you with an Ask Mello box. For HR, the Inbox shows its count and first three rows, with a red chip on anything overdue.
This week counts new faces, celebrations and thank-yous, and Your places links to what is on.
The feed below is about people you know: birthdays and anniversaries, introductions Mello made, community joins and badges, and now and then someone you haven’t met.
Three or more of a kind become one entry with the faces. It shows five entries; Show more adds the rest.
The rings show the same moments as stories, unseen first. Picks plays up to five Mello chose for you, like a birthday to wish: pick a quick note and Send in Slack copies it and opens your DM, or Skip. Shuffl never posts as you.
The buttons beside What’s happening switch the feed between Cards and Compact. The settings menu next to them turns the story rings, autoplay and Picks on or off, on every device.
For you lists what waits on you, by due date: pages HR asked you to confirm, and onboarding to-dos and check-ins. In your first week it adds setup steps such as a photo, a community and a hello.
It shows three; Show all opens the rest. The Home tab counts them.
- [Open Home](https://shuffl.ai/app)
## Getting around
The top bar has Home, People, Ask, Praise and Me. Press ⌘K, or choose the Ask Mello field, to search or ask from anywhere.
On a phone, the bottom bar has Home, People, Mello, Praise and Me, and a dot means something waits for you. Communities and Celebrations are on Home, your profile and the phone menu’s More.
Administrators, HR responders and Knowledge verifiers get an HR workspace switch in the top bar, counting what waits on you.
It opens a rail beside HR’s pages: Inbox, Today and People, then Programs (Pulse, Praise, Celebrations, Playbooks, Connections, Automations), Knowledge (Library, Handbook), Insights and Settings. The rail marks where you are; press the switch again to go back.
On a phone, Menu has one HR workspace row that opens the same list as a sheet, and HR’s pages get a bar of Inbox, Today, People, Programs and More. What’s new in the top bar lists the latest changelog entries and blog posts.
A link to an HR page someone can’t use, such as an old bookmark, takes them back to Home with a short note instead of a locked page.
Your photo at the top right opens the account menu: your name, sign-in email and role. Then come You (Your profile, Your settings, Notifications, Account), Company, Workspace, and Help, Privacy choices and Sign out.
Choosing a company opens the last workspace you used there. Owners and administrators find Company settings under Company and can create workspaces.
## Profile, notifications and calendar
Profile holds your name, photo and sign-in email, links to your page in People, and under Appearance picks light, dark or your device setting.
Notifications is one table: a row per notification and a column each for Slack and Email. Intros, onboarding, praise and celebrations are Slack only for now. Someone without a linked Slack account gets email. Preview on a row shows the message with sample people.
Connected apps lets you use Shuffl from Claude or another AI agent. Copy the connector URL, add it in Claude as a custom connector and allow access on the page that opens. The agent works as you, with your role, and Disconnect removes it.
What’s new in Shuffl is a short note after a major update, at least two weeks apart, with a link to the changelog. Turn off both switches to stop it.
Getting started is a few emails in your first ten days: a welcome for everyone (in Slack, if Shuffl reaches you there). Administrators also get setup notes on days 2 and 5 and a day 10 summary.
Turn off its Email switch, or use Unsubscribe, to stop them.
Check-ins are for owners and administrators: one email with one thing to try if nobody has used Shuffl for two weeks, and a last one at 30 days. A fix-it link comes if Shuffl is removed from Slack or a people sync fails.
Turn off its Email switch, or use Unsubscribe, to stop them.
Your calendar connects Google Calendar or Microsoft 365, optionally with Meet, Teams or Zoom, so Schedule time can propose times that suit both people. Shuffl reads free and busy times only.
- [Open Profile](https://shuffl.ai/app/settings/profile)
- [Open Notifications](https://shuffl.ai/app/settings/notifications)
- [Open Connected apps](https://shuffl.ai/app/settings/connected-apps)
## Your account and sign-in
Account holds your sign-in methods: email and password, Google or Slack. Disconnect Slack… stops Slack sign-in but keeps your profile linked. Add a passkey to sign in with your device, or turn on Two-factor sign-in with an authenticator app and keep the backup codes safe.
The first time you open Shuffl in a browser, a banner asks about analytics: Reject all, Choose or Accept all. Choose has a switch per kind of data, then Save choices.
Where the law requires consent, nothing optional starts until you accept. Privacy choices in the account menu changes it for that browser.
Product analytics decides whether Shuffl may see which features you use, never what you write. Delete account works once every company you alone own has another owner or, if empty, has been deleted. Leaving a workspace keeps your company membership.
- [Open Account](https://shuffl.ai/app/settings/account)
## Related guides
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Your profile](https://shuffl.ai/docs/your-profile)
- [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/celebrations)
- [Notifications and reminders](https://shuffl.ai/docs/notifications)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Privacy and your data
> Who can read your chats, HR requests, Pulse answers and profile, what Shuffl reads in Slack, and how to delete your data or leave.
Audience: Employees and HR teams
Kind: Explanation
Canonical: https://shuffl.ai/docs/privacy-and-data
## Your Mello chats and ratings
Your chats with Mello are private to you. Your manager, HR and administrators can’t open them, and administrators have no transcript view.
Shuffl deletes each chat 30 days after you start it; Privacy & details, under the box where you type, shows the date. A chat in Slack is also kept by Slack, under your company’s Slack retention settings.
Good answer shares your rating, your optional note and the sources the answer used with your workspace administrators. Your question and the answer stay private.
Bad answer also shares your question, so administrators can test Mello on it, unless you tick Keep my question private. The answer is never shared. Rating in Slack shares only your rating, reason and the sources.
- [Open Chat](https://shuffl.ai/app/chat)
- [Your chat history](https://shuffl.ai/docs/ask-mello#history)
## What HR sees
Nothing reaches HR until you choose Share with HR on the web or Send to HR in Slack. First Mello shows you the message and who on the HR team would receive it, so you can edit it.
HR gets the message you reviewed, never your chat. Only you and the HR responders on your request can read it; being an administrator doesn’t give access. A sensitive category, such as employee relations, opens only for the responders your company named for it.
Your company keeps HR requests for as long as it keeps the workspace, as its record of how a question was handled, even after the chat is deleted.
- [Share a request with HR](https://shuffl.ai/docs/hr-requests#share)
## Your Pulse answers
Pulse answers are confidential, not anonymous. Shuffl knows who was asked and whether they answered, to count participation. What you answered is stored apart from your name, under a token no role can reverse, and no role, export, report or agent can read it.
HR sees totals only when 7 or more people answered; your company can raise that number but never lower it. Skipping a question tells nobody anything.
There are no individual scores, manager dashboards or benchmarks against other companies, and a Pulse answer never appears in a chat with Mello.
Answers are deleted 90 days after the question closes; the totals are kept. Slack keeps its own copy of the question message, but your tap goes only to Shuffl.
- [Who sees Pulse answers](https://shuffl.ai/docs/pulse#who-sees-what)
- [What Pulse never builds](https://shuffl.ai/docs/pulse#never-built)
## Your profile, praise and celebrations
Your name, title, team, manager and work email come from People, and everyone in the workspace sees them.
For most other fields, open Me, choose Who can see what and pick Everyone, My team or Only me. Administrators don’t see hidden fields either, and Mello leaves them out of answers.
I know them and Want to meet on a coworker’s profile are private; nobody is told you clicked.
Volunteer as a buddy on your profile puts you first when HR picks a buddy for a new hire. Choose it again to step back. If HR took you off the list, ask HR to put you back.
Praise from a public channel shows to everyone, as it does in Slack. Praise from a private channel shows in Shuffl only to the giver and the people thanked.
Hide from profile takes praise off your profile and the Everyone feed. Administrators see praise totals only, for groups of 7 or more.
Shuffl stores your birthday only if you add it, as a month and day, never the year. Nothing about your birthday or anniversary is posted unless you choose Share it; then your manager hears a week ahead.
- [Open your profile](https://shuffl.ai/app/me)
- [Choose who sees what](https://shuffl.ai/docs/your-profile#visibility)
- [Who sees your celebrations](https://shuffl.ai/docs/celebrations#who-sees-what)
## What Shuffl reads in Slack
Shuffl reads only the Slack conversations it is part of. It can’t read your direct messages with coworkers, or a channel nobody added it to. It reads:
Messages you send to Shuffl in a direct message, with earlier messages in that conversation, and files you attach there when you ask about them.
Threads and group messages where someone mentions @Shuffl, to answer there or make a badge from the thread. Before answering where others can see, it checks who is in the conversation.
The praise and launch channels your administrators chose: messages that mention someone, and reactions on praise. A newly added praise channel brings in up to its last 12 months.
A community’s linked channel, read when someone opens the community page. Those posts are not stored.
Once a day, who posted and when in channels Shuffl is in whose name marks a project, launch or event, like #proj-atlas, to offer a badge when one goes quiet.
The words are not read or stored. Administrators can turn this off under Praise → Badges.
Your Slack member list, with names, profiles, email addresses and whether each account is active, to keep People current. Channel names and members, so administrators can pick channels and Shuffl can check who should see a message.
Shuffl writes to Slack only to send messages, open direct and group messages and add a reaction to praise when turned on. On request it creates a community’s channel or invites people to it.
On a paid Slack plan, if your company turns it on, it adds the Shuffl profile link to your Slack profile and changes nothing else.
- [Connect Slack](https://shuffl.ai/docs/slack)
## How Mello uses AI
Mello answers from the Knowledge published to you and your own record in People, and cites its sources. If nothing published covers your question, it says so and offers to bring in HR.
To write an answer, Shuffl sends your question, the conversation so far and the Knowledge it found to an AI model provider, only to compose that answer. Shuffl doesn’t use customer content to train models, or one company’s content to improve the service for another.
Mello writes with AI, so an answer can be wrong or incomplete. Before you act on pay, leave or eligibility, open the source or ask HR.
- [AI and your data](https://shuffl.ai/security#ai)
- [How the assistant uses company knowledge](https://shuffl.ai/privacy-policy#how-the-assistant-uses-knowledge)
- [Providers and where they process data](https://shuffl.ai/privacy-policy#who-else-sees-it)
- [What Mello never does](https://shuffl.ai/docs/what-mello-can-do#never)
## Product analytics choices
1. To turn them off in every browser, open Account from your account menu and turn off Product analytics. Your activity then counts only towards anonymous workspace totals.
2. For one browser, open Privacy choices in your account menu and choose Allow analytics or Reject analytics.
3. A company owner or administrator can turn product analytics off for every workspace in Settings → Company → Name and logo.
Product analytics tell Shuffl which features people use, never what anyone writes. They never include questions, answers, documents, HR requests, praise, Pulse answers, names, email addresses or Slack ids.
- [Open Account](https://shuffl.ai/app/settings/account)
- [Privacy preferences](https://shuffl.ai/privacy-preferences)
- [What product analytics record](https://shuffl.ai/privacy-policy#what-shuffl-processes)
## Delete your data or leave
1. To delete a chat, open its menu in your list of chats and choose Delete, then Delete conversation.
2. HR requests sent from it stay. A chat started in Slack is removed in Slack.
3. To leave a workspace, open Settings → Workspaces under Company, open the workspace’s actions menu and choose Leave workspace. You stay a member of the company.
4. To delete your account, open Account, then Delete account…. If you are a company’s only owner, choose a new owner or delete the empty company first.
5. Enter your password, tick I understand this can’t be undone and choose Delete my account.
6. If your company’s directory manages your account, ask your administrator to remove it there.
Deleting your account signs you out everywhere, ends your workspace memberships, revokes your API keys and removes your support conversations with Shuffl. Your person in People, HR requests, Knowledge and the activity log stay with each workspace, unlinked from you, as your employer’s records.
Chats go 30 days after they start and Pulse answers 90 days after the question closes. A deleted workspace or company can be restored for 30 days, then is erased; backup copies are gone within a further 30 days.
Five days after Shuffl is removed from a Slack workspace, it deletes what it holds from that Slack. That is chats and HR requests from Slack, drafts written from them, unpublished Slack files, praise read from channels, suggested badges, and everyone’s Slack id and photo.
Re-add Shuffl within those five days to keep everything.
Published Knowledge, awarded badges and People records stay until the workspace is deleted. Backups and other providers’ copies expire within 14 days of the removal. For anything else, write to privacy@shuffl.ai; your employer decides about workspace records.
- [Open Workspaces](https://shuffl.ai/app/settings/company/workspaces)
- [How long it is kept](https://shuffl.ai/privacy-policy#how-long-it-is-kept)
- [Data Processing Addendum](https://shuffl.ai/dpa)
## Related guides
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Your profile](https://shuffl.ai/docs/your-profile)
- [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/pulse)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Notifications and reminders
> Every message Shuffl sends you, where it arrives, and how to change or stop each one.
Audience: Everyone using Shuffl, and administrators who set reminders
Kind: Reference
Canonical: https://shuffl.ai/docs/notifications
## Where Shuffl reaches you
Shuffl reaches you in three places: a private Slack message from Mello, email to your account’s address, and Home and the dots in the menu in Shuffl itself.
Settings → Notifications decides, for each topic, whether it reaches you in Slack, by email, both or neither. Your choices apply in every workspace you belong to.
If your Slack account isn’t linked to your profile in a workspace, the page shows Slack not linked · email only. Messages that can go by email come by email instead. An administrator can link your Slack account in People.
Connections intros, Onboarding, Praise and Celebrations go in Slack only for now. Without a linked Slack account, onboarding messages wait and celebrations show as a note in Shuffl.
- [Link an account to the right person](https://shuffl.ai/docs/employee-access#link)
- [Shuffl without Slack](https://shuffl.ai/docs/slack#without-slack)
## Choose Slack, email or both
1. Open Settings and choose Notifications under You, or choose Notifications in the account menu.
2. Find the topic under Programs, Requests and support, or From Shuffl.
3. Turn its Slack or Email switch on or off. The change saves at once.
4. Choose Preview under a topic to see the message in Slack and by email.
5. To stop a topic completely, turn off both switches.
- [Open Notifications](https://shuffl.ai/app/settings/notifications)
## What each topic covers
Programs, which all start in Slack: Connections intros when you’re matched, Pulse check-ins that one tap answers, and Celebrations about your birthday or work anniversary. Also Onboarding steps and buddy invitations, and Praise when someone praises you.
Requests and support: replies to your HR requests and from Shuffl support.
HR responders and administrators also get HR requests for you, whose email leaves out what the person wrote, and the HR digest. Administrators get Pulse results, totals only, and owners and administrators get Billing.
From Shuffl: Getting started emails in your first ten days, with setup notes for administrators. Check-ins go to owners and administrators when nobody has used Shuffl for two weeks, Shuffl is removed from Slack or a people sync fails.
Moving to the new Shuffl reaches only the admin who installed the previous version, until Slack is reconnected.
## Your reminders
1. Open the reminder’s menu. Your team’s default follows what your administrator picked, including later changes.
2. Pick another option, or Off. Your choice wins and applies in this workspace only.
3. If your administrator turns a reminder off for the workspace, nobody gets it and its menu disappears.
Some topics carry a reminder menu under their switches, shown while your workspace has it on.
They are Remind me to thank people under Praise and Remind me about unanswered questions under Pulse. Playbooks has Remind me about overdue playbook to-dos, and Connections intros has Ask me who I know.
Reminders come on a working day inside your working hours, never two on the same day.
## Stop one kind of message
1. To stop one topic, turn off its Slack and Email switches in Settings → Notifications. Other topics keep coming.
2. In a Getting started, Check-ins or Moving to the new Shuffl email, choose Unsubscribe at the bottom, then Unsubscribe on the page.
3. It turns off that topic’s email only. Account emails, like password resets, still arrive.
4. An Unsubscribe link works for 90 days; after that use Settings → Notifications. To get the emails back, turn the Email switch on again.
5. For a reminder, choose Off in its menu, or press Stop these reminders on the message in Slack. Both set the same choice.
6. What’s new in Shuffl links to Settings → Notifications from both Slack and email.
- [Open Notifications](https://shuffl.ai/app/settings/notifications)
## What’s new
What’s new in Shuffl is a short note after a major update, at least two weeks apart, linking to the changelog. You hear about each update once, even across several workspaces. It starts in Slack; turn on Email to get it by email too.
The What’s new sparkle in the top bar is separate and stays whatever you choose. A dot means a changelog entry or blog post you haven’t seen; opening it clears the dot in every workspace.
- [Read the changelog](https://shuffl.ai/changelog)
## For administrators: reminder defaults
1. Praise: open Praise, then Settings. Under Reminders, turn on Send praise reminders and choose How often: Every 2 weeks, Monthly or Every 3 months.
2. It starts once Praise is reading a channel.
3. Pulse: open Pulse settings. Under Reminders, turn on Send Pulse reminders and choose When: The next day, or Before it closes (four hours before).
4. Under Days, pick at least one weekday reminders may go out.
5. Choose Save reminders.
Administrators decide whether each reminder runs and its default timing, in a card on its program’s settings page with a switch, a timing menu, Days and See the message.
Reminders go out between 9:00 and 17:00 in each person’s time zone, on the days you chose, never on the same day as another Shuffl reminder.
A praise reminder waits 7 days after a badge offer, and a Pulse reminder never comes in a question’s last half hour.
Each person can follow your default, pick another option or turn a reminder off, and their choice wins. The card counts how many turned it off, never who.
The HR digest’s schedule is on your own Notifications page, below the topics.
A new hire’s day 30, 60 and 90 check-ins and manager one-to-ones are onboarding playbook steps, not reminders.
- [Open Praise settings](https://shuffl.ai/app/praise/settings)
- [Open Pulse settings](https://shuffl.ai/app/pulse/settings)
- [The first 90 days](https://shuffl.ai/docs/playbooks#first-90-days)
- [The HR digest](https://shuffl.ai/docs/impact#digest)
## Related guides
- [Find your way around](https://shuffl.ai/docs/around-shuffl)
- [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/pulse)
- [Praise and badges](https://shuffl.ai/docs/praise)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Shuffl for managers
> What Shuffl does for you when People lists you as someone’s manager, and what stays private from you.
Audience: People managers
Kind: How-to guide
Canonical: https://shuffl.ai/docs/managers
## Who counts as a manager
You are a manager in Shuffl when People lists you as the manager of at least one current coworker. It isn’t a role, and job titles don’t count. HR sets reporting lines in People by hand or through Sync.
Being a manager adds a few private Slack prompts and changes which Knowledge and Pulse questions reach you. It gives you no access to your reports’ records beyond what every coworker sees.
If someone is missing from your team, or listed under you by mistake, ask HR to fix their manager in People.
- [How reporting lines are set](https://shuffl.ai/docs/people#reporting-lines)
## See your team
1. Open People and choose Filters. Under Add a filter…, choose Reports to and pick your own name.
2. To see the wider tree, open Me, then See in org chart on the Org card.
3. Unless you are also an administrator, you can’t change a report’s manager, team or title. Ask Mello to prepare a request to HR.
Your profile’s Org card lists your Direct reports. Their names, titles, departments, groups on profiles, manager and work email are visible to everyone in the workspace.
Other profile fields follow each person’s choices: a field kept to My team is hidden from you unless you share a group on their profile.
- [Open People](https://shuffl.ai/app/people)
- [Open the org chart](https://shuffl.ai/app/people?view=org)
## Check in with a new hire
1. Read what the step asks and open the links HR added.
2. Choose Done beside the to-do once you have had the one-to-one, so HR sees it on the hire’s playbook.
When HR approves a new hire whose manager is you, the manager steps come to you as private Slack messages on their days, with any to-dos. The First 90 days template, for example, books a one-to-one every other week.
Your Playbooks page also lists them under Plans for your new hires. Mello drafts a 30/60/90 plan as soon as they join, for you to edit and share.
You, the hire and HR see its goals, only you change them, and your to-do reminders link to it until it is shared.
Their day 30, 60 and 90 check-in answers are confidential: HR sees them only combined, and you never see them.
Slack message, Overdue to-do reminder (The manager, buddy or owner, privately; Once, a day or 3 days after a to-do’s day, while it is still open):
```text
2 to-dos for Mei Lin Zhou’s onboarding are still open.
```
- [The first 90 days](https://shuffl.ai/docs/playbooks#first-90-days)
- [Plan a new hire’s first 90 days](https://shuffl.ai/docs/playbooks#new-hire-plans)
## Anniversaries and birthdays
A week before a report’s work anniversary or birthday, Mello sends you a Slack direct message with the day and a note to start from. It comes only when the person chose to share that day.
If the team is signing a card, the message has Sign the card. Cards waiting on your note are under Cards to sign on Your celebrations.
Mello never posts as you. Send your note on the day, or use Slack’s Schedule message. Nothing comes if their manager changes before the day, either of you has left, or your Slack account isn’t linked.
Slack message, Manager heads-up (The person’s manager, privately; A week before a shared celebration):
```text
Jordan Lee's 5-year work anniversary is coming up on . A note from you on the day means more than one from Mello.
```
- [Celebrations for managers](https://shuffl.ai/docs/celebrations#managers)
- [Open your celebrations](https://shuffl.ai/app/celebrations)
## Change how often you’re nudged
1. A to-do HR gave you for a new hire gets one Slack reminder if it is still open after its day. Choose Done, or Snooze to Monday.
2. Open Settings → Notifications. Under Playbooks, Remind me about overdue playbook to-dos shows while your workspace has these reminders on.
3. Pick Your team’s default, another option or Off. Stop these reminders in Slack sets the same choice.
Praise reminders are the same for managers as for everyone. With Nudge quiet managers on, you also get a private note when nobody on your team has been thanked in 60 days, at most once a month.
- [Open Notifications](https://shuffl.ai/app/settings/notifications)
- [How reminders work](https://shuffl.ai/docs/notifications#reminders)
## Knowledge and Pulse aimed at managers
HR can publish Knowledge to Managers only, such as a guide to approving leave. You read it, and Mello answers you from it, while you have at least one report.
Pulse questions can also be aimed at managers or at individual contributors, such as the Manager check-in set your reports may answer.
Your Pulse answers count in the Managers group when HR splits results by Managers and ICs, shown only at or above the reporting floor.
- [Who can read a source](https://shuffl.ai/docs/knowledge#draft)
- [Who sees Pulse results](https://shuffl.ai/docs/pulse#who-sees-what)
## What you can’t see
Your reports’ chats with Mello. Only the person who had a chat can read it.
Your reports’ HR requests. Only the sender and the HR responders it went to see one.
Pulse answers and results. Pulse has no manager dashboards or team view, and no role can read one person’s answer.
New hire check-in answers, a coworker’s manager history and the upcoming celebrations list, which is for administrators.
- [What no role opens](https://shuffl.ai/docs/roles-and-permissions#private)
- [What Pulse never builds](https://shuffl.ai/docs/pulse#never-built)
## Ask Mello for help
1. In Chat, choose Who reports to me? or ask in your own words.
2. Ask about your team: who is on a team, someone’s title, when they started or what time it is where they are.
3. Ask about a policy you apply as a manager, such as approving expenses. Mello cites the source.
4. To change a report’s details or raise a concern, ask Mello. It drafts a message to HR, sent only when you choose Share with HR or Send to HR.
Mello answers from People and the Knowledge published to you. It never judges your reports, guesses how someone feels, or describes their pay, leave, performance or HR matters.
- [Open Chat](https://shuffl.ai/app/chat)
- [What Mello can answer](https://shuffl.ai/docs/ask-mello#what-mello-knows)
## Related guides
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/celebrations)
- [People and the org chart](https://shuffl.ai/docs/people)
- [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/pulse)
- [Roles and permissions](https://shuffl.ai/docs/roles-and-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Review and publish knowledge
> Turn a policy into a published source with an audience and dates, so Mello can answer from it and cite it.
Audience: HR administrators and Knowledge verifiers
Kind: How-to guide
Canonical: https://shuffl.ai/docs/knowledge
## Add a source
1. Choose Add source → Write an article to write in the editor, with Markdown and a preview. Write with Mello drafts a page from its title and a short request.
2. Choose Start from a template for one of over twenty policies, such as paid time off, expenses or code of conduct.
3. Shuffl fills in what it knows, like your company name and HR contact, and lists it under Filled in from Shuffl. Replace every other [bracketed placeholder] before publishing.
4. Or choose Draft with Mello on the template.
5. Mello reads your Knowledge and official sources for where your people work, then fills every blank, marking each value Your company, The law or Typical, check.
6. Check each one; Undo draft puts the template back. Mello is not a lawyer.
7. Check before you publish in the editor lists rules that often differ in the US, the UK and the EU.
8. It is not legal advice; have someone qualified review the policy.
9. Choose Import a file for a PDF, Word, PowerPoint, Markdown, HTML or text file up to 50 MB and 500 pages.
10. A long handbook is split by its headings into one draft per section. Password-protected PDFs cannot be read.
11. Choose Add a website page to import a page that Shuffl re-reads when it changes, including intranet pages behind a sign-in.
12. Connected providers such as Google Drive and Notion have their own guide.
13. Or tell Mello in Chat what employees should know. It drafts the wording and puts it in the Inbox for a reviewer to verify.
Everything Mello answers from starts as a source in Knowledge, with a title, a body, an audience and two dates. People who manage Knowledge add, edit and publish sources on the same page everyone reads.
- [Open Knowledge](https://shuffl.ai/app/knowledge)
- [Write Knowledge that Mello answers well](https://shuffl.ai/docs/write-knowledge#one-topic)
- [Policy templates to read first](https://shuffl.ai/templates#category-policies)
## Start with a draft
1. Give the source a title and check its text. For an imported file, read the extracted text of each draft before you publish.
2. Choose Who can read this after publishing?: HR admins only, Everyone in this workspace, or Selected departments, groups or roles.
3. A blank article starts with HR admins only; templates for employees start with Everyone in this workspace.
4. Set Effective date and Review by, in UTC. On the Review by date the source stops being used in answers until someone reviews it.
5. Choose Save draft. Only reviewers and administrators see drafts.
- [Variants by country, team or role](https://shuffl.ai/docs/write-knowledge#variants)
## Publish deliberately
1. Open the source and choose Review and publish. Check who can read it: if only HR admins can, Mello won’t answer employees from it.
2. Confirm with Publish source. Version history keeps every published version.
3. Employees can use the source once the audience includes them and today falls between its effective and review dates.
4. To change who can read a published source, choose Who can see this? in its header. Narrowing the audience removes access at once.
5. Ask Mello a question the source answers and follow the citation. Reviewers see more than employees do, so check with an employee account.
- [Open Chat](https://shuffl.ai/app/chat)
## Ask people to confirm they’ve read it
1. Open a published source and choose Ask to confirm. Everyone in its audience is asked. Leave Message them now on to message each person in Slack or by email.
2. People see the page under Please confirm on Home and choose I’ve read this at the end.
3. Only the person can confirm, in the app, never an API key or agent.
4. Confirmations lists who has and hasn’t confirmed. Remind messages the people who haven’t, at most once a day.
5. After you publish a new version, earlier confirmations stay on the record. Ask again asks everyone to confirm the new one; Stop asking ends the request.
For a policy people must read, such as a code of conduct, ask everyone who can read it to confirm they have. Shuffl records who confirmed which version and when.
To ask only new hires, add a Read and confirm step to a playbook instead. See Read and confirm a page in Playbooks and onboarding.
- [Choose where Shuffl messages you](https://shuffl.ai/app/settings/notifications)
- [Example: message the group a policy affects](https://shuffl.ai/docs/groups#recipe-policy)
## Download the handbook
1. In Knowledge, choose Handbook. It shows the contents, then each page published to everyone with its effective date and version number.
2. Choose Save as PDF, then Save as PDF in the print dialog, or Markdown for a text file.
3. Pages for particular groups or only admins are left out, and the page says how many. Drafts never appear.
When someone needs the handbook as a document, for paperwork, an auditor or print, download everything you publish as one handbook.
## Verify what Mello proposes
Mello proposes knowledge when an administrator tells it what employees should know, when an HR reply has something reusable, or when it imports a file on request.
Each proposal waits in the Inbox under Reviews, and in Slack as a Knowledge draft with Approve for everyone, Admins only, Edit and Dismiss.
Choose Review, edit the title, text and audience, then Approve knowledge or Decline. Approving publishes the source.
Guidance to re-check lists sources whose review date is due or passed. Employees lose access to an overdue source until someone sets new dates.
- [Open the Inbox](https://shuffl.ai/app/requests)
- [Knowledge from HR answers](https://shuffl.ai/docs/answer-hr-requests#knowledge)
## Keep sources current
Choose Edit draft to prepare a correction, then review and publish it; employees keep the last published version meanwhile. Withdraw takes a source down at once. Archive tidies away a never-published source, and Restore brings it back.
Status tells you what to do: Needs review means the review date arrived, Scheduled means the effective date is ahead, and Changes need review means a connected document changed.
Company values deserve their own page. Praise settings can point at it, so Mello tags praise with the values people actually wrote down.
## See what Knowledge is doing
Knowledge → Insights shows how many answers used verified Knowledge, which sources answer most, and Missing guidance where Mello found nothing. Answer feedback lists employees’ ratings with the sources used, and Questions to test Mello on lists questions behind Bad answer ratings. Names stay private.
- [Open Knowledge insights](https://shuffl.ai/app/knowledge/insights)
## What employees see
Employees open Knowledge from Home or a citation and see only published sources whose audience includes them. They can search titles, choose Look inside sources to search the text, and Ask in Chat to turn a search into a question.
- [Open the employee library](https://shuffl.ai/app/knowledge)
## Public guides and workspace knowledge are separate
These guides explain Shuffl and contain none of your company’s policies. Add private documents only in your signed-in workspace, with the right audience.
Ask the guides, the question box on these pages, searches only these public guides and does not save your question. For answers from your company’s sources, use Chat in your workspace.
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Write Knowledge that Mello answers well](https://shuffl.ai/docs/write-knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Write Knowledge that Mello answers well
> Write policies so Mello finds the right passage, answers with the right figure, cites it and knows when to bring in HR.
Audience: HR administrators and Knowledge verifiers
Kind: How-to guide
Canonical: https://shuffl.ai/docs/write-knowledge
## Start with the questions people ask
1. Write down the ten questions people ask HR most, in their words, such as “how many days off do I get?”.
2. For most teams that covers paid time off, sick leave, holidays, parental leave, expenses, remote work and benefits.
3. Open Knowledge. While common policies are missing, the library says You’re missing and lists them, each with Use template or Upload yours.
4. It checks titles only, so name each source after its topic, like Paid time off.
5. Publish each one to Everyone in this workspace unless only some people should read it. Mello never answers employees from a source only HR admins can read.
6. Once people are asking, Knowledge → Insights counts Missing guidance, answers where Mello found nothing to cite. Requests → Insights shows which HR request categories need an article.
Mello answers policy questions only from Knowledge you published, and cites the source. Start with the questions HR hears most.
- [Open Knowledge](https://shuffl.ai/app/knowledge)
- [Ways to add a source](https://shuffl.ai/docs/knowledge#add)
- [Playbook: HR policies people actually read](https://shuffl.ai/playbooks/hr-policies-people-read)
## One topic per source, with headings
For each question, Mello searches your published sources with a few keywords, at most three times, and reads the passages it finds. A passage is a few paragraphs, up to about 1,600 characters. Mello can open the passages either side to read the exceptions.
Every passage is stored with the source title, the nearest heading above it and the effective date, so it still makes sense out of context.
So keep one topic per source: Paid time off, Sick leave and Expenses as three sources, not one Benefits and leave page. Each then has its own audience and dates.
Use headings people would look for, such as How to request time off and Who approves it. In the editor, the Heading button starts a line with ##. Keep a source under 30,000 characters.
Imported files are split into one draft per section. A PDF splits by its bookmarks, or its largest heading size.
A Word file splits by its Heading 1, 2 and 3 styles, so use those rather than bold text. Short sections join a neighbour, and each counts as a document, so drop cover pages and contents lists.
- [Start with a draft](https://shuffl.ai/docs/knowledge#draft)
## Write the answer, with numbers and dates
Mello answers from what a passage says and nothing more. It doesn’t add an approval step, notice period or contact the source doesn’t state, and never makes up a figure.
Put the answer first, as a number with its unit: 25 days of paid time off a year, or your manager approves anything over £250. Say who it applies to and from when.
Write the steps in order: where to ask, how far ahead and who approves. Put any link or email address people need in the text; Mello copies it exactly and never invents an HR contact.
Use the words employees use, such as vacation alongside paid time off. Mello searches with the words of the question.
Keep one version of each rule. When two sources disagree, Mello points out the conflict instead of choosing. Withdraw the old source when you publish its replacement.
Templates and Write with Mello mark every fact your company must supply as a [bracketed placeholder]. Mello writes a placeholder instead of guessing a number.
Leave out names and details of anyone’s case. Everyone in a source’s audience can read all of it.
## Variants by country, team or role
When a policy differs by country, employment type or length of service, write one source with a heading for each case, such as In the United Kingdom.
Mello reads the asker’s record in People, answers only the case that applies and says which. When the record doesn’t say, it asks first, so keep employment type and location filled in.
Use an audience when some people must not read a source at all, such as a guide for managers. A reader must belong to one of the departments or groups you tick and hold one of the roles you tick (Managers or Individual contributors).
To give each country its own source, make a group per country with a Location rule. A subsidiary that needs separate HR content can have its own workspace.
In a shared Slack channel, Mello answers only from sources published to everyone and doesn’t use anyone’s People record.
- [Keep the directory right](https://shuffl.ai/docs/people#administrators)
- [One company, one or more workspaces](https://shuffl.ai/docs/companies-and-workspaces#company-and-workspace)
## Policies on an intranet page
Add source → Add a website page imports one page as a draft. It needs a permanent public HTTPS address with no query string or # part, under 512 KB. Pick the page that holds the policy itself, not a menu of links.
For a page behind a sign-in, pick its Access method: Bearer token, API key or Username & password (HTTP Basic only, not a login form). Cloudflare Access takes a Client ID and Client secret from a service token IT creates.
Use a dedicated read-only account. Credentials are encrypted and used only for that website.
Browser sign-in / SSO can’t sign in through Google, Microsoft or Okta yet. Use the site’s knowledge connector, such as Confluence or SharePoint, or ask IT for read-only service access.
When the page changes, the source shows Changes need review and the older text stops being used until you publish the new one.
- [Connect a knowledge provider instead](https://shuffl.ai/docs/connected-sources#availability)
## Test it the way employees ask
1. Ask each question on your list in Chat, in the words employees use, and a few in a direct message to Shuffl in Slack.
2. Open the supporting sources under each answer. The excerpt is the text Mello relied on.
3. Check the figure, the date and that it is the right case for the person asking.
4. Nothing found usually means the source isn’t published to that person or uses different words.
5. The wrong source usually means two sources overlap. An incomplete answer means the detail isn’t written down.
6. Fix the source with Edit draft, then Review and publish. Employees keep the last published version until you do.
7. Ask again until the answer is right. Administrators can read sources employees can’t, so check who can read the cited source.
8. After launch, check Knowledge → Insights weekly. Questions to test Mello on lists questions behind Bad answer ratings and unanswered ones.
9. Fix the source, then choose Dismiss, or Copy as case to keep it as an evaluation case.
- [Open Chat](https://shuffl.ai/app/chat)
- [Test before launch](https://shuffl.ai/docs/rollout#test-mello)
- [See what Knowledge is doing](https://shuffl.ai/docs/knowledge#insights)
## Keep it current
Every source has an Effective date and a Review by date, in UTC, and Mello uses it between the two. A new source is set to review 180 days ahead; change that to when the policy really needs checking.
Review due soon shows 14 days before the date. Once it passes, the source shows Needs review and nobody can use it until someone publishes it with new dates.
To announce a change ahead of time, publish the new rules as a separate source with a future effective date (Scheduled). Set the current source’s Review by to that day.
A future date on a new version would take the whole source out of answers until then.
A connected source is used only while its last check is under an hour old, and older text stops being used as soon as a change is found.
A workspace holds up to 1,000 active documents, counting each section of a split file. Scanned pages are read with text recognition, up to 200 pages per file, so a PDF with a text layer imports better. Password-protected PDFs cannot be read.
- [Keep sources current](https://shuffl.ai/docs/knowledge#maintain)
- [Freshness of connected sources](https://shuffl.ai/docs/connected-sources#freshness)
## When Mello should hand off to HR
Some questions need a person whatever you publish. When a message raises harassment or discrimination, a medical, legal or safety matter, or resignation, Mello answers any policy part. It then prepares a private message to HR for the person to review and send.
Mello also offers HR when nothing published covers a question, or for what it can’t do: approve leave, change pay or book time off. HR receives only the message the person sends, never the chat.
So publish the policy for these topics, such as Raising a concern, and say how to reach a person. When Mello suggests an article from an HR reply, it leaves out names, medical facts, salaries and one-off exceptions, and a verifier approves the wording.
In Requests settings, turn on Only named people can open these requests for sensitive categories such as Employee relations, and tick who can.
- [Set up categories and who can open them](https://shuffl.ai/docs/hr-requests#categories)
- [Answer a request](https://shuffl.ai/docs/hr-requests#follow-up)
## Related guides
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Roll out Shuffl to your company](https://shuffl.ai/docs/rollout)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Manage connected sources
> Connect Google Drive, Notion, Confluence, SharePoint, Dropbox, Box, Guru or BambooHR, and keep imported sources fresh.
Audience: HR administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/connected-sources
## Check availability first
Every provider imports single documents you pick and watches them for changes. Shuffl never writes back or crawls a drive, space or folder. Each import lands as a draft to review and publish.
Open Knowledge → Connections to connect a provider or request a new one. Google Drive, Notion, Dropbox, Box and SharePoint sign in with the provider; Confluence, Guru and BambooHR take a token you create. Tokens and grants are stored encrypted.
Signing in to Shuffl with Google does not connect Drive as a knowledge source; that is a separate consent.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Use an article or a file instead](https://shuffl.ai/docs/knowledge)
- [Import an intranet page](https://shuffl.ai/docs/write-knowledge#intranet)
## Google Drive
Connect Google Drive authorizes a separate selected-file connection. Import from Google Drive opens Google’s picker; each chosen Doc, Slides, PDF, Word, PowerPoint, text, Markdown or HTML file becomes a draft. Shuffl doesn’t list the rest of the Drive or edit the originals.
## Notion
Connect Notion authorizes a read-only Shuffl connection. Share each policy page with that connection in Notion, then choose Add from Notion and paste the page link. Linked private pages, databases and meeting transcripts are not imported.
## Confluence
1. In Atlassian account settings, create an API token for the account that can read the HR spaces.
2. On Knowledge → Connections, choose Connect next to Confluence and enter the site URL (like acme.atlassian.net), the account email and the token.
3. From Add source, choose Add from Confluence, then search or paste a link.
Confluence Cloud connects with an Atlassian API token from id.atlassian.com under Security → API tokens. Shuffl reads only the pages that account can open.
Add from Confluence searches page titles or takes a pasted link. Headings become sections, and the page version is what Shuffl watches for changes.
## Dropbox
1. On Knowledge → Connections, choose Connect next to Dropbox and sign in with the account that can open the files.
2. Approve read access for Shuffl.
3. From Add source, choose Add from Dropbox, then browse, search or paste a shared link.
Dropbox connects by signing in with the account that can open the HR folders, with read access only.
Add from Dropbox browses folders, searches file names or takes a shared link. Shuffl reads PDF, Word, PowerPoint, Markdown, HTML and text files; spreadsheets, images and older Office files are refused.
## Box
1. On Knowledge → Connections, choose Connect next to Box and sign in with the account that can open the files.
2. Grant Shuffl access.
3. From Add source, choose Add from Box, then browse, search or paste a link.
Box connects by signing in with the account that can open the HR folders.
Add from Box browses from All Files, searches file names or takes a pasted link. Shuffl reads PDF, Word, PowerPoint, Markdown, HTML and text files and watches each file’s version.
## SharePoint and OneDrive
1. On Knowledge → Connections, choose Connect next to SharePoint and OneDrive and sign in with the work account that can open the files.
2. Grant Shuffl read access to files and sites.
3. From Add source, choose Add from SharePoint and OneDrive, then browse, search or paste a sharing link.
SharePoint and OneDrive connect by signing in with the work account that can open the HR files, with read access to files and sites only.
Add from SharePoint and OneDrive starts at that account’s OneDrive and followed sites, searches file names or takes a sharing link. Shuffl reads PDF, Word, PowerPoint, Markdown, HTML and text files; spreadsheets, images and older Office files are refused.
## Guru
1. In Guru, create a user token under My settings → API access, or a collection token.
2. On Knowledge → Connections, choose Connect next to Guru and enter the email or collection id and the token.
3. From Add source, choose Add from Guru, then pick a card or paste a link.
Guru connects with a user token from My settings → API access, or a collection token. Shuffl reads only the cards that token can open.
Add from Guru lists the verified cards in a collection, searches card titles or takes a card link. Unverified cards can be pasted but aren’t listed.
## BambooHR
1. In BambooHR, create an API key from your account menu.
2. On Knowledge → Connections, choose Connect next to BambooHR and enter the company domain and key.
3. From Add source, choose Add from BambooHR, then pick a file from a category.
BambooHR connects with an API key created by an administrator who can open company files, the same way People → Sync does.
Add from BambooHR lists the categories under Files, searches file names or takes a file link. Employee files are never listed or read.
## Read freshness and review states
A connected source is used in answers only while its last check is under an hour old and the administrator who connected the account can still use it. Check now requests a fresh read but publishes nothing.
Changes need review means the source has new text to review and publish; the older version stops being used as soon as a change is detected. Review due soon means its review date is close.
Sync needs attention, Access lost, Removed from source and Check overdue are recovery states; Access restored means a lost source can be read again.
## Recover a source
1. Open the source and choose the provider’s name under Source to open the original and check that the connected account can still reach it.
2. Fix the access problem with the document owner. If the connection itself does not work, the administrator who connected it should check the account under Connected accounts.
3. Choose Check now if available. If a new draft is ready, review its text, audience and dates, then publish it. Restoring access does not republish a withdrawn document.
4. If unpublished HR edits block the new text, review those edits first.
5. Use source version opens Replace unpublished edits?; Replace with source creates a new draft and keeps the saved edits in version history.
## Disconnect with care
Disconnect and withdraw deletes the stored credential and withdraws every document imported through that connection; drafts, versions and the originals stay. After reconnecting, sources need a fresh check, review and publication. For Google Drive, also remove the authorization in Google Account settings.
## Related guides
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Find a recovery step](https://shuffl.ai/docs/troubleshooting)
Agent documentation index: https://shuffl.ai/llms.txt
---
# People and the org chart
> Find anyone, read the org chart, see who knows whom, and keep the directory right.
Audience: Everyone using Shuffl, with an administrator section
Kind: How-to guide
Canonical: https://shuffl.ai/docs/people
## Find a person
People opens on a search and the list of everyone, with each person’s title, group and location.
Type a name or a topic, choose a department chip, or pick a suggested search such as Who knows a topic or your manager. A topic shows who offered to be asked about it.
Open Filters to narrow by manager, department, job title, location, time zone or Slack. Choose a person to open their profile.
The At a glance tab shows where you sit, how the company has grown, its departments and tenure, and who is in working hours now.
Every figure is a count; nobody’s own dates are shown, and a workspace under five people sees no splits or charts.
You can ask Mello the same things, such as who runs a team or what time it is where someone is. Mello also answers who knows about a topic from people’s profiles, and offers Introduce me to draft a Slack message.
- [Open People](https://shuffl.ai/app/people)
## Org chart, departments and your network
Org chart draws who reports to whom from the manager field in People. Find a person, group or department highlights the match. List shows a foldable outline; Cards shows one reporting line per row, and choosing a card opens the people who report to them.
Network shows You should meet, people Mello thinks you would benefit from knowing, and People you know, from I know them notes and past introductions. Departments are on the Groups tab, under the Departments filter.
- [Shuffl for managers](https://shuffl.ai/docs/managers#your-team)
- [Departments](https://shuffl.ai/docs/groups#departments)
## Get introduced by someone you both know
1. On People → Network, a You should meet card that names people in common has Ask … to introduce you. Choose it.
2. They get a private Slack message with Introduce them or Not this time.
3. Introduce them starts a group DM with the three of you.
4. Not this time ends the request, and you can ask someone else. A request nobody answers lapses after two weeks.
5. You can have three requests waiting at once, and each card says where it stands.
Shuffl can ask a coworker you both know to introduce you. Only the two of you see the request, and if they pass you never hear why.
Slack Home shows your top two under People to meet.
- [Open your network](https://shuffl.ai/app/people?view=network)
- [Ask people who they know](https://shuffl.ai/docs/connections#who-knows-whom)
## Fill in reporting lines
1. Ask Mello proposes who reports to whom from job titles, departments and Slack, with a reason for each line. Untick any that look wrong, then Approve.
2. Set managers gives several people the same manager at once.
3. Import from your HR system opens Sync, so your HR system keeps managers up to date.
While more than one person has no manager, Org chart shows a Fill in who reports to whom panel with three ways to fill it in.
- [Open the org chart](https://shuffl.ai/app/people?view=org)
- [Open Sync](https://shuffl.ai/app/people?view=sync)
## Keep the directory right
1. On People, Invite sends an email invitation and Add person creates a record by hand.
2. Administrators also see access requests and tabs marked HR: Sync, and Insights with people marked as left and gaps in the directory.
3. Choose a row to open the Person details sheet. Employment type lets Mello answer with the right policy.
4. On the sheet, Roles sets the Workspace role and HR responder or Knowledge verifier. Connected accounts shows linked accounts, and Playbooks puts the person on a playbook.
5. Employment and access sets Employment (Not recorded, Employed, On leave or Employment ended) and access, with a reason.
6. Suspending access cancels queued messages and revokes agent keys, and keeps their history.
7. Department on the sheet picks the person’s one department; picking another moves them out of the old one.
8. To add one, choose New group on the Groups tab and pick A department: one per person.
9. Groups on the sheet ticks the lists a person belongs to; rule and synced groups show under Also in.
10. Start dates drive work anniversaries, New hires on Home and onboarding messages.
11. Insights counts joins and people marked as left by week, how complete the directory is and how many people hold each role.
12. Headcount covers 12 months, built from start dates.
- [Open People](https://shuffl.ai/app/people)
## Sync People from your HR system
Sync keeps People in step with your HR system or directory: people, titles, departments and managers, plus start dates from HR systems. Rippling, BambooHR, HiBob and Deel also let Mello read a person’s own time-off balance. Slack is a source too.
Google Workspace needs a separate administrator authorization for read-only access. Disconnect stops sync and removes the stored credential; imported records remain.
Gusto and Justworks wait on each company approving Shuffl’s app. You can request a provider not listed yet from the same tab.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Set up provisioning](https://shuffl.ai/docs/employee-access#provisioning)
- [Set up Sync](https://shuffl.ai/docs/people-sync)
## Related guides
- [Your profile](https://shuffl.ai/docs/your-profile)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [When someone leaves](https://shuffl.ai/docs/when-someone-leaves)
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Sync People from your HR system
> Connect Google Workspace, Microsoft 365, JumpCloud, BambooHR, Rippling, HiBob, Personio, Deel or Workday so People keeps titles, managers, start dates and leavers current.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/people-sync
## What Sync does
Sync fills People from the system you already keep up to date: who works here, their title, department, groups, manager and start date, and who has left.
Shuffl only reads; it never changes a record in your HR system or directory. A start date it brings in can start an onboarding playbook.
Administrators find it on People → Sync, marked HR. Connected lists each source with its last run, and Add a source lists what you can connect.
Under Coming soon, Gusto and Justworks wait on each company approving Shuffl’s app; choose Request, or name another system under Something else?.
Everyone a source brings in arrives with pending access, and a sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Sync in the People guide](https://shuffl.ai/docs/people#sync)
## Connect a source
1. Open People, then the Sync tab.
2. Under Add a source, choose Connect on your system. The dialog lists what to create there.
3. Enter the key, token or report details and choose Connect and sync. For Google Workspace or Microsoft 365, choose Continue with and sign in instead.
4. Shuffl reads your people before saving the connection. If the system refuses, the dialog says why and nothing is stored.
5. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
## What to create in each system
Google Workspace: sign in as an administrator who can read users and allow Shuffl to see users and groups.
If Google says the app is blocked, trust Shuffl under Security → API controls → App access control. Groups list their direct members; nested groups aren’t expanded. Google Workspace has no start dates.
Microsoft 365: sign in as a Global Administrator or Privileged Role Administrator and accept for your organization.
Shuffl reads users, hire dates and group memberships, leaving out guests, shared mailboxes and room accounts. If you already push people from Entra ID with SCIM, keep one of the two.
JumpCloud: in the Admin Portal, open your administrator menu (top right), choose API Settings and generate or copy an API key. Keys expire after 90 days by default, so note when to rotate it. JumpCloud has no start dates.
BambooHR: as an administrator, open your name (top right), choose API Keys and add a key named Shuffl.
Enter it with your Company domain, the part before .bamboohr.com. Shuffl adds a webhook with the key so changes arrive as they happen; without one it reads daily.
Rippling: open Tools → Developer → API Tokens and create a token with companies.read, departments.read, teams.read, users.read and workers.read, plus leave-balances.read for time off. Rippling expires a token unused for 30 days, so keep Sync connected.
HiBob: under Settings → Integrations → Service users, create one named Shuffl with a permission group that can view Basic info, Work and Lifecycle for all employees, former ones included.
Enter its ID and token. For live changes, add the Connect dialog’s webhook address under Automation → Webhooks and paste Bob’s secret into Webhook secret.
Personio: under Settings → Integrations → API credentials, generate a credential named Shuffl that reads Employees. It needs name, preferred name, email, status, position, supervisor, department, team, hire date and termination date. Enter the Client ID and Client secret.
Deel: open More → Developer → Access Tokens and generate an organization token with people:read and organizations:read, allowing work emails. Deel’s contractors get the Contractor employment type in People.
Workday: give an integration system user access to workers, organizations and managers, and share with it an advanced custom report of all workers, leavers included. Its fields are Employee_ID, Preferred_Name, Email, Business_Title, Manager_Employee_ID, Supervisory_Organization, Hire_Date, Active and Termination_Date.
Enable it as a web service and enter its URL from Actions → Web Service → View URLs with ?format=json, plus the user and password.
## What Slack fills in
Slack is listed under Connected once Slack is connected. On every plan, Shuffl reads names, emails, photos, titles, time zones and deactivations from it.
Start dates and managers come from Slack Atlas, or from custom profile fields named Start date, Hire date or Joined and Manager or Reports to. If Slack asks for permission again, reconnect to read custom fields.
Slack fills these only for people no other source manages, and a blank keeps what People has. Managers and custom fields are read on each sync, so choose Sync now on the Slack card after a reorganization.
- [Connect Slack](https://shuffl.ai/docs/slack)
## What Shuffl reads and which value wins
Shuffl reads every source daily. BambooHR, and HiBob with a webhook secret, also send changes as they happen. Each card says which.
Shuffl links each record to a person by the source’s id, then by a work email matching exactly one person. Anyone else becomes a new person; a former employee never in People is not imported.
Name and email stay with Slack or SCIM when either holds the person. Job details come from the source: title, department, groups, manager, start date, and employment type and time zone when sent.
A source overwrites those fields on every read, so correct mistakes in the source. A blank keeps what People has, so start dates typed in People survive Google Workspace and JumpCloud.
If you also use an HR system, connect it first so it owns start dates.
Departments are groups marked Department on People → Groups. They are created from the source’s names, or matched by name, and follow renames; a new department moves the person out of their old one.
Groups you bring in follow the source; groups made in Shuffl stay as they are.
A manager is set when the source names one who is also in that source. Shuffl never clears or invents a manager and skips one that would create a loop.
Start dates drive anniversaries, New hires on Home and onboarding dates. Shuffl also keeps a first hire date when the source sends one or someone returns.
HR systems that send a termination date set the person’s last day in People, never with a reason, as not announced. A later start date clears it.
If two sources list the same person, the first keeps them; disconnecting it hands them to the next.
- [Fill in reporting lines](https://shuffl.ai/docs/people#reporting-lines)
- [Start dates and anniversaries](https://shuffl.ai/docs/celebrations#start-dates)
## Starters and leavers
A future hire arrives with pending access. Once the source shows them active, Employment becomes Employed.
When an HR system shows someone as terminated or inactive, or their last day has passed, Shuffl sets Employment ended and suspends their access. An archived Google Workspace user is treated the same way.
A suspended or turned-off directory account, or an inactive HiBob one, has access suspended and employment left as it was. JumpCloud has no terminated state, so record Employment ended yourself.
Workday ends employment from Active or a passed Termination_Date, so keep leavers in the report.
Someone a source stops listing is counted as no longer listed, never suspended. Enable a returning employee yourself.
- [When your HR system says they left](https://shuffl.ai/docs/when-someone-leaves#automatic)
- [Enable access](https://shuffl.ai/docs/employee-access#link)
## Time-off balances
With BambooHR, Rippling, HiBob or Deel, Mello can tell an employee their own time-off balances when they ask in their own chat. It uses that system’s policy names and units and says the date they are as of.
Mello reads only the asking person’s balances, never in a shared channel, and never guesses a number. It can prepare an HR request with the dates.
The key or token must be allowed to read time off; the source’s card says whether it can.
- [What Mello knows about you](https://shuffl.ai/docs/ask-mello#what-mello-knows)
## Choose which groups come in
1. Open People → Sync and choose Groups on the source’s card.
2. Turn on In Shuffl for each group you want. Shuffl starts a sync so its members arrive.
3. Leave Show on profiles on for teams people work in, and turn it off for groups that only HR uses.
Teams and groups from a source or Slack don’t come in by themselves. Each sync lists them on the source’s Groups screen with their size, so mailing lists stay out of People.
A group you bring in follows the source at every sync. Turn it off and it stays in Groups as a list for you to keep or delete; turn it on again to follow the source.
- [Groups from Slack and People sync](https://shuffl.ai/docs/groups#synced)
## Read a sync and fix a failed one
1. When a card shows Needs attention, the provider refused the key. Create a new key, token or password in that system.
2. Choose Connect on the same system and enter the new details. Shuffl replaces the stored key and runs a sync.
3. For Google Workspace or Microsoft 365, sign in again as an administrator.
4. For Microsoft 365, Needs attention usually means someone removed Shuffl under Enterprise applications in Entra.
Each card shows how many people the source manages and when it last synced. Its last run is a row of chips: New, Linked, Updated, Managers, Not listed and Skipped, such as people another source manages. Counts of zero are left out.
Sync now queues a read straight away. It runs within a minute; refresh to see the result.
A failed run changes nobody and says why on a red chip, such as Credential refused. Shuffl tries again at the next daily read.
## Disconnect a source
Choose Disconnect on the source’s card and confirm. Syncs stop, the stored key is deleted, and every person stays in People to edit by hand.
Shuffl removes its BambooHR webhook. Remove a HiBob webhook or Google authorization yourself. To rotate a key, connect the same source again instead.
## Related guides
- [People and the org chart](https://shuffl.ai/docs/people)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [When someone leaves](https://shuffl.ai/docs/when-someone-leaves)
- [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/celebrations)
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Groups
> Live groups of people kept by rules, picked by name or synced from Slack and your HR system, departments with one per person, and starter groups. Automations act for each person who joins or leaves. Everyone can browse the groups shown on profiles.
Audience: Employees and workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/groups
## Keep a group by rules
A group is a live set of people that Pulse questions, programs and messages can be aimed at.
On People → Groups, choose New group, keep A group under What it is, name it, choose Rules under How it is kept and write what a person must match. Shuffl re-evaluates it every ten minutes and when you save.
A rule names an attribute from People, such as start date, last opened Shuffl, department, manager, job title, employment, location, Slack account linked, community or Connections program. A rule can also name another group, so one group can build on another.
Every rule must hold, and a rule can take several values, such as a department that is one of Engineering or Product. And any of adds a sub-group where one row is enough. Preview who matches shows how many people match now before you save.
- [Open Groups](https://shuffl.ai/app/people?view=groups)
## Pick people by name
A list holds exactly the people you pick: choose A list: people you pick under How it is kept, then find each person by name. It changes only when someone edits it, so it suits a pilot or a committee.
A list is also how you keep a team. Edit it here, or tick Groups on a person’s details sheet in People.
## Show a group on profiles
Teams are groups. Turn on Show on profiles and the group shows on its members’ profiles, in the org chart and in search. Leave it off for lists only HR uses, such as On leave.
The HR team is a group of the HR responders who answer private HR requests. It always shows on profiles and can’t be removed.
## Departments
1. Open People, then Groups, and choose New group. Under What it is, choose A department: one per person.
2. Name it, such as Customer Success, and pick the people in it by name.
3. A department is always a list with no rules, and it has no Show on profiles switch because profiles already show each person’s department. Choose Create the department.
4. Adding someone to a department moves them out of the one they were in. To change one person, open their Person details sheet in People and pick a Department.
5. Remove the department on its page deletes it, and its people have no department until you pick a new one. Departments can’t be archived.
A department is a group, such as Engineering or Sales, marked Department on the Groups tab. Each person is in one department at most. The filter above the list reads All groups, Departments or Other groups; choose Departments to see only them.
One department per person lets Pulse, eNPS and Culture compare departments without exposing anyone. Nobody is in two, so nobody can work out a small team’s answers by subtracting one total from another.
Connections across departments, Knowledge audiences, the org chart and profiles use the same departments; each person’s department shows on its own line.
With People sync, the department field in your HR system fills departments for you. Shuffl makes a department for each name it reads, or uses the one you already have with the same name, and follows renames.
Fix a wrong department in the HR system, since the next sync replaces a change made by hand.
- [Open Departments](https://shuffl.ai/app/people?view=groups&type=departments)
- [New department](https://shuffl.ai/app/groups/new?department=1)
- [Departments from People sync](https://shuffl.ai/docs/people-sync#what-syncs)
- [How Pulse keeps answers private](https://shuffl.ai/docs/pulse#who-sees-what)
## Groups for everyone
Everyone has the Groups tab on People. Employees see the groups shown on profiles, not departments, their own first, each with a few faces and a count. Groups with Show on profiles off stay with HR, even for someone with a link.
A group with five people or more has a glance at the top of its page: headcount, departments, tenure and who is in working hours. Smaller groups skip it so no figure points at one person.
A group’s page lists everyone in it, each opening their profile; Open in People shows them with People’s filters. Administrators also see the group’s rules, messages, automations and activity.
- [Open Groups](https://shuffl.ai/app/people?view=groups)
## Groups from Slack and People sync
Slack user groups and groups from People sync come in only when you choose them: on People → Sync, choose Groups on the source’s card, SCIM included.
Their name and members follow the source, but you can describe, show, message and automate them, and aim features at them.
Once groups are synced, a filter above the list picks Every source, Made in Shuffl, From Slack or From People sync.
## Starter groups
New group opens on the groups most HR teams want first, such as Managers, New this quarter, Not on Slack and On leave, with today’s count.
Choose one and Shuffl makes it, keeps it by rules you can change, and opens it. Blank group and Department are below them.
## A group’s page
A group’s page shows its headcount over a month and who joined and left this week. When people join or leave, above the tabs, holds its automations.
Members lists everyone with when they joined, and Rules (Settings for a synced group or a department) holds the form; saving re-evaluates the group at once. Messages and Activity follow.
Refresh now re-evaluates the group at once. Remove deletes it with its history; removing a department leaves its people with no department. If a refresh fails, the group says so and keeps its last members.
## Message a group
Choose Message on a group’s page to write to everyone in it. {{first_name}}, {{manager}} and {{company}} fill in for each person, and a button can open a page of Shuffl. It goes on each person’s chosen channel, or only Slack or only email.
Check who gets it previews the message and counts who it reaches, leaving out anyone HR already messaged today (one message from HR a day) or who can’t be reached. Nothing goes out until you choose Send.
In Slack it arrives as a direct message from Shuffl, and a reply in its thread becomes an HR request. People can choose Slack or email for HR messages, but can’t turn them off.
## Automate what happens when someone joins or leaves
An automation does one thing for each person who joins or leaves a group.
It can send a message, ask a Pulse question, start a playbook (you still approve their steps), invite to a community, add to Connections or give a badge.
It can also change another group, add to or post in a Slack channel, or tell HR, their manager or someone named.
A Slack channel must be one Shuffl is in. Each person is added with their linked Slack account, and a post says they joined the group, with your note; posts are for joins only. If Slack refuses, the run says why.
How soon runs it within ten minutes or 1 to 90 days later, such as a Pulse question a week after someone joins. When the day comes, someone who has moved back is skipped.
Pulse answers from an automation are pooled across everyone it asks, stay anonymous and show under the question once the reporting floor is met. A retired question is asked only by automations. Adding someone to another group runs that group’s automations too.
Automations, under Programs in the HR workspace, lists every automation by group with On, Pause and Edit. It includes playbooks that start on each start date or last day, and Connections programs whose people come from a group.
Choose Add an automation, then a group, A new hire gets a start date or Someone gets a last day.
On a group’s page, When people join or leave sits above the tabs. Ideas at the bottom of Automations and on the group’s page suggest automations that fit, such as Start their playbook for New this quarter. Choosing one opens the dialog filled in.
A playbook’s, Connections program’s or invite-only community’s page says what starts it, with Automations that start this. A new automation starts paused; Turn on starts it.
Each runs once per person and entry, and skips people with pending access, ended employment or a message from HR already that day.
Insights, the second tab, counts runs done, skipped and failed over 30, 90 or 180 days against the period before.
It also shows the people reached, runs by week and kind, and the top reasons runs did nothing. Choose a group to see only its automations.
Runs, the last tab, lists every run newest first: who it was for, what it did, and whether it was done, skipped, scheduled or failed, with why.
Filter by outcome or by group; Show older runs loads 50 more. A group’s Activity tab shows its own runs.
## Do something with a group
Actions on a group’s page opens Pulse, a playbook’s Add people, a community invitation or a new Connections program with the group already chosen. Export members as CSV downloads each member’s name, email, job title, department, manager and join date.
Ask Mello can say who is in a group or how many people it holds.
## Worked examples
Each example pairs a group with a feature it feeds. Make the group first.
## Example: start every new hire’s onboarding on their own
1. Make a group called New hires kept by Rules, with the rule Started within 30 days.
2. On the group’s page, under When people join or leave, add When someone joins and Start a playbook with the playbook new hires follow, then Turn on.
3. Add When someone joins and Tell their manager, with a note such as Plan their first one to one this week.
4. Each new hire now joins the group, is enrolled and their manager hears. You still approve each hire’s schedule on the playbook.
5. For hires already in the group, choose Actions → Start and the playbook’s name once.
- [Enroll hires in a playbook](https://shuffl.ai/docs/playbooks#enroll)
- [Make a group](https://shuffl.ai/app/groups/new)
## Example: ask managers a Pulse question of their own
1. Make the Managers starter group.
2. Choose Actions → Ask a Pulse question. Pulse opens with Managers chosen under Who gets it; write the question and add it.
3. If the group is smaller than your reporting floor, the picker warns that its answers would never be shown.
4. To move an existing question, choose Set group beside it on Pulse → Questions.
5. On Pulse → Insights, By group shows each group’s results beside Everyone, whoever was asked.
- [How Pulse groups work](https://shuffl.ai/docs/pulse#administrators)
## Example: coffee chats for one office or across two departments
1. Make a group with a Location rule for the offices, or a Department rule naming two departments that rarely meet.
2. Choose Actions → Start a Connections program; the group is already under Who takes part.
3. Pick the Slack channel and schedule, and start it. People who join or leave the group join or drop out from the next round.
- [Set up a Connections program](https://shuffl.ai/docs/connections#program)
## Example: get a new policy read by the people it affects
1. Publish the policy in Knowledge and choose Ask to confirm.
2. Open the group that most needs to act, such as Managers, and choose Message.
3. Under Button choose Open a page of Shuffl, label it Read the policy and paste the policy’s /app address.
4. Choose Check who gets it, then Send. Replies in Slack land in the Inbox as HR requests.
5. Confirmations on the policy shows who has read it; Remind nudges the rest, at most once a day.
- [Ask people to confirm a policy](https://shuffl.ai/docs/knowledge#confirm)
## Example: reach the people who are not on Slack
1. Make the Not on Slack starter group.
2. Choose Message, set Send it to Email only, and explain how to join Slack.
3. Add When someone leaves and Tell HR to hear as each person links Slack.
- [How people choose Slack or email](https://shuffl.ai/docs/notifications)
## Example: hear when someone comes back from leave
1. Make the On leave starter group: everyone whose employment in People reads on leave.
2. Add When someone leaves and Tell their manager, with a note such as Back from leave: book a return conversation, and Tell HR if HR runs the return.
3. Leaving the group is the return, so the note arrives within ten minutes.
- [Employment status in People](https://shuffl.ai/docs/people)
## Example: grow a community from a group
1. Make an invite-only community you manage, such as Austin office.
2. Make a group of who should be invited, by rules or as a list.
3. Choose Actions → Invite to a community, then add When someone joins and Invite to a community for later joiners.
- [Communities and their channels](https://shuffl.ai/docs/communities)
## Example: ask every new hire how their first week went
1. On Pulse → Questions, add a question such as I knew who to ask for help this week, then retire it so only automations ask it.
2. Open your New hires group. Add When someone joins, How soon 7 days later, Ask a Pulse question with that question, then Turn on.
3. Each hire is asked a week in. Results show under the question once enough hires answer.
- [How Pulse results stay anonymous](https://shuffl.ai/docs/pulse#administrators)
## Example: chain groups so one move sets off the next
1. Make a list group called Alumni.
2. On a group such as Contractors and interns, add When someone leaves and Add to a group with Alumni.
3. Automations on Alumni, such as Tell someone in payroll, run as each person arrives.
## Related guides
- [People and the org chart](https://shuffl.ai/docs/people)
- [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/pulse)
- [Introduce coworkers with Connections](https://shuffl.ai/docs/connections)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Communities](https://shuffl.ai/docs/communities)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Share a request with HR
> Choose who answers HR requests, review what you share before it is sent, and work the queue in the Inbox.
Audience: Employees, HR responders and workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/hr-requests
## Administrator: choose responders
1. Open People, choose a person and turn on HR responder under Roles. Owners start as responders; administrators don’t unless you add them.
2. Settings → Roles and access lists every responder and the HR team name employees see.
3. A responder needs an enabled account of their own. If nobody eligible appears, enable the person in People first.
4. Responders get a Slack direct message for each new request, or an email if their Slack account is not linked.
New responders get new requests only. Existing requests keep the responders the employee approved. Removing someone takes effect at once.
- [Open Roles settings](https://shuffl.ai/app/settings/roles)
- [Prepare responder access](https://shuffl.ai/docs/employee-access)
- [Where requests reach responders](https://shuffl.ai/docs/answer-hr-requests#arrive)
## Administrator: categories and response target
1. Open the Inbox from the HR workspace, then Request settings at the foot of the page.
2. A note says whether Mello built the list from Knowledge or it is the starting list.
3. Rename, add or remove categories if you want to. Keep the list short.
4. Choose an owner for each one, or leave it with anyone on the HR team.
5. Turn on Only named people can open these requests for sensitive topics, and tick who can.
6. Set the response target: how soon HR should first reply, in business days. Weekends don’t count.
Mello builds the categories from your published Knowledge and updates them as you publish more; until then a starting list is used. Once you edit the list, Mello leaves it alone, and Rebuild from Knowledge brings Mello’s back.
Mello puts every new request in one category and tells its owner first. Responders can move a request to another category.
A sensitive category, such as complaints or medical leave, opens only for the people you name; other responders can’t list or open those requests, even with a link. The person who asked always sees their own request.
- [Open Request settings](https://shuffl.ai/app/requests/settings)
## Employee: review before sharing
1. Ask Mello in Chat or a Slack direct message. When a person needs to help, Mello prepares a short message and names the responders who would receive it.
2. Read it. Choose Edit message to change it, and include only what you want HR to see.
3. Choose Share with HR on the web or Send to HR in Slack once the message and recipients look right. Nothing is sent before that.
4. Replies arrive in the same chat or Slack thread, with who on HR wrote them.
5. HR requests in your Chat history lists every request you sent, each with Mark resolved, and Reopen question once resolved.
HR receives the reviewed request, not your whole conversation. If HR is not set up, contact your HR team the usual way.
Slack message, Handoff to HR (The person asking Mello, in their DM; When Mello can’t answer and offers to ask HR):
```text
Ready to send to HR
```
Slack message, HR’s reply (The person who asked, in the same DM thread; When HR sends a reply):
```text
HR replied: Congratulations! You can take up to *16 weeks* of paid parental leave.
Tell your manager when you apply in Shuffl, and I’ll handle the rest.
```
Slack message, Your HR requests (Whoever asks Mello about their requests, in their DM; When someone asks Mello where their HR requests stand):
```text
Your HR requests
```
## Responder: own and answer a request
Responders see open requests in the Inbox and on the Shuffl app’s Home tab in Slack.
A request opens beside the list, or over it on a phone, with the employee’s reviewed message and the thread so far. Take ownership tells others you have it; Release to HR team hands it back.
Write your reply and choose Send reply, or Draft with Mello to have it drafted in Chat; the employee gets it in their original conversation.
Mark resolved asks how it was answered: by a published article, Needs an article, or No article needed. If you can verify Knowledge, Needs an article also starts a draft from your last reply.
Reopen question brings a request back. A reply sent from Slack or the web shows in both.
In Slack, a new request arrives from Shuffl as a card with its category, who asked and the question quoted. Reply drafts an answer with Mello in the thread; Assign to me tells others you have it.
Slack message, New HR request (HR responders for the request’s category, privately; When someone sends Mello’s handoff to HR):
```text
New HR request from Mei Lin Zhou: My partner is having a baby in March. How much parental leave can I take, and do I need to tell my manager before I apply?
```
Slack message, Knowledge draft for review (The person who can verify Knowledge, in their DM; When Mello turns an HR answer into reusable guidance):
```text
Knowledge draft for your review: Parental leave
```
- [Open the Inbox](https://shuffl.ai/app/requests)
- [The responder’s full routine](https://shuffl.ai/docs/answer-hr-requests)
## See how requests are going
Culture shows four HR request tiles for administrators. All figures opens the full page: how many requests came in, time to first reply and to resolve, the share answered within target, and how many wait on HR.
By category lists the busiest categories first, with how many need an article. Review the top ones each quarter and write the articles they need.
The weekly HR digest carries the totals to administrators and responders.
- [Open HR request figures](https://shuffl.ai/app/insights/culture/requests)
## Product help is a separate conversation
Help & feedback → Contact Shuffl is for product questions, not your organization’s HR requests.
## Related guides
- [Ask Mello](https://shuffl.ai/docs/ask-mello)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Culture, what Mello handled and the HR digest](https://shuffl.ai/docs/impact)
- [Answer HR requests as a responder](https://shuffl.ai/docs/answer-hr-requests)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Answer HR requests as a responder
> Your daily routine as an HR responder: find new requests, take one, reply or ask for more, close it so Knowledge grows, and hand it on when you’re away.
Audience: HR responders
Kind: How-to guide
Canonical: https://shuffl.ai/docs/answer-hr-requests
## Where new requests arrive
Each new request notifies one responder: its category owner, or else someone else on the HR team who can open it. Everyone who can open it sees it in the Inbox.
In Slack, the request arrives from Shuffl as a card with its category, who asked, when a reply is due and the question. It has Reply, Assign to me and Open in Shuffl.
Otherwise you get an email, New HR request, which leaves out what they wrote and links to it.
On the web, open the Inbox from the HR workspace or the card on Home. The Shuffl app’s Home tab in Slack lists up to five waiting requests.
Slack message, New HR request (HR responders for the request’s category, privately; When someone sends Mello’s handoff to HR):
```text
New HR request from Mei Lin Zhou: My partner is having a baby in March. How much parental leave can I take, and do I need to tell my manager before I apply?
```
- [Open the Inbox](https://shuffl.ai/app/requests)
- [How administrators choose responders](https://shuffl.ai/docs/hr-requests#responders)
- [Choose Slack, email or both](https://shuffl.ai/docs/notifications#choose)
## Read the Inbox
The Inbox is one list, overdue first: unresolved HR requests, Knowledge drafts to verify, guidance to re-check and Pulse actions past due. The chips above it show All, Mine, Unassigned, Overdue, Reviews and Pulse. Requests you sent yourself never appear here.
Each row shows its category, who asked and who has it, how long it has waited and its status: Open, Waiting on HR, Waiting on employee or Reply overdue. A lock means only named people can open it.
Start with anything overdue. Arrow keys move between rows and Enter opens one. When nothing waits, the page says You’re all caught up.
## Take a request and reply
1. Choose the request in the Inbox. It opens beside the list, or over it on a phone.
2. Choose Take ownership. If the category is wrong, change it in the Category menu.
3. Write your reply in the box under the thread and choose Send reply. It goes to the employee as written.
4. For a longer answer choose Draft with Mello. In Chat, tell Mello how you’d answer; it shows Your reply is ready to review.
5. Read it. Choose Edit message to change the wording, tick Send this message to and the employee’s name, then choose Send reply. Cancel reply drops the draft.
One responder owns a request at a time; others can read it but can’t reply. Replying to a request nobody owns makes it yours.
To ask for more detail, reply with your question. The request moves to Waiting on employee until they answer, then back to Waiting on HR.
In Slack, choose Reply on the card and tell Mello in the thread how you’d answer. Nothing is sent until you press Send reply. Assign to me and Unassign take and release ownership.
## What the employee sees
The employee sees their request under HR requests in Chat and, if they asked in Slack, in that thread. They never see its category, due time or how you closed it.
Before anyone takes it, the status is Sent to HR; once you do, it says your name is helping and the status is Waiting on HR.
Your reply arrives quoted in their Slack thread with your name, or as an email if they chose that. Their status changes to HR replied, with Resolved and Still need help in Slack.
Still need help, or a message back, returns it to you as Waiting on HR. If they resolve it themselves, it closes without a note on how it was answered.
Slack message, HR’s reply (The person who asked, in the same DM thread; When HR sends a reply):
```text
HR replied: Congratulations! You can take up to *16 weeks* of paid parental leave.
Tell your manager when you apply in Shuffl, and I’ll handle the rest.
```
- [How employees share a request](https://shuffl.ai/docs/hr-requests#share)
## Mark a request resolved or reopen it
1. In the request, choose Mark resolved.
2. Choose how it was answered: Answered by an article (pick the article), Needs an article, or No article needed for a one-off.
3. Choose Mark resolved in the dialog. The request leaves the Inbox.
Only the owner can mark a request resolved or reopen it, on the web. In Slack, use Open in Shuffl.
Reopen question brings a resolved request back as Waiting on HR and clears how it was closed. The employee can reopen it too.
## Turn a good answer into Knowledge
1. Find the draft under Reviews in the Inbox, or in Slack as a Knowledge draft card.
2. Choose Review. Take out anything about the person who asked and any one-off exception.
3. Choose who can use the answer under Who can use this answer?, and set the Effective date and Review again.
4. Choose Approve knowledge, or Decline. In Slack, Approve for everyone approves it for the whole workspace.
When you send a reply that holds guidance others would need, Mello proposes it as Knowledge, leaving out anything naming the employee or an email address. Closing with Needs an article drafts one from your last reply.
Both happen only if you can verify Knowledge, as administrators and Knowledge verifiers can. Otherwise Needs an article is still counted in Request insights.
Employees never see a draft until someone approves it. Then Mello can answer the same question from it.
- [Verify what Mello proposes](https://shuffl.ai/docs/knowledge#verify)
## Sensitive categories and the response target
A request shows Sorted by Mello until someone changes its category. If you’re not named on a locked category, you can’t list or open its requests, even with a link.
Moving a request into a sensitive category you aren’t named on removes it from your queue at once. If its owner isn’t named either, it goes back to Open for the named people.
The response target counts business days from when the request was sent; Saturday and Sunday don’t count. First reply due shows until the first reply goes out.
Request insights is for administrators. Others get the count waiting on them in the weekly HR digest.
- [Set categories and the response target](https://shuffl.ai/docs/hr-requests#categories)
- [Request insights for administrators](https://shuffl.ai/docs/hr-requests#insights)
## Hand over when you’re away or leaving
A request can only be opened by the responders it was shared with who still hold the role. A responder added later doesn’t see earlier requests.
If you’re away, choose Release to HR team on each request you own, or Unassign in Slack. It reads Ready for someone in HR until another responder takes ownership.
When a responder loses their role or access, their requests read The previous responder no longer has access, and anyone else on the request can take ownership. An administrator also reassigns their categories in Requests → Settings.
If nobody on a request still has access, the employee is asked to contact HR the usual way. Hand requests on before access ends.
- [Hand on what a leaver looked after](https://shuffl.ai/docs/when-someone-leaves#hand-over)
## Related guides
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [When someone leaves](https://shuffl.ai/docs/when-someone-leaves)
- [Notifications and reminders](https://shuffl.ai/docs/notifications)
Agent documentation index: https://shuffl.ai/llms.txt
---
# When someone leaves
> Record that someone has left, turn off their access and hand on what they looked after, by hand or from your HR system or identity provider.
Audience: HR administrators and workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/when-someone-leaves
## Employment ended, suspended or on leave
Everyone in People has two settings under Employment and access. Employment records the facts: Not recorded, Employed, On leave or Employment ended. Employee access decides whether they can use this workspace: Enabled or Suspended.
When someone leaves, set Employment ended. It suspends their access in the same save and takes them out of the directory, org chart, headcount, celebrations, praise and badges.
Suspending access alone keeps them counted as employed, so use it for a pause. On leave changes neither.
## Record that someone has left
1. Open People and choose the person to open their Person details sheet.
2. Expand Employment and access and set Employment to Employment ended. Employee access changes to Suspended.
3. Under Reason for change, say why in a few words, such as their last day.
4. Choose Save access. The sheet shows No enabled seat, and Recent activity records Access suspended.
You can’t change your own access; another administrator does it. To find everyone who has left, open Filters on People and choose App access: Suspended.
If someone comes back, set Employment to Employed and Employee access to Enabled, with a reason. Restore a deactivated Slack account first, and with SCIM, their assignment in your identity provider.
- [Open People](https://shuffl.ai/app/people)
## What stops at once
Suspending blocks the person from this workspace on the web, with Mello in Slack and through the API. If they open it, they see Your workspace access is suspended. Nothing they made is deleted.
In the same save, Shuffl cancels Mello answers and Connections introductions waiting to reach them, and revokes the workspace API keys they created. A revoked key stays revoked if their access comes back.
A new hire is removed from their onboarding program and its unsent messages are cancelled. If they were someone’s buddy, that hire loses them: open the program, choose Choose a buddy on the hire’s row, then Review and approve messages.
New Pulse questions and Connections rounds leave them out. Pulse answers they already gave can’t be traced to them and stay in the totals until deleted, 90 days after each question closes.
## What Employment ended changes
Coworkers can no longer open their profile, and they leave the org chart; their reports show without a manager until you set one. People Insights counts them under Marked as left.
Celebrations stops for them: no birthday or anniversary messages or cards, and no asks to sign cards for others.
They can’t be given praise or earn new badges. Praise and badges from before stay.
## Hand on what they looked after
1. Reporting lines: open People, then Org chart, and choose Set managers to give their reports a new manager.
2. With Sync, the next update from your HR system does this once it shows the new manager.
3. Roles: a suspended HR responder or Knowledge verifier reads Inactive and gets no new requests.
4. Turn the role off under Roles on their sheet; if they are the only HR responder, make someone else one first.
5. HR requests they owned wait for HR to take over. Another responder opens each from the Inbox and chooses Take ownership.
6. In Request settings, give each category they owned a new owner, and tick someone else on categories only named people can open.
7. Requests they sent as an employee stay with HR, but replies no longer reach them. The responder who owns one can choose Mark resolved.
8. Communities: Shuffl doesn’t remove them. An owner or moderator chooses Manage (See all for a moderator) under Members, then Remove beside their name.
9. Make someone else owner first if they were the only one. The Slack channel is left alone.
Suspending them doesn’t unpublish any Knowledge. Reviews that come due show in the Inbox for every Knowledge verifier and administrator.
- [Open the org chart](https://shuffl.ai/app/people?view=org)
- [Open Request settings](https://shuffl.ai/app/requests/settings)
- [Own and answer a request](https://shuffl.ai/docs/hr-requests#follow-up)
- [Hand over as a responder](https://shuffl.ai/docs/answer-hr-requests#hand-over)
## Remove them from the company
1. Open Settings → Company → Members, open the actions menu on their row and choose Remove from company.
2. Confirm Remove company member?. They lose access to every workspace in the company, with employee access suspended in each. Their contributions remain.
3. Administrators can remove members; only owners can remove administrators or other owners. Nobody can remove themselves here, or the last owner.
Suspending works in one workspace. Their company membership stays, and so does a company owner or administrator role, which keeps Company settings open to them until you remove them from the company.
Removing someone doesn’t record that their employment ended, so set Employment ended in each workspace as well.
A company API key acts as the person who created it, so their keys show Paused while they aren’t a company owner or administrator. To end them for good, choose Revoke key on each in Settings → API keys and webhooks → Company keys.
- [Open Company members](https://shuffl.ai/app/settings/company/members)
- [Open Company API keys](https://shuffl.ai/app/settings/company/api-keys)
- [Remove members with a company key](https://shuffl.ai/docs/api-permissions#company-keys)
## When your HR system or identity provider says they left
With Sync, when an HR system reports someone as terminated or inactive, or their last day has passed, Shuffl sets Employment ended and suspends their access. The reason names the provider.
A suspended or turned-off directory account has access suspended and employment left as it was.
Someone a source stops listing is left as they are. Sync never turns access back on.
With SCIM provisioning, deactivating or unassigning someone in your identity provider suspends their access at once without ending employment. Assigning them again restores access unless someone changed it by hand or their employment ended.
Deactivating someone’s Slack account suspends their access too, and it can’t be enabled again until the Slack account is restored.
However access is suspended, the same things stop. Handing on roles, requests and communities is still yours.
- [Sync People from your HR system](https://shuffl.ai/docs/people#sync)
- [Provision people from your directory](https://shuffl.ai/docs/employee-access#provisioning)
- [Starters and leavers in Sync](https://shuffl.ai/docs/people-sync#starters-and-leavers)
## Deleting their data
People has no action that deletes a person. Their record and history stay after they leave. To erase someone’s personal data, follow the privacy guide.
- [Privacy and data](https://shuffl.ai/docs/privacy-and-data)
## Related guides
- [People and the org chart](https://shuffl.ai/docs/people)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Companies and workspaces](https://shuffl.ai/docs/companies-and-workspaces)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Privacy and your data](https://shuffl.ai/docs/privacy-and-data)
- [Answer HR requests as a responder](https://shuffl.ai/docs/answer-hr-requests)
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Playbooks and onboarding
> Put people on a playbook of messages, Knowledge links and to-dos counted from a day 0. Onboarding adds a buddy and anonymous check-ins on day 30, 60 and 90.
Audience: Workspace administrators, new hires and buddies
Kind: How-to guide
Canonical: https://shuffl.ai/docs/playbooks
## Create a playbook
1. Open Playbooks from the HR workspace. With no playbook yet, Mello suggests a filled-in onboarding playbook: choose Review and start, Change something or Not now.
2. Or choose New playbook and start from a template, or ask Mello in Chat to draft one from your handbook.
3. Details: name the playbook and choose day 0: each person’s start date, the day they join, or one date for everyone.
4. Choose the accountable HR responder, the local send time and the default time zone.
5. Steps: turn the buddy and the help check-in on or off.
6. Choose any step to change who it goes to, its day or its words, or to remove it, and Add step to write your own.
7. The preview fills in {{hire}}, {{buddy}} and {{manager}} with sample people.
8. People: choose who starts it now, by name or everyone in a group, department or community (members who show it on their profile).
9. Or leave it empty and use Add people later.
10. Review shows the playbook in numbers: steps, check-in days, to-dos for the manager and the hire, and who it starts with.
11. Choose Start playbook, or Save draft to finish later. Starting adds the people you chose with their steps waiting for approval; a draft adds nobody.
12. Insights shows hires in progress, buddy acceptance and check-ins answered.
- [Open Playbooks](https://shuffl.ai/app/playbooks/all)
- [Onboarding messages and checklist to copy](https://shuffl.ai/templates#category-onboarding)
## Write the playbook
1. Under Steps on the playbook’s page, every step sits on one timeline, from Before day 1 to Months 2 and 3, including the buddy invitation, introduction and help check-in.
2. A program with only those three shows Add starter playbook, which adds the starter to-dos and check-ins.
3. Choose Add step. Pick Message, To-do, Check-in or Read and confirm, and write a title.
4. Choose who it goes to (the hire, their manager, their buddy, the HR responder or someone you name) and the day.
5. A message can carry a checklist and links to published Knowledge, a web page or a community. Link Knowledge the recipient can read. Use {{hire}}, {{buddy}}, {{manager}} and {{start_date}}.
6. A Check-in is a day 30, 60, 90 or one-year check-in, or your own questions on any day, answered anonymously. See The first 90 days below.
7. Each template starts with to-dos for the manager and the hire, a welcome, and first-day and first-week checklists.
8. Saving sends only the changed steps back for approval. Removing a step cancels it for everyone not sent yet, along with its open to-dos.
9. An open to-do for the manager, buddy or someone you named gets one Slack reminder a day after its day, with Done, Snooze to Monday and Stop these reminders.
10. The hire gets one only when HR nudges them. Change the timing under To-do reminders on the Settings tab of Playbooks.
## Add people and approve their messages
1. Choose Add people and pick people, everyone in a group, department or community under A group or team, or a CSV with emails, start dates, time zones and buddies.
2. Start dates and time zones come from People.
3. Counted from the day someone joins, day 0 is today unless you pick another date. With one date, everyone starts on it.
4. Choose a buddy for each hire from the suggestions, or leave it empty and let the hire ask someone. The buddy accepts or declines right in Slack, or in Shuffl.
5. On the Messages tab, choose Review and approve messages, read each message with its date and recipient, tick that you reviewed them and approve.
6. A step with nobody to send to is skipped. Changing a date, buddy or message sends that hire back for approval.
7. Messages go out in the hire’s own time zone, in Slack. A hire or buddy without a linked Slack account waits until they have one.
- [Start every new hire’s playbook on their own with a group](https://shuffl.ai/docs/groups#recipe-new-hires)
## See how each hire is doing
1. Needs attention flags to-dos more than a day past their day, whoever owns them.
2. It also flags pages sent to read and confirm that are unconfirmed after three days, and a help request nobody has resolved.
3. Mello’s panel lists who to nudge. Nudge sends that person one Slack reminder with their overdue to-dos for that hire, with Done and Snooze to Monday.
4. It works once a day and never reaches someone who stopped these reminders.
5. The figures count people on the playbook, to-dos done by the day after they were due, overdue to-dos and hires who asked for help.
6. On a phone, each hire is a card.
The Hires tab is how everyone on the playbook is getting on: their day, how much of the playbook is done, the next step and what needs attention. It opens first unless messages wait for approval.
Progress counts steps sent and to-dos done. Check-in answers stay anonymous and out of it, and nothing here scores the hire.
## Give some hires different steps
1. Make the groups first in People → Groups, by rules such as department, location or employment type, or by name.
2. Open a step, pick groups under Only for or Not for, and save. The step list shows its tracks under its title.
3. The Tracks tab lists each group the playbook uses, how many steps it narrows and how many hires are in it now.
4. Preview as shows the steps one person would get today, with each skipped step and why. Nothing is sent or added.
5. Review and approve shows a skipped step’s reason. It is never sent and has no to-dos.
One playbook can give a department, an office or contractors their own steps. On a step, Who gets it picks groups from People → Groups: Only for sends it to people in any of them, Not for leaves out everyone in one.
Groups are checked against People when you review a hire’s messages and again when you approve them. If People changes in between, approve asks you to review again.
## Introduce them to people
1. Add a step, choose Meet as the type, and pick who under Meets. Teammates are people with the same manager, longest here first, up to five.
2. Review and approve names the people in each meet message. If People changes before you approve, approve asks you to review again.
3. Pick a time books 30 minutes in everyone’s calendar, or lets them choose a time together.
4. Your playbooks lists the people they met under Your people, with Say hi and their profile.
A meet step introduces the hire to their manager, their manager’s manager, a teammate or several, or someone you choose. It is one Slack group message with a card for each person and Pick a time.
Who they meet comes from People when you approve the hire’s messages. With nobody there, such as no manager yet, the review says so and the step is skipped.
## Ask them about themselves
1. Add a step, choose Form as the type, and tick what it asks under Asks.
2. On the day, Slack shows Answer, which opens the form there. The same form is on Your playbooks, where they can also add a photo.
3. They can change their answers later on the form or on their profile.
A form step asks the hire a few questions for their profile: preferred name, pronouns, a line about them, birthday and photo. Pick any of them.
Answers go straight onto their profile under their own privacy settings. The birthday is their Celebrations birthday, with no year. HR sees only that the form was answered.
## Before their Slack is ready
1. The step preview says Email until Slack is ready on every step to the hire.
2. Review and approve messages says the same on each step that will go by email for that hire.
3. Each step is one email, however often delivery retries. The step shows as sent once it goes.
Steps to the hire before their Slack is set up go by email to their work email, in a branded email with the same words. Resources are links, and to-dos link to Your playbooks.
Once their Slack account is ready, the next steps go there. Meet steps and check-ins wait for Slack or Your playbooks.
## People who join after day 0
1. Set the playbook’s own choice under Someone who joins after day 0 when you write it. Group automations use it.
2. When Add people finds people past day 0, the check step previews one person’s playbook under each choice. Pick one for this batch.
3. Review and approve messages shows the same: skipped steps are struck out and are never sent.
Someone can join a playbook after its day 0, such as a group added months after it started, so some steps were due before they joined.
Skip what’s past is the default: earlier steps are left out. A buddy invitation still goes today when the introduction is ahead.
Send what they missed as one message sends a single What you missed message the day they join, with their missed to-dos due that day. Past check-ins are skipped; steps for their manager, buddy or HR go that day.
Start from today moves the whole playbook later by the same number of days, so its first step goes the day they join and nothing is missed.
## Playbooks beyond onboarding
The same steps, to-dos and check-ins work beyond onboarding: a new manager’s first months, a return from parental leave, an intern cohort, a team move or a new policy.
Day 0 can be one date for everyone, such as the day a policy takes effect. Playbooks counted from the day someone is added, by hand or by a group automation, can’t have steps before day 0.
A playbook without a buddy leaves out the buddy messages and column. Turn the help check-in off when the playbook has its own check-ins. {{hire}} means the person on the playbook.
Someone can be on several playbooks at once. Your playbooks shows a switch for each, and Home shows the one that’s running now.
## Templates for other moments
1. New managers starts the day someone joins Managers (everyone with a direct report).
2. It sends a welcome, a to-do for their own manager, a nudge at two weeks, a check-in after a month and a manager check-in at two months.
3. Back from leave starts the day someone leaves On leave.
4. It sends a welcome back, a catch-up for their manager, a note about hours and workload, a check-in after two weeks and a manager check-in after a month.
5. Leaving (see below) counts from each person’s last day in People: a handover plan, notes on what only they know, an anonymous exit check-in and HR to-dos.
6. Policy roll-out counts from the date the policy takes effect: everyone gets the policy with a to-do to read and confirm it, and a reminder a week later.
7. Link the Knowledge page to the first step.
8. Intern cohort counts from the cohort’s first day: manager setup, a welcome, checklists, a check-in after a week, a mid-point review and a wrap-up.
9. Keep the cohort in a list group and add it with Add people.
10. Team move starts the day someone joins the group for their new department or team.
11. It sends a welcome, introductions from their new manager, a manager check-in at two weeks and a check-in after three weeks.
12. For New managers, Back from leave or Team move, Start it from a group under Day 0 names the group, making Managers or On leave if needed.
13. Saving turns on the group automation for people who join or leave from then on; each person’s steps still wait for approval.
Only the onboarding templates have a buddy. The others count from the day someone joins the playbook from one date or from each person’s last day, and each suggests the group that starts it.
- [Read each playbook on the templates library](https://shuffl.ai/templates#category-onboarding)
- [Groups](https://shuffl.ai/docs/groups)
## Checklists, buddies and check-ins
A new hire sees their onboarding on Home: checklist progress, the next to-dos, a check-in to answer and who is getting things ready. See all opens Your playbooks, with a timeline of their first 90 days, their buddy and manager, and where to ask.
Steps arrive in Slack with Done beside each to-do and Open my checklist. Your playbooks shows Your checklist, Your resources from the steps, and Getting ready for you: others’ to-dos for the hire, like the laptop. Only the to-do’s owner can check it off.
The hire can ask Mello about their onboarding in Chat or a Shuffl direct message, such as what to do this week. Mello answers only from their own playbook and can check off their to-dos once they confirm.
Someone not on an onboarding playbook sees You’re not in an onboarding playbook until HR starts one.
With no buddy chosen, Find me a buddy suggests coworkers who fit. The one the hire asks answers Yes, I’ll help or Not now in Slack, and the hire hears either way.
An invited buddy gets a Slack message with the hire’s name, team and start date, a few topics worth covering and two meetings to book in the first week. It has Accept and Decline. The same choice is in Your playbooks.
At the check-in the hire answers All good or I need help. I need help opens a reviewed message to HR, like any other HR request, so the accountable responder hears about it.
Slack message, Buddy invitation (The buddy you picked, privately; Days before the hire starts, after you approve it):
```text
<@UJONAH>
*Would you be Mei Lin Zhou’s onboarding buddy?*
Mei Lin Zhou joins on Monday, October 5, 2026. A buddy answers the everyday questions and helps a new colleague feel at home.
Accept or decline right here in Slack, or in Shuffl.
```
Slack message, A new hire asks for a buddy (The coworker they asked, privately; When a new hire without a program asks someone to be their buddy):
```text
Hi Jonah, could you be Mei Lin’s onboarding buddy?
Mei Lin Zhou joined recently and is looking for an onboarding buddy: someone to answer everyday questions for the first few weeks.
You came up because: on your team, finance, here 2 years.
“I’d love someone who knows the year-end close.”
Say yes or not now right here. You can also say hi to <@UMEI> here.
```
Slack message, Buddy said yes (The new hire who asked, privately; When the coworker answers their ask):
```text
Jonah Whitfield said yes to being your onboarding buddy. Ask them anything about getting started. Say hi to <@UJONAH>.
```
Slack message, Buddy introduction (The new hire and their buddy; On the start date):
```text
<@UMEI>, <@UJONAH>
*Meet your onboarding buddy*
Mei Lin Zhou starts on Monday, October 5, 2026. Jonah Whitfield is their buddy for the first weeks.
Find 30 minutes together this week to say hello.
Pick a time with your buddy: connect your own calendar or choose a time together.
```
Slack message, Check-in (The new hire, privately; A couple of weeks after they start):
```text
<@UMEI>
*How is your first stretch going, Mei Lin Zhou?*
If anything is stuck, like access, tools or expectations, say so and HR follows up with you directly.
Answer “All good” or “I need help” in Shuffl.
```
- [Open Your playbooks](https://shuffl.ai/app/playbooks)
## Run a buddy program
1. When you choose a hire in Add people, or Choose a buddy on their row, pick one of the suggestions.
2. Each says why they fit and how many hires they buddy now.
3. In the playbook editor, open Buddy invitation to change the topics under Worth covering, up to six, and the day of Ask if they met, or turn it off.
4. Open the Settings tab of Playbooks to see Buddies. Take someone off the list if their hires never met them; they can’t volunteer again until you choose Put back.
Anyone can choose Volunteer as a buddy on their own profile. Suggestions put volunteers first and never suggest the hire’s manager, their manager’s managers or anyone who reports to the hire.
A month after the start date, the hire and the buddy are each asked in Slack whether they met and whether it helped. Neither sees the other’s answer. HR does, on the Buddies card.
Slack message, Did you meet? (The new hire, and separately their buddy; A month after the start date):
```text
Did you and Jonah meet? Your first month is nearly done. Did you and your buddy Jonah get together, and did it help?
```
- [Open Buddies](https://shuffl.ai/app/playbooks/settings)
## The first 90 days
Every template has the day 30, 60 and 90 check-ins; First 90 days adds the one-year check-in and the manager’s one-to-ones every other week through week 12.
Add one with Add step, then Check-in. Each can be in a playbook once; for other days, see Check-ins with your own questions.
On the day, the hire gets the New hire experience questions; day 90 adds one open question about what to fix before the next person starts.
Answer opens a short form in Slack, and the check-in stays open in Your playbooks for 30 days. A hire on two playbooks is asked once.
Under Playbooks → Insights, What new hires said shows the share who agreed with each question and the open answers. It shows once enough hires have answered (your Pulse reporting floor, 7 or more).
Answers are stored without names or times, so nobody, managers included, sees one person’s answers.
Slack message, 30, 60 and 90-day check-in (The new hire, privately; On day 30, 60 and 90, when the playbook has those check-ins):
```text
Your 30-day check-in: You’ve been here a month. Four quick questions about your start, about a minute in all.
```
Slack message, First anniversary (The person, privately; On their first anniversary, when the playbook has the one-year check-in):
```text
One year with us: Happy first anniversary, and thank you for the year. One question to mark it, and one more if you have a minute.
```
- [Open What new hires said](https://shuffl.ai/app/playbooks/insights#what-new-hires-said)
- [For managers](https://shuffl.ai/docs/managers#new-hires)
## Check-ins with your own questions
1. Open a playbook, choose Add step, then Check-in, and set Which check-in to Your own questions, any day.
2. Give it a title and a day.
3. Write up to six questions: Agree or disagree, Rating, 1 to 5, Yes or no, or Open answer, which people can skip. The intro is optional.
4. Save. The check-in goes to the person on that day, in Slack with Answer and on Your playbooks, and stays open for 30 days.
Any playbook can ask its own questions on any day, such as two weeks after a return from leave. Answers are kept without names, like the first 90 days.
Results show under Your own questions, at the end of What new hires said on the Insights tab, once your Pulse reporting floor is reached.
- [Open What new hires said](https://shuffl.ai/app/playbooks/insights#what-new-hires-said)
## Read and confirm a page
1. Open a playbook, choose Add step, then Read and confirm.
2. Under Page to confirm, pick a published Knowledge page the person can read, and give the step a title and a day.
3. Save and approve each person’s steps as usual. Read and confirm on the playbook’s page shows who confirmed; Download CSV gives each person, page, status, date and version.
A Read and confirm step asks the person on the playbook to read one published Knowledge page, like the handbook or a code of conduct, and confirm they have. Shuffl keeps the same record as a policy confirmation: who, which version and when.
On the day, a Slack message with Read and confirm opens the page; the confirmation is at its end. Your playbooks shows To confirm until they do.
If the page changes after someone confirmed it, their confirmation stays with the version they read, and the step doesn’t ask again.
- [Confirming a Knowledge page](https://shuffl.ai/docs/knowledge#confirm)
## Draft a playbook from your handbook
1. Ask Mello in Chat, for example “Draft our onboarding playbook from our handbook”. With a new playbook’s steps still empty, Draft from Knowledge asks the same.
2. Mello searches your published Knowledge and replies with the draft: how many steps, how many pages it linked and how many have no owner yet. Choose Review and create.
3. The playbook editor opens with Mello’s steps. Check each one, pick who does the ones marked Pick who, then save or start it.
Mello can draft a playbook from your Knowledge, such as a handbook’s first-week section or an IT setup page.
It proposes messages, to-dos and Read and confirm steps on the days the pages give, linking the pages it used. Nothing is saved, sent or started until you check, save and approve the steps.
When a page doesn’t say who does something, Mello doesn’t guess: the step goes to the accountable HR responder for now and is marked Pick who. Open it to choose the hire, their manager, their buddy or someone you name.
## Start a playbook automatically for new hires
1. Create a playbook whose day 0 is each person’s start date.
2. Open Automations under Programs in the HR workspace, or Add an automation on the playbook’s page, and choose Add an automation, then A new hire gets a start date.
3. Pick the playbook and who it starts for: everyone, or only the people in one group, such as Engineering.
4. Turn the automation on, then approve each person’s steps as they arrive.
A playbook counted from each person’s start date can start by itself. When People Sync brings in someone with a start date ahead, or you give someone one in People, they start the playbook within ten minutes.
Their steps wait for your approval, the same as when you add people by hand, so nothing goes out before you check it.
Each person starts it once for each start date. If you remove someone, they are not added back for that date; a new start date, such as a rehire, starts it again. People whose employment has ended, and start dates already past, are left out.
A leaving playbook can start the same way from each last day: choose Someone gets a last day instead. See Leaving below.
## Plan a new hire’s first 90 days
1. Open Playbooks. Under Plans for your new hires, Mello has drafted goals for the first 30, 60 and 90 days from the hire’s role, department and your Knowledge. Draft again makes new ones.
2. Choose Edit goals to change, add or remove goals, up to five for each stage, then Save plan.
3. Choose Share with the hire. They see the plan on their Playbooks page and tick goals off as they go.
When a new hire starts an onboarding playbook counted from their start date, their manager in People sees them under Plans for your new hires.
Only the manager changes the goals. The hire reads them once shared, and HR reads them on the playbook: choose See goals under the hire’s name.
## Leaving
1. Choose New playbook, then Leaving, or set Day 0 to Their last day on any playbook.
2. A leaving playbook has no buddy, and steps can go up to 60 days before and after the last day.
3. Open the playbook and choose Add people.
4. Or start it on its own: on Automations, choose Add an automation, then Someone gets a last day, pick the playbook and turn it on.
5. Anyone People gives a last day ahead starts it within ten minutes.
6. Approve their steps as for any playbook. The exit check-in is anonymous, and its answers show combined under Your own questions once enough people have answered.
When someone is leaving, open them in People, choose Edit and set their Last day. Shuffl never asks for or keeps the reason. HR systems that send a termination date fill it in for you.
The Leaving template plans the handover and how the team hears, captures what only they know and asks an anonymous exit check-in. It gives HR equipment and access to-dos and checks the handover a month on.
Until you tick Their leaving has been announced, only HR, admins and their manager see the last day, and only steps for their manager and HR go. The rest wait, marked waiting until announced, and go once you tick it.
If the last day moves, unsent steps come back for approval at the new dates. Clearing it ends the playbook. Steps to the person stop once their employment or access ends; manager and HR steps after the last day still go.
- [Read the Leaving playbook](https://shuffl.ai/templates/leaving-playbook)
## Related guides
- [People and the org chart](https://shuffl.ai/docs/people)
- [Groups](https://shuffl.ai/docs/groups)
- [Introduce coworkers with Connections](https://shuffl.ai/docs/connections)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Shuffl for managers](https://shuffl.ai/docs/managers)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Introduce coworkers with Connections
> Introduce coworkers in Slack on a schedule, choose who gets matched, and see how rounds went.
Audience: Workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/connections
## Create an introduction program
1. Open Connections from the HR workspace. With no program yet, Mello suggests one: choose Review and start, Change something or Not now.
2. Or choose New program and start from a template, such as Cross-team coffee or Lunch groups, or ask Mello in Chat to draft one.
3. Choose who takes part: a Slack channel’s members, a group from People → Groups, or one or more communities.
4. Then pick the channel introductions post in, inviting Shuffl first if it is private. Someone who keeps a community off their profile is never included through it.
5. Choose the matching, group size and schedule, then write the introduction. The preview shows the message as it will look in Slack.
6. Choose Start program to schedule the first round, or Save draft. Starting sends nothing right away.
Connections needs the Shuffl app in Slack. Introductions go out as Slack group messages; nothing is sent from the web.
- [Open Connections](https://shuffl.ai/app/connections)
- [Connect Slack first](https://shuffl.ai/docs/slack)
- [Example: a program for one office from a group](https://shuffl.ai/docs/groups#recipe-connections)
## Choose who gets matched
Who should meet whom? has four answers. Anyone they haven’t met pairs people not yet introduced.
People from different groups, departments or communities mixes them; People in the same group, department or community keeps each group inside one. Hosted introductions has chosen hosts meet groups of guests, such as leaders meeting new hires.
Fine-tune can honor I’d like to meet requests from profiles and prefer Common ground (Off, Prefer or Strongly prefer). How far across the company to reach is Anyone new, Friends of friends or Far corners.
Groups hold 2 to 8 people, with an optional extra so nobody is left out. Keep coworkers apart can avoid, or never allow, groups of managers and their reports, teammates, people in the same department or people who already know each other.
On the program page, People lets you pause or resume one person, and Never introduce keeps two people out of the same group in every program.
## Ask people who they know
1. Open Connections, then its Settings tab, and find Ask who people know.
2. Turn on Ask people who they know, choose Once a week or Once a month, and pick the days it may go out.
3. Choose Save reminders. It is off until you turn it on.
Keep coworkers apart and suggestions on Network both work better the more Shuffl knows who knows whom. Ask who people know, on the Settings tab of Connections, has Shuffl ask.
Each person gets a private Slack question about one coworker they share people with: Do you know them? I know them stays hidden until the other person says it too.
Nobody is asked twice about the same person, outside working hours or on a break, and people can change it under Connections intros in their notification settings.
- [Open Connections settings](https://shuffl.ai/app/connections/settings)
- [Get introduced by someone you both know](https://shuffl.ai/docs/people#warm-intros)
## Set the schedule and review rounds
A program runs every few days, weeks or months in the time zone you choose. Monthly schedules can repeat on the same date (the 13th), the same weekday position (the second Tuesday) or the last weekday. The program page shows the next introduction.
Under Repeats, choose every day, weekday, week, 2 weeks, month, or Custom for any gap. Under On, choose the days; Monday and Thursday on a weekly program makes two rounds a week.
Starts sets the first date, At the time and time zone, and Next introductions shows the next three dates.
Run now previews the groups before anything is sent; Try another arrangement reshuffles, and confirming starts the round.
Round history on the program page shows each group and whether its message was delivered, with Retry known failures. The Rounds tab lists every round across programs, with a status filter.
Insights counts who is taking part, introductions made, first-time pairs and introductions across teams, per program, and charts introductions and the people in them by week.
When a program is paused, resumed or ended after introductions, Mello tells its channel. A monthly program with fewer than two people for a round says so there, with Invite people.
Slack message, Program paused (The program’s channel; When a program is paused, resumed or ended):
```text
Coffee across teams is paused. Shuffl won’t introduce anyone in #coffee-club until your workspace resumes it.
```
Slack message, Not enough people (A monthly program’s channel; When fewer than two people opted in to a round):
```text
This round needs at least two opted-in people. No introductions were sent.
```
- [Open Connections insights](https://shuffl.ai/app/connections/insights)
## Read preserved historical rounds
If your workspace moved over from the previous Shuffl, the Rounds tab in Connections also lists its earlier rounds under From the previous Shuffl, below your current rounds.
Open one to see its groups, how many people each had and whether its introduction was recorded as sent.
These rounds are read-only. People in them are not linked to anyone in People today, and they never affect current programs or who gets matched. Where the previous Shuffl kept no record of a message, the group says Not recorded.
- [Open Rounds](https://shuffl.ai/app/connections/history)
## What employees see
An introduction is a Slack group message naming everyone, with a line about each person from their profile, their bio and, when calendars are connected, a Pick a time button. Someone without a bio gets a private nudge with Add bio.
In Shuffl, Connections shows each person their next introduction and People you’ve met, and Home gets a Connections shortcut. Someone no program introduces doesn’t see Connections at all.
People can take a break on the Shuffl app’s Home tab in Slack: until back from out of office, for a round or two, a month, or until they resume. Nobody else is told.
Slack message, Introduction (Each new group, in a group DM; Every round of a Connections program):
```text
<@UALEX>, <@UJORDAN>
A little time to meet someone new. Find 20 minutes this week to say hello.
Something to start with: you both mentioned *hiking*.
— Connect your calendar, or suggest a time here.
```
```text
*Alex Kim* (they/them) · Product designer, Growth · 3 years here ·
Working on the new signup flow · Ask me about Figma, climbing
*Jordan Lee* · Support lead, Customer · 8 months here ·
I help customers get unstuck and I love a tidy spreadsheet.
```
Slack message, Add your bio (Someone introduced without a bio, privately; Right after their introduction):
```text
Your introduction went out without a bio. Add a few lines so the people you meet know a little about you.
```
- [Open Connections](https://shuffl.ai/app/connections)
## Onboard new hires
Onboarding is its own program type, with a buddy invitation, an introduction and a check-in for each new hire. It has its own guide.
- [Onboard new hires](https://shuffl.ai/docs/playbooks)
## Related guides
- [Connect Slack](https://shuffl.ai/docs/slack)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Communities](https://shuffl.ai/docs/communities)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Ask one confidential question at a time with Pulse
> One short question at a time, on Home or in Slack, who sees the answers, and how administrators run it.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/pulse
## What employees see
1. Tap an answer: Strongly disagree to Strongly agree, Yes or No, 1 to 5, or 0 to 10 for eNPS.
2. The message changes to Thanks, recorded, with how many have answered, never your answer.
3. Change answer works until the question closes (48 hours unless your administrator changed it, or when the next one opens), on Home or in Slack.
4. Then it reads This one’s closed, with the share who answered.
5. Choose Skip this one to skip. A skip is not an answer and is not reported.
6. In Slack or email, Need help with this? opens a conversation with Mello or a private request to HR under your name, carrying no question or answer.
Mello asks one short question on your workspace’s schedule.
It appears on Home as Today’s question and in Slack as Quick one from Mello · 10 seconds, with who sees your answers in the small print. It stays on the Shuffl app’s Home tab until you answer.
Without a linked Slack account it comes by email.
Your first question carries the full notice from Who sees what; later ones carry a short version.
Pulse has two tabs for everyone: This week, the open question and recent ones, and Your answers, with your streak, turnout and what HR changed because people answered.
Between questions, Pulse says No question open right now, when the next one goes out and how many answered the last one. Home shows the same on its Next Pulse question tile.
Someone who joined after this week’s question went out sees Your first question is on its way, with when the next one goes out, on Pulse and on Home alike.
If administrators share results, Recent questions shows the combined figure for each closed question asked to everyone, such as 72% favourable, once enough people answered.
Slack message, Pulse question (Each person in the Pulse audience, privately; On the Pulse schedule; the first one explains how it works):
```text
Quick one from Mello: I know what’s expected of me at work.
```
Slack message, Pulse question, answered (The person who answered, privately; Right after a tap; the same message, rewritten):
```text
Thanks, recorded.
```
Slack message, Pulse question, closed (Each person who was asked, privately; When the question closes; the same message, rewritten):
```text
This one's closed.
```
- [Open Pulse](https://shuffl.ai/app/pulse)
- [How a private HR request works](https://shuffl.ai/docs/hr-requests)
## Who sees what
This is the notice every employee reads before their first question. Your answers are confidential, not anonymous: HR sees totals for groups of 7 or more people, never your answer or your name next to one.
You can skip any question, and skipping tells nobody anything.
Confidential, not anonymous means Shuffl knows who answered, to count participation. The answers are stored separately under a token that no role, export, report or agent can read.
A total shows only when 7 or more people answered; below that, HR sees Too few and the participation share. Results freeze when the question closes.
Results by group, department, managers and ICs, and tenure follow the same floor. When a small group is hidden, enough others are hidden with it that nobody can subtract their way to it.
Each person is in one department, so departments never overlap. Other groups can. So a group is also hidden when fewer than 7 people are outside it. The same applies when it and another shown total would reveal fewer than 7 people by subtraction.
Slack keeps its own copy of the direct message under your workspace’s retention and export settings. The question text is not confidential; the tap is, and it travels only to Shuffl.
- [Security and data handling](https://shuffl.ai/security)
## For administrators
1. Open Pulse from the HR workspace and choose the Insights tab: participation, favourable share, eNPS and results by driver, week and group, with example figures before the first question closes.
2. Questions holds the question bank; Settings holds the cadence, reporting floor and AI switch.
3. Under By group, choose Over time for a line per group: weeks over 30 days, fortnights over 90, months over 180.
4. Pick Favourable, eNPS or a driver. Fell the most and Rose the most list moves of 5 points or more, each with Ask why.
5. Choose Start pulse and pick how often under Repeats; Every Tuesday and Thursday at 10:00 is the default.
6. Tap the day circles to choose days, or use Custom for any gap. Open for (1 to 168 hours, 48 by default) sets how long a question stays open.
7. Check the reporting floor: it starts at 7 people and can only go up, from the next send.
8. To aim a question at part of the company, choose Set group on Questions and pick a group from People → Groups.
9. The picker warns when the group is under the floor, since its answers would never show. eNPS always goes to everyone.
10. When a question closes, administrators get Pulse results are in, in Slack or by email.
11. It carries the result, the change since last time (such as ↑ 6 pts), who answered, the widest gap between groups and a button to ask Mello.
12. Turn it off under Pulse results in your notification settings.
13. Decide whether Mello may work with results. With Summarise trends with AI on, Mello reads published totals, never answers, to say what moved and what to ask next.
14. Decide whether employees see results. With Share results and Show everyone the results on, each closed question asked to everyone shows its combined figure under Recent questions.
15. The figure shows once the floor was met. Splits and questions asked to a group stay with administrators.
Slack message, Pulse results are in (Admins who keep Pulse results on; When a Pulse question closes):
```text
Pulse results are in: I know what’s expected of me at work. (68% favourable)
```
- [Open Pulse](https://shuffl.ai/app/pulse/insights)
- [Example: ask managers a question of their own](https://shuffl.ai/docs/groups#recipe-pulse)
## Start from a question set
1. Open Pulse from the HR workspace, then the Questions tab.
2. Once you have questions, the sets sit in a closed list, such as 10 more Pulse templates to try, with a few shown as tiles.
3. Choose a set to preview its questions and the driver each one measures.
4. Choose Add N questions. They join the rotation, one per send. Reword or retire any of them later.
A new workspace opens Questions on What should Pulse ask about? with ten question sets, such as Weekly check-in, Wellbeing and New hire experience. Choose Write your own to start blank.
Clarity, Belonging, Psychological safety and Workload are based on published workplace research, in our own short wording, and each links to a glossary page. Psychological safety is its own driver in Insights.
- [Open Pulse questions](https://shuffl.ai/app/pulse/questions)
- [Every question set to copy](https://shuffl.ai/templates#category-pulse)
- [Psychological safety](https://shuffl.ai/glossary/psychological-safety)
## Open one question
On Insights, choose a closed question to open it in a side panel, with a link you can share with another administrator.
The panel shows the result and how many answered, the spread of answers and Every time it was asked. By group compares groups, departments, managers and ICs, or tenure under Show results by.
Groups are frozen as they were when the question went out. Actions lists what you change because of the result.
Plan an action starts an action from this result. Ask Mello about this opens Chat with the question and its earlier sends; Mello answers in a few lines with what stands out and what to try. Ask a follow-up asks Mello for one more question.
- [Open Pulse insights](https://shuffl.ai/app/pulse/insights)
## Questions Mello suggests
1. Open Questions. Suggested by Mello lists what is waiting. Approve adds a question to the front of the rotation, worded exactly as shown.
2. Choose Edit to reword it first, or Dismiss to drop it. Mello does not suggest the same wording again.
3. Every suggestion is checked for leading wording, personal topics such as health, religion or pay, and two questions in one; one that fails must be reworded before approval.
4. Choose Suggest questions for up to three now, optionally on a topic, or ask Mello in Chat or Slack. They arrive as suggestions, never as live questions.
With the AI switch on, Mello suggests up to two follow-up questions a week, each with one line on why, such as Workload fell from 74% to 58% favourable. Owners and administrators get each in Slack or by email, with Approve and Dismiss.
Mello reads only the last eight weeks’ published totals and the wording already asked, never an answer, a group under the floor or a name.
In Chat, ask Mello to draft follow-up questions about a result. Its card lists each question with its scale and why, and saving adds them to Suggested by Mello.
Slack message, Mello suggests a Pulse question (Owners and admins, when Pulse AI suggestions are on; When Mello suggests questions, once per suggestion):
```text
Mello suggests a Pulse question: I can get my work done in a normal working week.
```
- [Open Pulse questions](https://shuffl.ai/app/pulse/questions)
## eNPS
eNPS asks How likely are you to recommend working here to a friend? on a 0 to 10 scale, every quarter by default, replacing that day’s question. Change how often or turn it off under eNPS in Pulse settings.
People who answer 9 or 10 are promoters, 7 or 8 passives, 0 to 6 detractors. The score is promoters minus detractors, from -100 to +100, under the same reporting floor. Insights shows the latest score, its split and the trend over eight eNPS questions.
- [Open Pulse settings](https://shuffl.ai/app/pulse/settings)
## Acting on results
1. On Insights, open a closed question and choose Plan an action, or open Actions and choose Plan an action.
2. Write the action, or choose Draft with Mello. Pick an owner and a due date. Leave Ask this question again on to see if it helped.
3. Choose Tell people, edit the draft, pick a channel and whether to message everyone who was asked, and post.
4. Mark the action Done when it is. Mello can also list, plan and update actions in Chat.
An action is what you will do about a closed question, with an owner and a due date. Overdue actions show in the Inbox and on Home until marked done or dropped.
Pulse asks the question again on the first send two weeks after the due date, to the same audience. The action shows the result before and after, each side under the reporting floor.
Tell people sends one "You said, we did" message to a Slack channel Shuffl is in and to everyone who was asked.
Mello drafts it from the published result and the action, never from answers, and you edit it first. A retry never sends it twice.
Slack message, You said, we did (A channel you pick, and each person who was asked; Once, when HR approves the post about an action):
```text
You said, we did: Share priorities and what they mean for each team
```
- [Open Pulse actions](https://shuffl.ai/app/pulse/actions)
## Reminders
1. In Pulse settings, turn on Send Pulse reminders and choose The next day or Before it closes.
2. Each person can change or turn off reminders under Pulse check-ins in their notification settings.
When reminders are on, anyone who hasn’t answered or skipped gets one reminder per question, in Slack or by email, in their working hours on a day you chose.
In Slack, Mello turns the question’s own message into the reminder, so there is only one message to answer.
Answering, skipping or choosing Need help with this? means no reminder. Nobody but you sees that you were reminded.
Slack message, Pulse reminder (Someone who hasn’t answered the open question, privately; Once per question, when HR turns Pulse reminders on; it rewrites the question’s own message and adds one line that notifies):
```text
Reminder: I know what’s expected of me at work.
```
```text
Reminder: today’s Pulse question is still open above. It takes 10 seconds.
```
- [Open Pulse settings](https://shuffl.ai/app/pulse/settings)
- [Your notification settings](https://shuffl.ai/app/settings/notifications)
## What is never built
Pulse has no individual scores, no manager dashboards, no free text and no benchmarks against other companies.
Nobody is ranked, scored or flagged from their answers, and a pulse answer never appears in a chat with Mello.
## Retention
Answers are deleted 90 days after the question closes. Reports, the frozen totals above the floor, are kept so you can compare over time.
Deleting an answer in Shuffl doesn’t remove Slack’s own copy of the message.
- [How long it is kept](https://shuffl.ai/privacy-policy#how-long-it-is-kept)
## Related guides
- [Groups](https://shuffl.ai/docs/groups)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Culture, what Mello handled and the HR digest](https://shuffl.ai/docs/impact)
- [Find your way around](https://shuffl.ai/docs/around-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Praise and badges
> How Shuffl reads your praise channel in Slack, what you see and control, badges people earn, and how administrators set it up.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/praise
## Giving praise
Thank someone the way you already do: post in your company’s praise channel, like #kudos, and @mention them. You never leave Slack.
Or choose Praise on a coworker’s profile, or Give praise under Praise. Shuffl suggests people you work with, offers starters and lets you tag values.
Review what the channel will see, then post; Shuffl posts it in the praise channel with both your names. A closed draft waits for you.
If a few words don’t say much yet, the composer asks what they did and what it changed. It never stops you posting.
Some people prefer private thanks. The composer says so, and Mello sends them your words as a private Slack note instead. Turn on Send as a private note at Review to do this for anyone.
In Slack, Thank back and Give praise on Mello’s messages open the same composer as a form. The channel sees your words quoted, with your name and values underneath.
Shuffl reads new top-level messages that mention someone, decides whether each is praise and tags up to three company values. Thread replies and bot messages are left alone.
When Shuffl records a message as praise, it adds a ❤️ reaction, or your administrator’s chosen emoji. Slack reactions show on the praise in Shuffl as totals.
Edit the message in Slack and Shuffl reads it again. Delete it and it is gone from Shuffl too.
Above the feed, Top values this month shows the most-praised company values of the last 30 days.
Slack message, Praise sent from Shuffl (The praise channel; When someone gives praise from Shuffl or from Slack’s Give praise):
```text
<@UJORDAN> praised <@UPRIYA> and <@UMEI>: Thank you for running the customer onboarding call while I was out. Three new teams went live without a hitch.
```
Slack message, A private thank-you (Someone who prefers private thanks, in a direct message; When someone praises a person who chose Tell me privately, or sends praise as a private note):
```text
<@UJORDAN> sent you a private thank-you: Thank you for staying with the payroll export until it balanced. Nobody else noticed, and that was the point.
```
- [Open Praise](https://shuffl.ai/app/praise)
## Praise you received
1. Hide from profile takes praise off your profile and the Everyone feed.
2. Choose Not praise? when Shuffl misread a message. It disappears from Shuffl for everyone, the Slack message stays, and the giver and administrators can do the same.
Praise → Yours lists the praise you received and gave, including from private channels you’re in, with totals only you see. Praise you received also shows on your profile and Home to people who can read its channel.
When someone praises you, Mello sends at most one Slack message a day, quoting each note with Thank back. Turn off Tell me in Slack to stop it.
Under When someone praises me, choose Share it with the team or Tell me privately.
Privately, praise from Shuffl arrives as a private note, and channel praise about you stays off your profile and the feed, including earlier praise, until you show it. Private notes are listed under Private notes, for you and the other person only.
Slack message, You were praised (The person praised, privately; Once a day, only on days they were praised):
```text
You were praised 2 times today.
```
- [Open your praise](https://shuffl.ai/app/praise/me)
## Reminders to thank people
1. Choose Give praise, write it and choose Post praise. Not now dismisses it; Stop these reminders turns them off.
2. Under Praise in your notification settings, follow your team’s choice, pick how often, or turn them off.
When your administrator turns on praise reminders, Mello sends a private Slack note if you haven’t thanked anyone in a while. It comes every 2 weeks, monthly or every 3 months, with a Give praise button. It never writes or posts praise for you.
It comes in your working hours on an allowed day, never on the same day as another Shuffl reminder or within 7 days of a badge offer.
Slack message, Praise reminder (Someone who hasn’t thanked anyone in a while, privately; When HR turns praise reminders on, at most as often as chosen):
```text
Anyone you’d like to thank? It’s been a while since you shared praise in #kudos.
```
- [Your notification settings](https://shuffl.ai/app/settings/notifications)
## Badges
1. Choose New badge, from a template or blank. Give it a name, description and picture (uploaded or AI-made), and pick its kind: Custom, Event, Program, Release, Role or Tenure.
2. Choose how people get it: Owners give it, Anyone with the claim code, or Anyone can request it and owners approve. Add owners and, if you want, moderators.
3. Give a badge with Give, claim one under Have a claim code?, or choose Request and wait for an owner.
4. Ask for this badge on a profile sends the same request. Holders can hide a badge from their profile; administrators can hide one for everyone.
5. In Slack, mention @Shuffl in a thread and say “badge this”. Mello drafts a name and picks the people, visible only to you; choose Review badge, edit and Create badge.
6. Later, “@Shuffl rename it to …” or “@Shuffl add @name” in the thread updates it.
7. When you thank three or more people in the praise channel, or name coworkers in your launch channel, Shuffl may offer you a badge for them.
8. It asks at most once a week. Don’t ask again stops it.
9. When a project or event channel you made goes quiet for two weeks, Shuffl may DM you a badge for everyone who posted, such as Atlas beta crew.
10. Review it and choose Create badge; Thank them in the channel posts one line there. It asks once per channel.
11. Badge messages in Slack show the badge’s picture.
A badge marks something a person earned or belongs to, like a program, a release or years of tenure. Badges show on profiles, in the Home feed and on Home’s Badges this week card.
Shuffl gives some badges itself: tenure, coworkers met through Connections, and a first badge for starting a community, making a badge and giving praise in a praise channel.
Being thanked earns First thanks, Thanked across teams (three departments) and Lives our values (five thanks for the same value). They count only public praise shown on your profile and never compare you with anyone.
Your own agent can draw or upload a picture for a badge you own over MCP or the API.
Slack message, Badge suggestion (Someone who thanked a group or named a launch team, privately; At most once a week, when badge suggestions are on):
```text
Turn this praise into a badge?. Help center launch
```
Slack message, Badge suggestion for a quiet channel (The person who made a project or event channel, privately; Once per channel, two weeks after its last post):
```text
#proj-atlas-beta has gone quiet. Atlas beta crew
```
Slack message, Badge made (The maker privately, then the original thread; When someone creates a badge from a suggestion):
```text
You made Help center launch for 3 people.
```
```text
<@UJORDAN> gave Help center launch to <@UPRIYA>, <@UMEI> and <@UALEX>.
```
- [Open Badges](https://shuffl.ai/app/praise/badges)
- [What your agent can do](https://shuffl.ai/docs/mcp#examples)
## Who sees what
Everyone sees praise from public channels. Praise from a private channel shows only to the people in that channel now, everywhere: the feed, Home, profiles, Praise → Yours and the daily note.
Someone thanked in a private channel they aren’t in doesn’t see it. Administrators get no exception.
Shuffl keeps each private praise channel’s member list current, rechecking every six hours. If it is removed from the channel or can’t check for a day, that channel’s praise is hidden until it can.
A private note is read only by its sender and recipient. It counts in administrators’ totals but never shows in the feed, a profile or the daily note.
Administrators see totals only, for groups of 7 or more, and there are no leaderboards.
## For administrators
1. Open Praise → Settings and turn on Read praise channels.
2. Under Company values, pick the Knowledge page with your values, or Create a company values page from the template. Mello tags praise with them.
3. Add the channels where people already thank each other, up to five.
4. Make sure Shuffl is in them: Add Shuffl to it for a public channel, /invite @Shuffl in a private one.
5. Shuffl brings in the last 12 months and Mello posts a short hello there, once.
6. Under React to praise in Slack, pick the emoji Shuffl adds to new praise, or turn it off. Older Slack connections need a reconnect by a Slack owner or admin.
7. Administrators get two more tabs, marked HR.
8. Insights shows who is recognized and who gives praise by week. Who was recognized splits the share thanked by department, team and location and marks Few thanked under 30%.
9. Groups need 7 people. Choose Stop reading to stop; praise already read stays.
10. Turn on Nudge quiet managers. Mello privately tells a manager when nobody on their team of two or more has been thanked in 60 days.
11. It nudges at most monthly and names nobody.
12. Under Reminders, turn on Send praise reminders and choose how often; each person can change or turn it off. See the message shows what they get.
13. Under Praise → Badges, Badge suggestions turns badge offers from group praise and quiet channels on or off.
14. It also picks the launch channel Shuffl watches, like #launches (Shuffl must be in it). Nothing is made until the person offered says yes.
Slack message, Praise channel hello (A channel Shuffl watches for praise; Once, when praise capture starts there):
```text
Hi, it's Mello. Shuffl now keeps the praise shared here, so the people you thank can find it on their Shuffl profile. Mention the people you are thanking with @ and I take it from there. I won’t post here again.
```
Slack message, Manager nudge (A manager, privately; When HR turns on Nudge quiet managers and nobody on their team was thanked in 60 days, at most once a month):
```text
Nobody on your team has been thanked in the last 60 days.
```
- [Open Praise settings](https://shuffl.ai/app/praise/settings)
## Related guides
- [Communities](https://shuffl.ai/docs/communities)
- [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/celebrations)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Communities
> Groups for interests, places, skills and resource groups, each linked to a Slack channel.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/communities
## Find and join a community
1. Open Communities and filter by kind, or choose Yours for memberships and pending invitations. Invitation-only communities are visible only to members, invited people and community managers.
2. Choose Join for an open community, or Accept invitation for an invitation-only one, which also requests an invitation to its Slack channel.
3. Leaving in Shuffl doesn’t leave the Slack channel, and rejoining an invitation-only community needs a new invitation.
4. Open a community for its page: cover, description, latest Slack posts, newest members and who runs it.
5. Open in Slack goes to the channel. Posts from a private channel or invitation-only community show to members only.
6. Choose Show me as a member to decide whether the community appears on your profile. Members lists who is in it, when the owners allow that.
A community is a group of coworkers around an interest, a city or office, a skill or a resource group, with a page, its members and usually a Slack channel. Suggested for you picks communities from your profile and the people you know.
- [Open Communities](https://shuffl.ai/app/communities)
## Start a community
1. Choose New community and pick a template, or Start from scratch. A template fills in the name, description, category and picture; change what you like.
2. Choose Who can join: open to the workspace, or Invite only, which a private Slack channel requires.
3. Administrators and owners can link or create its channel, where Mello introduces the community.
4. Creating a private channel needs Slack’s private-channel permission; otherwise link a private channel Shuffl is already in.
5. Add a cover, uploaded or created with AI, choose who is listed as a member, and add owners and moderators. Choose Create community.
6. For an invitation-only community, an owner or administrator chooses Manage under Members, selects people and chooses Invite selected people. Each person must accept; Withdraw cancels a pending invitation.
7. Moderators can edit details and remove members but not invite. Only owners and administrators change the Slack link or archive.
## For administrators
Administrators manage communities on the same Communities page, seeing every one, archived included, and can create, edit, archive or change owners of any. Community activity on Home shows only to people allowed to see that community.
Your Slack probably has communities already, like a running club. Under Turn channels into communities, Shuffl ticks the channels that look like one; change the kind or ticks, and confirm invitation-only admission for each private channel. Open communities sync membership with Slack.
Workspace setup lists suggested channels under Start communities, each with a reason.
Once created, Mello says hello in each channel, with a Join button for open communities, and Shuffl draws a cover unless you chose one. A cover that fails can be retried from the same list.
Your own agent can also draw or upload a cover for a community you own, moderate or administer, over MCP or the API.
Slack message, Community channel hello (The channel linked to a community; Once, when the channel is linked):
```text
Hi everyone, I'm Mello. This channel is now home to the *Runners* community in Shuffl.
Weekend runs, race plans and route swaps.
Join here or in ; membership stays in step in both.
```
- [Open Communities](https://shuffl.ai/app/communities)
- [Turn channels into communities](https://shuffl.ai/app/setup/slack-channels#communities)
- [Example: invite a group to a community](https://shuffl.ai/docs/groups#recipe-community)
## Related guides
- [Praise and badges](https://shuffl.ai/docs/praise)
- [Connect Slack](https://shuffl.ai/docs/slack)
- [Your profile](https://shuffl.ai/docs/your-profile)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Celebrate work anniversaries and birthdays
> Work anniversaries and birthdays in Slack, what each person decides, and how administrators set it up.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/celebrations
## Your anniversary and birthday
1. To add your birthday, open Celebrations from Home, or Me, and enter the month and day. Shuffl never imports a birthday and never asks for the year.
2. To stop a celebration, turn it off there. Anything already scheduled for it is cancelled.
Shuffl celebrates two days: your work anniversary, counted from your start date in People, and your birthday, if you add it. Your workspace switches each one on separately.
On the day, Mello sends you a private Slack note, with Your celebrations to change what is shared (or a note in Shuffl without linked Slack). Coworkers who know you see your day on Home with a Congratulate button.
This week, on Your celebrations, lists coworkers celebrated in a channel in the last seven days. Private or team-only celebrations aren’t listed, and a birthday never shows an age.
Slack message, Share your celebration? (The person celebrating, privately; A few days before the date):
```text
Your 3-year work anniversary is coming up on . Should Mello share it in #celebrations?
```
Slack message, Your note on the day (The person celebrating, privately; On the day, shared or not):
```text
Happy work anniversary, Jordan Lee! 3 years with us. Thank you for everything you do.
```
Slack message, Celebration post (The celebrations channel or the person’s team; On the day, if they said yes):
```text
Happy work anniversary, Jordan Lee! 3 years with us. Thank you for everything you do.
```
- [Open your celebrations](https://shuffl.ai/app/celebrations)
## Who sees what
Your workspace may also post in a Slack channel or message your teammates, but only if you say yes, separately for your anniversary and your birthday.
A week before your first shared day, Mello asks you in a Slack direct message: Share it or Keep it private. Either way, you still get your own note on the day.
Change your answer any time in Slack, on Shuffl’s Home tab or on the web under Celebrations. Saying no cancels any shared message still waiting.
No celebration post or note carries the date or your age; only your manager’s heads-up names the day. A birthday has no year stored at all. An anniversary message can say how many years.
A channel post shows a celebration card with your first name and, for an anniversary, the years. It invites coworkers to reply in its thread to add a note for you.
When you share a day, your manager hears about it a week ahead so they can send a note. A private day stays between you and Mello.
## Sign a team card
When someone shares their day, Mello opens a card a week before and asks their teammates and manager to sign it. Add a note writes yours in Slack; each person writes one, changeable until the day.
The card is a surprise: the person gets it on the day in a Slack message from Mello quoting every note, and under Your celebrations. A card nobody signed is never sent.
Cards waiting on your note are listed under Cards to sign on Your celebrations.
Slack message, Sign the team card (The person’s teammates, privately; A week before a shared celebration):
```text
Jordan Lee's 5-year work anniversary is on . 2 people have signed their card so far.
```
Slack message, Your team card (The person celebrating, privately; On the day, if anyone signed):
```text
Your team signed a card for your 5-year work anniversary, with notes from Priya Shah, Marcus Webb and 1 other.
```
- [Open your celebrations](https://shuffl.ai/app/celebrations)
## For managers
A week before a report’s shared anniversary or birthday, Mello sends their manager a Slack direct message with the day and a note to start from. A first year and every fifth year are called out as milestones.
Mello never posts as you. Send the note yourself on the day, or write it now and use Slack’s Schedule message. Mello still sends its own note.
Nothing goes out for a day the person keeps private, or when People lists no manager for them. If their manager changes before the day, the old manager’s heads-up is not sent.
Slack message, Manager heads-up (The person’s manager, privately; A week before a shared celebration):
```text
Jordan Lee's 5-year work anniversary is coming up on . A note from you on the day means more than one from Mello.
```
- [Shuffl for managers](https://shuffl.ai/docs/managers#celebrations)
## For administrators
1. Open Celebrations from the HR workspace. The HR-only tabs are Upcoming, Insights, History and Settings.
2. Upcoming shows the next 60 days, shared or private. Insights shows how celebrations landed, History every message sent or skipped, and Settings one card each for anniversaries and birthdays.
3. In a new workspace, pick a starter: Work anniversaries in a channel, Birthdays in a channel, Tell the team about anniversaries, or Private anniversary notes.
4. It fills in the settings; nothing is turned on yet.
5. Choose who hears about it: a private note to the person only, also a post in a Slack channel you choose, or also a message to each teammate.
6. Write the message. Use {name} and {years} for anniversaries, and {name} for birthdays.
7. Choose the send time. Each message goes out at that time in the person’s own time zone.
8. How this is sent on each card sums up the timing, privacy and Who sees what.
9. Choose the send days. Monday to Friday is the default, so a Saturday birthday goes out the Friday before.
10. Choose On other days, send on: the send day after it for Monday, or all seven days for the day itself.
11. Choose Turn on, after Preview if you want to check the message. Save without turning on keeps your edits.
- [Open Celebrations](https://shuffl.ai/app/celebrations/upcoming)
## See how celebrations land
Insights counts celebrations sent in the last 30, 90 or 180 days against the period before. It shows how many, how many people, birthdays and anniversaries, and how many reached a channel or the team.
Notes per card shows how warmly the team signed the cards given. Mello’s line names messages that failed or were skipped, and people who have not said whether to share. Names stay on History.
- [Open Insights](https://shuffl.ai/app/celebrations/insights)
## Start dates
Work anniversaries count from each person’s start date in People. For people who came back, joined through an acquisition or were contractors first, choose whether to count from the latest start date or the first hire date. Changing it reschedules upcoming anniversaries.
People sync keeps the first hire date when your HRIS sends one (BambooHR and Workday do), or when someone whose employment had ended comes back with a later start date.
You can also add a first hire date by hand when you edit a person in People.
The same card lists start dates that look wrong. That means more than 90 days ahead, more than 60 years ago, or shared by five or more people and at least a fifth of everyone.
While anniversaries are on, Mello tells administrators once a year how many it found.
- [Open Start dates](https://shuffl.ai/app/celebrations/settings#start-dates)
## When messages are sent
Each message goes out on the day if it is a send day, otherwise on the nearest send day before or after, as you chose; Upcoming shows when.
Each message is sent at most once, even on retry, and one not sent by the end of the person’s send day is skipped, never sent late.
Turning a celebration off, a person opting out, saying no to sharing or employment ending cancels what was scheduled.
A rehired person’s anniversary counts from their new start date, unless you chose the first hire date under Start dates. A February 29 anniversary or birthday is celebrated on February 28 in other years.
## Related guides
- [Your profile](https://shuffl.ai/docs/your-profile)
- [Connect Slack](https://shuffl.ai/docs/slack)
- [People and the org chart](https://shuffl.ai/docs/people)
- [Shuffl for managers](https://shuffl.ai/docs/managers)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Mentorship programs
> Pair mentors and mentees for a few months, with goals, booked meetings, private notes and check-ins.
Audience: Everyone using Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/mentorship
## Join a program
Open Mentorship from Home once HR starts a program. Until you have a pair, How mentorship works sums up the four steps: join, get matched, meet, check in. Each program shows how long pairings last and how often you check in.
Choose Find a mentor or Become a mentor, and say what you want to learn or can help with. Your match reads it too. The program then says whether you’re waiting for a match or matched. You can join as both, and leave any time.
- [Open Mentorship](https://shuffl.ai/app/mentorship)
## Pick your mentor
Some programs let you pick your mentor. Shuffl shows up to three mentors with room, outside your reporting line, with why each fits. Choose Ask and they get a message.
The mentor accepts, which starts your pairing and introduces you both, or passes, and you pick again. Nobody sees who else you were offered, and you’re never told why someone passed.
## Your pairing
Once your pair starts, you both get an introduction with a first agenda and Pick a time, which finds 30 minutes you’re both free and sends the invite. The card shows your next meeting. A week in with nothing booked, Shuffl reminds you once.
Before each meeting the card shows what to bring: the thing you said you’d try, open goals and questions for this stage. After you meet, either of you adds notes and one thing to try. Only the two of you read them; HR never does.
The mentee writes up to five goals for the pairing and ticks them off. The mentor can read them; HR never sees them.
Every few weeks each of you is asked whether you met, with one tap in Slack or on the page. HR sees the answers; your partner doesn’t. Either of you can pause, resume or end the pairing early.
Slack message, Meet your mentor (The mentor and the mentee, each privately; When HR approves the pair, or the mentor accepts):
```text
Meet your mentor, Jonah. Your pairing in Grow at Northwind runs until December 21. Shuffl checks in every 2 weeks.
```
Slack message, A mentee chose you (The mentor, privately; When a mentee picks them in a program where mentees choose):
```text
Priya would like you as their mentor. Customer team mentoring pairs you for 12 weeks.
```
Slack message, Pick a time (The mentor and the mentee, each privately; Once, a week into a pairing with no meeting booked):
```text
Pick a time with Jonah. Your mentorship started a week ago and there’s no first meeting yet. Shuffl finds 30 minutes you’re both free.
```
Slack message, Did you meet? (The mentor and the mentee, each privately; Every few weeks while the pairing runs, and once at the end):
```text
Did you and Jonah meet? Shuffl checks in every 2 weeks. Did you two get together since the last check-in?
```
## Start a program
Administrators open Mentorship from the For HR menu, then Programs, then New program. Pick who can join: everyone or one group. Each program’s button says what’s next, such as Approve 2 matches.
Set how long a pairing lasts, how often pairs check in and how many mentees each mentor takes. A new program starts with the terms on Mentorship → Settings. Changes apply to pairs approved afterwards.
- [Open Programs](https://shuffl.ai/app/mentorship/programs)
## Approve pairs
Suggest matches gives each waiting mentee one mentor. It favors shared topics, more time at the company and the same time zone, and spreads mentees across mentors.
Or set How matches are made to let mentees pick from three mentors. Mentors then accept or pass, and the program lists who is waiting on an answer.
Nobody is paired with someone in their reporting line, a person they were paired with before, or a pair you kept apart in Connections. Nothing is sent until you approve a pair; Skip suggests someone else next time.
## Follow a program
The program page shows each pair meeting now, how many check-ins they answered and how often they met. Ended pairs show whether each person said it helped.
End pair stops a pair; Remove takes a person off the program so they’re never suggested. Pause stops joining and check-ins; Archive ends every pair. A mentor whose pairing finishes gets the Mentor badge.
## See how pairs are doing
Insights shows pairs meeting now, new pairs, check-ins answered and pairs that ended early, each against the period before. Mello says what waits on you, such as matches to approve.
Pick 30, 90 or 180 days, and one program if you run several. See trend on a program page opens it here. Insights counts answers; it never reads goals.
- [Open Insights](https://shuffl.ai/app/mentorship/insights)
## Settings for new programs
Mentorship → Settings, also under Settings → Programs, sets what a new program starts with. The defaults are 12-week pairings, a check-in every 2 weeks and up to 2 mentees per mentor.
Programs already running keep their own terms; change those with Edit on the program.
- [Open Settings](https://shuffl.ai/app/mentorship/settings)
## Related guides
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Introduce coworkers with Connections](https://shuffl.ai/docs/connections)
- [Groups](https://shuffl.ai/docs/groups)
- [Notifications and reminders](https://shuffl.ai/docs/notifications)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Culture, what Mello handled and the HR digest
> See how your culture is doing and what to do next, what Mello handled and the time it saved, and get the numbers by email or Slack on a schedule.
Audience: Workspace administrators and HR responders
Kind: Explanation
Canonical: https://shuffl.ai/docs/impact
## Today
Insights opens on Today. Mello’s panel says how many things need you, the same number as the Inbox badge, then counts HR requests, drafts, re-checks and Pulse actions, each opening the Inbox.
Below come Mello’s suggestion for what to turn on next and At a glance: what Mello handled this month and Culture’s four rates, each opening the Culture page.
Until setup is finished, Today shows the steps left; afterwards the checklist stays under Settings, Setup. Until something is published, Today leads with adding your handbook and skips the tiles.
- [Open Today](https://shuffl.ai/app/insights)
## Culture at a glance
Culture opens on Mello’s headline: whether your vital signs are warmer, cooler or steady against the 90 days before. It also says how many things in your Inbox need you, the same number as its badge.
Under it are this week’s numbers and Ask Mello about your culture.
Today lists what needs you, one line and one button each: your Inbox count first, then new hires who asked for help. Mello’s recommendations follow, such as a new hire with no buddy or a department nobody has thanked lately.
Not now hides one for 90 days. Good news beside it shows recent praise, steps that worked and upcoming shared anniversaries.
Vital signs are four 90-day numbers, each with its change and a weekly line when the numbers moved. They are eNPS with Pulse participation, Recognized (share of people thanked), Across teams (share introduced to another team) and Check-ins (share of new hires’ check-ins answered).
Each vital sign opens its Insights tab.
HR requests sits under them, for the same 90 days: requests with a weekly line, median first reply, share within your response target, and how many wait on HR now. Waiting opens the Inbox; the other tiles and All figures open the full request figures.
Where to improve is a heatmap of every department of 7 or more people. It shades Pulse, Thanked and Met other teams by how far each sits under the company, furthest behind first.
Each row offers the step for its weakest area, such as Give praise, plus Ask Mello, and Detail breaks the row down further.
Playbooks in flight shows your four busiest playbooks, with people who need help first. Your company shows headcount over twelve months, the biggest departments, groups and average tenure, each linking to People.
Groups count only with 7 or more people, so no figure about a group points at one person. What Mello handled comes last, described below.
- [Open Culture](https://shuffl.ai/app/insights/culture)
## What Mello handled
What Mello handled, at the foot of the Culture page, shows this week, this month or all time. It counts questions answered from Knowledge and how many needed no HR, HR requests prepared, onboarding messages, praise tied to values and app actions run for administrators.
Time saved multiplies answered questions by the number you enter under Minutes a typical HR question takes you. Until then the tile stays empty.
- [Open What Mello handled](https://shuffl.ai/app/insights/culture#mello)
## The HR digest
The HR digest sends these numbers to administrators and HR responders every week, two weeks or month. It has every program with its change since the last digest (↑ 4 pts), what needs you and a suggested next step, totals only.
HR responders who don’t administer the workspace get only the requests waiting on them.
Set it up under Settings → Notifications → HR digest: how often, the day and time, whether to send a note when nothing happened, and optionally a private Slack channel. Show the digest under Preview draws the last one. Each recipient picks email or Slack.
Slack message, HR digest (HR and admins who turned it on; Weekly, or on the schedule you pick):
```text
Northwind Traders: your week in Shuffl
```
Slack message, HR digest for responders (HR responders who don’t administer the workspace; On the same schedule as the HR digest):
```text
3 HR requests are waiting on you
```
- [Open Notifications](https://shuffl.ai/app/settings/notifications)
## Mello’s culture nudges
Mello also points out culture gaps in a group, each with one action. Examples: a department nobody has thanked in six weeks (Give praise) or a new hire with no buddy (Pick a buddy). Two departments Connections hasn’t introduced lately get a cross-team round.
They lead the HR digest, sit on Today and join Mello’s top three on Culture. Each names a department or counts new hires, never a person, and departments count only at 7 or more people. Not now hides one for 90 days.
- [Open Today](https://shuffl.ai/app/insights)
## Insights in each area
Culture brings Praise, Connections, Onboarding and Pulse together. Each area also has its own Insights tab for administrators. Knowledge shows which sources answer and where guidance is missing, Requests the reply and resolve times, and People the headcount, joins and departures.
All show totals; Pulse and Praise only for groups of 7 or more.
## Related guides
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/pulse)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Workspace settings
> How Settings is grouped, then the workspace’s name and logo, roles and access, integrations, API keys and webhooks, and activity.
Audience: Workspace administrators
Kind: Reference
Canonical: https://shuffl.ai/docs/settings
## How Settings is grouped
You is yours in every workspace: Profile (name, photo and appearance), Notifications, Your calendar, Connected apps and Account.
Workspace is for administrators: General, Roles and access, Integrations (Slack, Single sign-on, Email domains and Provisioning, for company owners and administrators), API keys and webhooks, and Activity.
Company holds Name and logo, Workspaces, Members and Billing; members who aren’t owners or administrators see only Workspaces. Programs lists each program Mello runs with its On or Off, and opens that program’s own Settings tab.
- [Open Settings](https://shuffl.ai/app/settings)
- [Company settings](https://shuffl.ai/docs/companies-and-workspaces#company-settings)
## General
Settings → General renames the workspace and sets a logo, shown in the app and on the Slack Home tab.
A line under the title says your access and links to People. Every app link names its workspace, so a copied link opens the same page for whoever you send it to.
Export workspace downloads your data as JSON. A company owner or administrator can delete a workspace by typing its name; it stays restorable for 30 days, then Shuffl permanently erases its data.
- [Open General settings](https://shuffl.ai/app/settings/workspace)
## Roles and access
Company owners and administrators manage every workspace in their company; workspace administrators manage only their own.
HR responders receive employee requests, under the HR team name set here, and Knowledge verifiers publish sources without being administrators. Turn roles on under Roles on a person’s details sheet in People.
- [Open Roles and access](https://shuffl.ai/app/settings/roles)
## Integrations, API keys and webhooks
Slack, Single sign-on, Email domains and Provisioning are under Workspace → Integrations; they belong to the company, so only its owners and administrators see them.
API keys and webhooks has three tabs: Workspace keys work in one workspace only, Webhooks sends signed events, and Company keys manage the company itself, never a workspace’s data.
- [Email domains](https://shuffl.ai/docs/employee-access#email-domains)
- [Single sign-on](https://shuffl.ai/docs/employee-access#single-sign-on)
- [API keys and agents](https://shuffl.ai/docs/agent-quick-start)
- [Company API keys](https://shuffl.ai/docs/api-permissions#company-keys)
## Activity log
Activity is the workspace log of what changed, who changed it and when, for settings, roles, access, sources and programs.
- [Open Activity](https://shuffl.ai/app/settings/activity)
## Related guides
- [Connect Slack](https://shuffl.ai/docs/slack)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Billing](https://shuffl.ai/docs/billing)
- [Roles and permissions](https://shuffl.ai/docs/roles-and-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Roles and permissions
> Who can see and do what in Shuffl, from company owner to employee, and how to give or take away each role.
Audience: Company owners and administrators
Kind: Reference
Canonical: https://shuffl.ai/docs/roles-and-permissions
## How roles fit together
Shuffl has two layers of role. A company role (owner, administrator or member) applies across the company and all its workspaces. A workspace role (administrator or employee) applies to one workspace.
Two more roles are given inside one workspace: HR responder, who answers private HR requests, and Knowledge verifier, who reviews and publishes Knowledge. Anyone with enabled employee access can hold them.
Manager is not a role you assign. It comes from the manager field in People, and it adds a few prompts but no extra access.
- [Companies and workspaces](https://shuffl.ai/docs/companies-and-workspaces#company-and-workspace)
## Who can see and do what
Company owner: everything a company administrator can do, plus change company roles, transfer ownership, remove administrators and owners, and delete or restore the company. Owners start as HR responders and Knowledge verifiers wherever they have an enabled profile in People.
Company administrator: all of Company settings and every workspace in the company, including ones they haven’t joined. They create, delete, restore and resume workspaces and choose the default, and can remove ordinary members.
Workspace administrator: runs one workspace, including People, Knowledge, the Inbox, Culture and every program. They manage access, workspace roles, Request settings and workspace Settings. They can’t open Company settings beyond the workspace list, delete their workspace or change their own role.
HR responder: gets new HR requests by Slack or email and works them in the Inbox. They see only requests sent while they were a responder, and a sensitive category only when named on it. The role opens no People, Pulse or settings pages.
Knowledge verifier: writes drafts, approves what Mello proposes, and publishes and withdraws sources. The role does not open HR requests, People or settings.
Manager: whoever People lists as someone’s manager. They get onboarding check-in nudges and a heads-up before a report’s shared anniversary or birthday, and Knowledge and Pulse can target Managers. A manager can’t see their reports’ chats, HR requests or Pulse answers.
Employee: uses Home, Chat with Mello and People, reads Knowledge published to them, answers Pulse, gives praise, joins communities and sends reviewed requests to HR.
- [Who can manage the company](https://shuffl.ai/docs/companies-and-workspaces#roles)
- [How responders work](https://shuffl.ai/docs/hr-requests#responders)
- [Verify knowledge](https://shuffl.ai/docs/knowledge#verify)
- [Shuffl for managers](https://shuffl.ai/docs/managers)
## What no role opens
Some things stay private whatever someone’s role. Mello chats are seen only by the person who had them; managers, HR and administrators cannot read them.
An HR request is seen by the employee who sent it and the responders it went to. An administrator needs to be an HR responder too to read them.
Pulse answers are stored apart from who gave them. No role, export, report or agent can read one person’s answer, and results show only for groups at or above the reporting floor.
- [Who sees Pulse results](https://shuffl.ai/docs/pulse#who-sees-what)
## Make someone a workspace administrator
1. Open People and choose the person to open their details.
2. Expand Roles. Under Workspace role, choose Administrator, then Save role. The change shows in Settings → Activity.
3. To take the role away, choose Employee and Save role.
4. If Roles says No workspace role yet, the person has no linked app account. Invite them or link their account under Connected accounts first.
5. You can’t change your own role. Company owners’ and administrators’ roles are changed under Settings → Company → Members.
6. To bring in a new administrator, choose Invite on People and pick Administrator as the role. They become one when they accept.
- [Open People](https://shuffl.ai/app/people)
- [Link an app account to a person](https://shuffl.ai/docs/employee-access#link)
## Add an HR responder or Knowledge verifier
1. Open Settings → Roles and access from the HR workspace. View HR responders and View Knowledge verifiers open People filtered to them.
2. Open the person, expand Roles and turn on HR responder or Knowledge verifier. It takes effect at once.
3. If the switch is greyed out, enable their employee access and link their app account in People first.
4. Turn the switch off to take the role away. The only HR responder can’t be turned off: make someone else a responder first.
5. Under HR responders on Settings → Roles and access, HR team name is what employees see when they send a question to HR. Change it and choose Save name.
- [Open Roles settings](https://shuffl.ai/app/settings/roles)
## Change company roles and transfer ownership
1. To make a company administrator or another owner, open Settings → Company → Members, open the person’s actions menu and choose Change role. Pick Administrator or Owner, then Save role.
2. To transfer ownership, open Settings → Company → Name and logo and choose Transfer ownership… on the Company owner card.
3. Pick a new owner who is already a company member, then Transfer ownership.
4. You stay in the company as an administrator. The new owner also becomes an HR responder and Knowledge verifier wherever they have an enabled profile in People.
5. Remove from company in the same menu takes away access to the company and all its workspaces. Administrators can remove ordinary members; only owners can remove administrators or other owners.
- [Open Company members](https://shuffl.ai/app/settings/company/members)
- [Open Company settings](https://shuffl.ai/app/settings/company/general)
## Restore and resume a deleted workspace
1. Open Settings → Company → Workspaces. A deleted workspace has a Deleted badge.
2. Choose Restore on its row. Only company owners and administrators see it.
3. The workspace comes back paused, so programs don’t send anything for dates that passed. Its People, Knowledge and history are as they were.
4. Check its programs’ next dates, then choose Resume on its row, or Resume workspace in its Settings → General.
5. Restore works for 30 days after deletion, then Shuffl permanently erases the workspace. If the whole company was deleted, restore the company first.
- [Open Workspaces](https://shuffl.ai/app/settings/company/workspaces)
- [Restore a deleted company](https://shuffl.ai/docs/companies-and-workspaces#delete-company)
## API keys follow their creator
An API key acts as the person who created it. A workspace key can do only what its grants name and its creator’s current role allows; if the creator loses a role, the key loses it too.
A company key works with its creator’s current company role and pauses while they aren’t a company owner or administrator.
- [Choose exact grants](https://shuffl.ai/docs/api-permissions#grants)
- [Company API keys](https://shuffl.ai/docs/api-permissions#company-keys)
## Related guides
- [Companies and workspaces](https://shuffl.ai/docs/companies-and-workspaces)
- [Workspace settings](https://shuffl.ai/docs/settings)
- [Share a request with HR](https://shuffl.ai/docs/hr-requests)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Shuffl for managers](https://shuffl.ai/docs/managers)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Billing
> Shuffl is free for every workspace; where the company’s billing state lives, and what to do if an older plan needs attention.
Audience: Workspace administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/billing
## Free for every workspace
Shuffl is free for every workspace at any size, including Mello, single sign-on and HRIS sync. There is no plan to start, no trial and no card.
AI answers are not metered. If a paid plan for Mello at larger sizes comes later, administrators will be told before anything changes. A company that started a plan earlier can still manage or cancel it in Settings → Company → Billing.
- [Open Billing](https://shuffl.ai/app/settings/company/billing)
## Read the state before taking action
Free for everyone is the state of every company without a subscription. The other states, such as Awaiting payment or Payment overdue, apply only to a company that started a plan before Shuffl became free, and each comes with a recovery message.
Trial expired or Subscription ended no longer pause anything: every feature stays free, and sign-in, account and billing management, export and help are always available.
## Use the recovery action shown
Refresh billing state asks the payment provider for the current status, and Manage payment opens its portal for cards and invoices. After Cancel at period end, check the dates shown. Enabling people is never refused for billing, and nothing is charged automatically.
Billing notices reach owners and administrators under the Billing topic in Settings → Notifications.
- [Review employee access](https://shuffl.ai/docs/employee-access)
## Related guides
- [Workspace settings](https://shuffl.ai/docs/settings)
- [Invite and enable employees](https://shuffl.ai/docs/employee-access)
- [Find a recovery step](https://shuffl.ai/docs/troubleshooting)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Switch to Shuffl from your current tools
> Move to Shuffl from the tools you use now, keep your HR system and directory, and connect them in the right order.
Audience: HR teams and administrators moving to Shuffl
Kind: How-to guide
Canonical: https://shuffl.ai/docs/switch-to-shuffl
## Switch without starting over
Shuffl works beside the HR systems you keep. Your HR system stays the record of who works here, your identity provider keeps sign-in, and Slack stays where people talk. Shuffl reads them and does the work around them: answers, requests, onboarding, Pulse, praise and celebrations.
Most teams connect Slack, their HR system and their handbook in one afternoon, then turn programs on one at a time.
- [Every integration](https://shuffl.ai/integrations)
## Which system owns what
Shuffl only reads your HR system, directory and documents. Fix a wrong title or manager where it lives, and the next sync brings it in.
### Each system keeps its job
- Your HR system: who works here, titles, managers, departments, start dates, leavers and time-off balances.
- Your identity provider: sign-in, and who is provisioned or removed.
- Slack: where people talk, with names, photos and time zones.
- Your docs: the policies Mello answers from, after HR reviews them.
- Shuffl: answers, HR requests, playbooks, Pulse, praise, celebrations, Connections and communities.
## Connect in this order
1. Connect Slack in Settings → Integrations → Slack. Everyone in your Slack workspace appears in People with access pending.
2. Connect your HR system on People → Sync, or push people from your identity provider over SCIM. Connect the HR system first so it owns start dates and managers.
3. Add single sign-on under Settings → Workspace → Integrations → Single sign-on, once People lists everyone.
4. Add your handbook: upload files, add a web page or connect Google Drive, Notion, Confluence or another source on Knowledge → Connections.
5. If another app runs intros, shoutouts or celebrations in Slack, bring those channels over from workspace setup.
6. Enable access for the people who should use Shuffl, then turn programs on one at a time.
- [Open workspace setup](https://shuffl.ai/app/setup)
- [Get started](https://shuffl.ai/docs/getting-started)
## From another Slack app
Workspace setup finds channels where another app runs coffee chats, shoutouts or celebrations. Intros become a Connections program, shoutouts a praise channel with the past year imported, and celebrations keep their channel.
Add the other app’s CSV of past intros so nobody meets the same person again. Intros start once the old app leaves the channel, and each person whose birthday was celebrated is asked privately before Shuffl keeps it.
- [Bring your Slack channels over](https://shuffl.ai/docs/getting-started#slack-channels)
## From email, spreadsheets and survey tools
### What replaces what
- A shared HR inbox: employees ask Mello in Slack or on the web. What it can’t answer becomes an HR request in HR’s Inbox.
- A handbook in a wiki or drive: connect it, review each draft and publish. Mello answers with a citation.
- An onboarding spreadsheet: start from a playbook template. Start dates from your HR system start each hire’s playbook.
- A survey tool: Pulse asks short anonymous questions in Slack or by email, with question sets to start from.
- A birthday spreadsheet: people add their own birthday, and work anniversaries come from start dates.
- [HR requests](https://shuffl.ai/docs/hr-requests)
- [Playbooks](https://shuffl.ai/docs/playbooks)
- [Pulse](https://shuffl.ai/docs/pulse)
- [HR templates](https://shuffl.ai/templates)
## Identity and sign-in
Step-by-step guides for each one: how to connect it, what comes in and what Shuffl does with it.
- [Google Workspace](https://shuffl.ai/docs/google-workspace)
- [JumpCloud](https://shuffl.ai/docs/jumpcloud)
- [Microsoft 365](https://shuffl.ai/docs/microsoft-365)
- [Microsoft Entra ID](https://shuffl.ai/docs/microsoft-entra-id)
- [Okta](https://shuffl.ai/docs/okta)
- [OneLogin](https://shuffl.ai/docs/onelogin)
## HR systems
Step-by-step guides for each one: how to connect it, what comes in and what Shuffl does with it.
- [BambooHR](https://shuffl.ai/docs/bamboohr)
- [Deel](https://shuffl.ai/docs/deel)
- [HiBob](https://shuffl.ai/docs/hibob)
- [Personio](https://shuffl.ai/docs/personio)
- [Rippling](https://shuffl.ai/docs/rippling)
- [Workday](https://shuffl.ai/docs/workday)
## Knowledge
Step-by-step guides for each one: how to connect it, what comes in and what Shuffl does with it.
- [Box](https://shuffl.ai/docs/box)
- [Confluence](https://shuffl.ai/docs/confluence)
- [Dropbox](https://shuffl.ai/docs/dropbox)
- [Google Drive](https://shuffl.ai/docs/google-drive)
- [Guru](https://shuffl.ai/docs/guru)
- [Notion](https://shuffl.ai/docs/notion)
- [SharePoint and OneDrive](https://shuffl.ai/docs/sharepoint)
## Chat and AI
Step-by-step guides for each one: how to connect it, what comes in and what Shuffl does with it.
- [ChatGPT](https://shuffl.ai/docs/mcp#connect-chatgpt)
- [Claude](https://shuffl.ai/docs/mcp#connect-claude)
- [Claude Code](https://shuffl.ai/docs/mcp#connect-claude-code)
- [Codex](https://shuffl.ai/docs/mcp#connect-codex)
- [Cursor](https://shuffl.ai/docs/mcp#connect-cursor)
- [Slack](https://shuffl.ai/docs/slack)
- [VS Code](https://shuffl.ai/docs/mcp#connect-vscode)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Roll out Shuffl to your company](https://shuffl.ai/docs/rollout)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with BambooHR
> Connect BambooHR to keep People current and let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/bamboohr
## What BambooHR does in Shuffl
BambooHR is where many HR teams keep the employee record. Connect it once and People, onboarding playbooks and celebrations follow it. Mello can also answer from the company files you pick.
You need to be a Shuffl workspace administrator, with an administrator in BambooHR for the steps there.
- [Shuffl + BambooHR](https://shuffl.ai/integrations/bamboohr)
## Connect BambooHR to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on BambooHR.
2. Sign in to BambooHR as an administrator, open your name in the top right, choose API Keys and add a key named Shuffl.
3. Paste the key and your company domain into Shuffl. Shuffl reads your employees before saving anything.
4. Shuffl registers a webhook with the same key so changes arrive as they happen, and reads everything once a day as well.
5. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Changes arrive as they happen, and Shuffl also reads BambooHR once a day. Shuffl only reads; it never changes anything in BambooHR.
BambooHR’s values replace People’s on every read, so fix a wrong title or manager in BambooHR. A blank keeps what People has.
### From BambooHR into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Start dates
- Leavers
- Each person’s own time-off balances
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello tells each employee their own time-off balance in a private chat, in BambooHR’s policy names.
- Mello knows each person’s title, manager and department when it answers.
## Answer from BambooHR
1. On Knowledge → Connections, choose Connect next to BambooHR.
2. In BambooHR, create an API key from your account menu.
3. Enter your company domain and the key into Shuffl. Shuffl checks it with one read of the company file list before saving.
4. Pick files from a category; each is read as a draft for review. Employee files are never listed.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: PDF, Word, PowerPoint, Markdown, HTML, text. You pick each one, and Shuffl never writes to BambooHR.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in BambooHR becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## Good to know
Shuffl adds a webhook with the same key, so hires, changes and leavers arrive as they happen. Without one it reads once a day.
Make the key as an administrator who can see every employee. Employee files are never read; only the company files you pick become Knowledge.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, BambooHR refused Shuffl’s key or sign-in. Create a new one in BambooHR and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Box
> Connect Box to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/box
## What Box does in Shuffl
Keep your handbook and policies in Box and let Mello answer from them. Shuffl reads only the files you pick, and HR reviews every change before Mello uses it.
You need to be a Shuffl workspace administrator, with an administrator in Box for the steps there.
- [Shuffl + Box](https://shuffl.ai/integrations/box)
## Answer from Box
1. On Knowledge → Connections, choose Connect next to Box.
2. Sign in with the Box account that can open the files.
3. Grant Shuffl access. It reads the files you pick and writes nothing.
4. Pick a file from a folder or a search; it is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: PDF, Word, PowerPoint, Markdown, HTML, text. You pick each one, and Shuffl never writes to Box.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Box becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Box, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Confluence
> Connect Confluence to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/confluence
## What Confluence does in Shuffl
If your handbook lives in Confluence, Mello can answer from those pages with a citation. Headings become sections, and a new page version waits for HR’s review.
You need to be a Shuffl workspace administrator, with an administrator in Confluence for the steps there.
- [Shuffl + Confluence](https://shuffl.ai/integrations/confluence)
## Answer from Confluence
1. On Knowledge → Connections, choose Connect next to Confluence.
2. In Atlassian account settings, create an API token.
3. Enter your site, the account email and the token into Shuffl. Shuffl checks it with one read before saving.
4. Pick pages from a search or paste their links; each is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: Pages. You pick each one, and Shuffl never writes to Confluence.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Confluence becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Confluence, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Deel
> Connect Deel to keep People current, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/deel
## What Deel does in Shuffl
Deel employs and pays people across countries. Connect an organization token and People lists your whole team, contractors included, and Mello can tell each person their time-off balance.
You need to be a Shuffl workspace administrator, with an administrator in Deel for the steps there.
- [Shuffl + Deel](https://shuffl.ai/integrations/deel)
## Connect Deel to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Deel.
2. In Deel, open More → Developer → Access Tokens and generate a new organization token.
3. Select the scopes people:read and organizations:read, and allow work emails.
4. Paste the token into Shuffl. Shuffl checks it against your organization and people before saving it.
5. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Deel once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Deel.
Deel’s values replace People’s on every read, so fix a wrong title or manager in Deel. A blank keeps what People has.
### From Deel into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Start dates
- Leavers
- Each person’s own time-off balances
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello tells each employee their own time-off balance in a private chat, in Deel’s policy names.
- Mello knows each person’s title, manager and department when it answers.
## Good to know
Contractors get the Contractor employment type in People, so a group rule can leave them out of programs meant for employees.
Deel sends no live changes, so Shuffl reads it once a day. Choose Sync now on its card after a big change.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Deel refused Shuffl’s key or sign-in. Create a new one in Deel and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Dropbox
> Connect Dropbox to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/dropbox
## What Dropbox does in Shuffl
Keep policies in Dropbox and Mello answers from the files you pick. Shuffl watches each file and holds a changed version for HR to review.
You need to be a Shuffl workspace administrator, with an administrator in Dropbox for the steps there.
- [Shuffl + Dropbox](https://shuffl.ai/integrations/dropbox)
## Answer from Dropbox
1. On Knowledge → Connections, choose Connect next to Dropbox.
2. Sign in with the Dropbox account that can open the files.
3. Approve read access for Shuffl. Nothing is written to Dropbox.
4. Pick a file from a folder or a search; it is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: PDF, Word, PowerPoint, Markdown, HTML, text. You pick each one, and Shuffl never writes to Dropbox.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Dropbox becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Dropbox, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Google Drive
> Connect Google Drive to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/google-drive
## What Google Drive does in Shuffl
Write policies in Google Docs and let Mello answer from them. Shuffl sees only the files you select, and a changed doc waits for HR’s review before Mello uses it.
You need to be a Shuffl workspace administrator, with an administrator in Google Drive for the steps there.
- [Shuffl + Google Drive](https://shuffl.ai/integrations/google-drive)
## Answer from Google Drive
1. On Knowledge → Connections, choose Connect next to Google Drive.
2. Sign in with the Google account that can open the documents.
3. Approve access to files you select. Shuffl sees only those files.
4. Pick a document from Drive; it is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: Docs, Slides, PDF, Word, PowerPoint, Markdown, HTML, text. You pick each one, and Shuffl never writes to Google Drive.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Google Drive becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Google Drive, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Google Workspace
> Connect Google Workspace to keep People current and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/google-workspace
## What Google Workspace does in Shuffl
Google Workspace is the directory at many companies. Connect it to fill People with everyone, their titles, managers and Google Groups, and let people sign in with Google.
You need to be a Shuffl workspace administrator, with an administrator in Google Workspace for the steps there.
- [Shuffl + Google Workspace](https://shuffl.ai/integrations/google-workspace)
## Connect Google Workspace to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Google Workspace.
2. Sign in with a Google Workspace administrator account that can read users.
3. Allow Shuffl to see the users and groups in your domain. Groups become teams in People.
4. If Google says the app is blocked, trust Shuffl in the Admin console under Security → API controls → App access control, then connect again.
5. Shuffl reads your people before it saves the connection, and the first sync runs straight away.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Google Workspace once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Google Workspace.
Google Workspace’s values replace People’s on every read, so fix a wrong title or manager in Google Workspace. A blank keeps what People has.
### From Google Workspace into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Leavers
## What it does for HR
### In Shuffl
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with Google Workspace
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick SAML. Keep the values it shows open.
2. In the Google Admin console, open Apps, then Web and mobile apps, and add a custom SAML app. Download the IdP metadata on the way.
3. Paste the ACS URL and entity ID, and the login URL into Start URL. Set Name ID format to EMAIL and Name ID to Primary email. Leave Signed response off.
4. Turn the app on for the organizational units who should sign in.
5. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
6. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## Good to know
If Google says the app is blocked, trust Shuffl in the Admin console under Security → API controls → App access control, then connect again.
Groups list their direct members; nested groups aren’t expanded. Google Workspace doesn’t send SCIM to custom apps, so People → Sync is the way in.
## With your other systems
Google Workspace has no start dates. Type them in People, or connect your HR system first so it owns them; a blank from Google keeps what People has.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Google Workspace refused Shuffl’s key or sign-in. Create a new one in Google Workspace and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Guru
> Connect Guru to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/guru
## What Guru does in Shuffl
If HR answers live in Guru cards, Mello can answer from the verified ones. Shuffl reads only the cards the token can open.
You need to be a Shuffl workspace administrator, with an administrator in Guru for the steps there.
- [Shuffl + Guru](https://shuffl.ai/integrations/guru)
## Answer from Guru
1. On Knowledge → Connections, choose Connect next to Guru.
2. In Guru, create a user token under My settings → API access, or a collection token.
3. Enter the user email or collection id and the token into Shuffl. Shuffl checks it with one read before saving.
4. Pick verified cards from a collection or a search, or paste a card link; each is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: Cards. You pick each one, and Shuffl never writes to Guru.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Guru becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Guru, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with HiBob
> Connect HiBob to keep People current, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/hibob
## What HiBob does in Shuffl
HiBob (Bob) holds your people data. Connect a service user and People follows Bob, with changes as they happen once you add a webhook. Mello can tell each person their time-off balance.
You need to be a Shuffl workspace administrator, with an administrator in HiBob for the steps there.
- [Shuffl + HiBob](https://shuffl.ai/integrations/hibob)
## Connect HiBob to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on HiBob.
2. In Bob, open Settings → Integrations → Service users and create one named Shuffl.
3. Give it a permission group that can view Basic info, Work and Lifecycle for all employees, including former ones.
4. For instant updates, open Settings → Integrations → Automation → Webhooks, add the webhook address Shuffl shows with the employee events and copy its secret.
5. Paste the ID, token and secret into Shuffl. Shuffl reads your employees before saving anything.
6. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
7. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Changes arrive as they happen, and Shuffl also reads HiBob once a day. Shuffl only reads; it never changes anything in HiBob.
HiBob’s values replace People’s on every read, so fix a wrong title or manager in HiBob. A blank keeps what People has.
### From HiBob into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Start dates
- Leavers
- Each person’s own time-off balances
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello tells each employee their own time-off balance in a private chat, in HiBob’s policy names.
- Mello knows each person’s title, manager and department when it answers.
## Good to know
For live changes, add the webhook address Shuffl shows under Automation → Webhooks in Bob and paste Bob’s secret into Webhook secret. Without it Shuffl reads once a day.
An inactive Bob account has its Shuffl access suspended. A termination date sets the person’s last day.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, HiBob refused Shuffl’s key or sign-in. Create a new one in HiBob and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with JumpCloud
> Connect JumpCloud to keep People current and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/jumpcloud
## What JumpCloud does in Shuffl
JumpCloud manages your company’s accounts and devices. Connect it to keep People current and let everyone sign in to Shuffl with JumpCloud.
You need to be a Shuffl workspace administrator, with an administrator in JumpCloud for the steps there.
- [Shuffl + JumpCloud](https://shuffl.ai/integrations/jumpcloud)
## Connect JumpCloud to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on JumpCloud.
2. In the JumpCloud Admin Portal, open your administrator menu (top right) and choose API Settings.
3. Generate an API key, or copy the current one. Keys expire after 90 days by default, so note when to rotate it.
4. Paste the key into Shuffl. Shuffl checks it by listing users before saving it.
5. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads JumpCloud once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in JumpCloud.
JumpCloud’s values replace People’s on every read, so fix a wrong title or manager in JumpCloud. A blank keeps what People has.
### From JumpCloud into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Leavers
## What it does for HR
### In Shuffl
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with JumpCloud
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick OpenID Connect. Keep the values it shows open.
2. In the JumpCloud Admin Portal, open SSO Applications, add a Custom Application and choose to manage single sign-on with OIDC.
3. Paste the redirect URI into Redirect URIs and the login URL into Login URL. Keep Client Authentication Type as Client Secret Basic.
4. Turn on the email and profile standard scopes, give the user groups who should sign in access to the app, and save.
5. Copy the client ID and client secret JumpCloud shows once. The issuer is the same for every JumpCloud organization.
6. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
7. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## Good to know
JumpCloud API keys expire after 90 days by default. Note when to rotate yours, then connect again with the new key.
JumpCloud signs only the SAML response by default, which Shuffl refuses. Sign the assertion too, or use OpenID Connect.
## With your other systems
JumpCloud has no start dates and no terminated state. Connect your HR system for those, or record start dates and Employment ended in People yourself.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, JumpCloud refused Shuffl’s key or sign-in. Create a new one in JumpCloud and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Microsoft 365
> Connect Microsoft 365 to keep People current, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/microsoft-365
## What Microsoft 365 does in Shuffl
Use Microsoft 365 as your directory? One administrator sign-in fills People with everyone, their hire dates, managers and groups.
You need to be a Shuffl workspace administrator, with an administrator in Microsoft 365 for the steps there.
- [Shuffl + Microsoft 365](https://shuffl.ai/integrations/microsoft-365)
## Connect Microsoft 365 to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Microsoft 365.
2. Sign in with a Microsoft 365 Global Administrator or Privileged Role Administrator account.
3. Accept the permissions on behalf of your organization: read users and group memberships. Groups become teams in People.
4. To stop syncing later, disconnect in Shuffl or remove Shuffl under Enterprise applications in the Microsoft Entra admin center.
5. Shuffl reads your people before it saves the connection, and the first sync runs straight away.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Microsoft 365 once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Microsoft 365.
Microsoft 365’s values replace People’s on every read, so fix a wrong title or manager in Microsoft 365. A blank keeps what People has.
### From Microsoft 365 into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Start dates
- Leavers
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Good to know
Shuffl leaves out guests, shared mailboxes and room accounts.
If the card reads Needs attention, someone usually removed Shuffl under Enterprise applications in Entra. Sign in again as an administrator.
## With your other systems
If you already push people from Microsoft Entra ID with SCIM, keep one of the two. Connect your HR system first if you want it to own start dates.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Microsoft 365 refused Shuffl’s key or sign-in. Create a new one in Microsoft 365 and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Microsoft Entra ID
> Connect Microsoft Entra ID to push people and groups to Shuffl and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/microsoft-entra-id
## What Microsoft Entra ID does in Shuffl
Microsoft Entra ID can push people and groups to Shuffl over SCIM and sign everyone in. Removing someone in Entra takes their Shuffl access away at once.
You need to be a Shuffl workspace administrator, with an administrator in Microsoft Entra ID for the steps there.
- [Shuffl + Microsoft Entra ID](https://shuffl.ai/integrations/microsoft-entra-id)
## Push people from Microsoft Entra ID
1. In Shuffl, open Settings → Workspace → Integrations → Provisioning and choose New SCIM connection. Copy the base URL and the token, which is shown once.
2. In Microsoft Entra ID, turn on SCIM 2.0 provisioning for a Shuffl app. Set Provisioning Mode to Automatic. Tenant URL takes the base URL and Secret Token the token.
3. Turn on creating, updating and deactivating users, send the work email as the user name and assign the people who belong in Shuffl.
4. Back in Shuffl, under Who gets workspace access?, choose Everyone assigned to this app or Selected groups only, then Save access policy.
5. To use a pushed group in Shuffl, open People → Sync, choose Groups on the SCIM card and turn it on.
- [Open Provisioning](https://shuffl.ai/app/settings/company/provisioning)
- [Provisioning in detail](https://shuffl.ai/docs/employee-access#provisioning)
## What comes in
Microsoft Entra ID sends each change as it happens. Shuffl only reads; it never changes anything in Microsoft Entra ID.
Microsoft Entra ID’s values replace People’s on every update, so fix a wrong title or manager in Microsoft Entra ID. A blank keeps what People has.
### From Microsoft Entra ID into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Leavers
## What it does for HR
### In Shuffl
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with Microsoft Entra ID
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick OpenID Connect. Keep the values it shows open.
2. In the Microsoft Entra admin center, open App registrations and choose New registration. Add the redirect URI as a Web platform redirect URI.
3. Under Certificates & secrets, add a client secret. Under Token configuration, add the email optional claim to the ID token.
4. Put the login URL in Branding & properties as the Home page URL so the app opens from My Apps.
5. Copy the Application (client) ID and the secret. The issuer uses your Directory (tenant) ID.
6. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
7. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## Good to know
Entra sends the user principal name by default. For SAML, set the Unique User Identifier to user.mail so Shuffl gets the work email.
## With your other systems
Entra ID sends no start dates. Connect your HR system for those, or use Microsoft 365 in People → Sync instead of SCIM, which reads hire dates. Keep one of the two.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
If people stop arriving, read the provisioning errors in Microsoft Entra ID. Tokens expire after 90 days: choose Rotate token in Shuffl, paste the new one into Microsoft Entra ID, test it, then revoke the old one.
Unassigning someone in Microsoft Entra ID suspends their access at once. Restoring them doesn’t undo a suspension made by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Notion
> Connect Notion to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/notion
## What Notion does in Shuffl
If your handbook is a set of Notion pages, Mello can answer from them with a citation. Share each page with the Shuffl connection, and HR reviews every change.
You need to be a Shuffl workspace administrator, with an administrator in Notion for the steps there.
- [Shuffl + Notion](https://shuffl.ai/integrations/notion)
## Answer from Notion
1. On Knowledge → Connections, choose Connect next to Notion.
2. Authorize Shuffl in your Notion workspace.
3. In Notion, share each policy page with the Shuffl connection.
4. Paste the page link into Shuffl; it is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: Pages. You pick each one, and Shuffl never writes to Notion.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in Notion becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## Good to know
Linked private pages, databases and meeting transcripts aren’t imported. Share each page you want on its own.
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in Notion, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Okta
> Connect Okta to push people and groups to Shuffl and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/okta
## What Okta does in Shuffl
Okta can push people, groups, titles, departments and managers to Shuffl over SCIM, and sign everyone in. Unassign someone in Okta and their access ends at once.
You need to be a Shuffl workspace administrator, with an administrator in Okta for the steps there.
- [Shuffl + Okta](https://shuffl.ai/integrations/okta)
## Push people from Okta
1. In Shuffl, open Settings → Workspace → Integrations → Provisioning and choose New SCIM connection. Copy the base URL and the token, which is shown once.
2. In Okta, turn on SCIM 2.0 provisioning for a Shuffl app. Paste the base URL into SCIM connector base URL and the token under HTTP Header authentication.
3. Turn on creating, updating and deactivating users, send the work email as the user name and assign the people who belong in Shuffl.
4. Back in Shuffl, under Who gets workspace access?, choose Everyone assigned to this app or Selected groups only, then Save access policy.
5. To use a pushed group in Shuffl, open People → Sync, choose Groups on the SCIM card and turn it on.
- [Open Provisioning](https://shuffl.ai/app/settings/company/provisioning)
- [Provisioning in detail](https://shuffl.ai/docs/employee-access#provisioning)
## What comes in
Okta sends each change as it happens. Shuffl only reads; it never changes anything in Okta.
Okta’s values replace People’s on every update, so fix a wrong title or manager in Okta. A blank keeps what People has.
### From Okta into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Leavers
## What it does for HR
### In Shuffl
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with Okta
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick OpenID Connect. Keep the values it shows open.
2. In the Okta Admin Console, open Applications, choose Create App Integration, then OIDC and Web Application.
3. Paste the redirect URI into Sign-in redirect URIs and the login URL into Initiate login URI. Keep Client secret as the client authentication.
4. Assign the people or groups who should sign in, then copy the client ID and secret. The issuer is your Okta domain.
5. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
6. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## With your other systems
Okta sends no start dates. Connect your HR system for those, so playbooks and anniversaries have them. Okta keeps names, emails and access.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
If people stop arriving, read the provisioning errors in Okta. Tokens expire after 90 days: choose Rotate token in Shuffl, paste the new one into Okta, test it, then revoke the old one.
Unassigning someone in Okta suspends their access at once. Restoring them doesn’t undo a suspension made by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with OneLogin
> Connect OneLogin to push people and groups to Shuffl and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/onelogin
## What OneLogin does in Shuffl
OneLogin can push people, groups and departments to Shuffl over SCIM and sign everyone in.
You need to be a Shuffl workspace administrator, with an administrator in OneLogin for the steps there.
- [Shuffl + OneLogin](https://shuffl.ai/integrations/onelogin)
## Push people from OneLogin
1. In Shuffl, open Settings → Workspace → Integrations → Provisioning and choose New SCIM connection. Copy the base URL and the token, which is shown once.
2. In OneLogin, turn on SCIM 2.0 provisioning for a Shuffl app. Paste the base URL into SCIM Base URL and the token into SCIM Bearer Token.
3. Turn on creating, updating and deactivating users, send the work email as the user name and assign the people who belong in Shuffl.
4. Back in Shuffl, under Who gets workspace access?, choose Everyone assigned to this app or Selected groups only, then Save access policy.
5. To use a pushed group in Shuffl, open People → Sync, choose Groups on the SCIM card and turn it on.
- [Open Provisioning](https://shuffl.ai/app/settings/company/provisioning)
- [Provisioning in detail](https://shuffl.ai/docs/employee-access#provisioning)
## What comes in
OneLogin sends each change as it happens. Shuffl only reads; it never changes anything in OneLogin.
OneLogin’s values replace People’s on every update, so fix a wrong title or manager in OneLogin. A blank keeps what People has.
### From OneLogin into Shuffl
- Everyone, with names and work emails
- Job titles
- Departments
- Teams and groups, the ones you choose
- Leavers
## What it does for HR
### In Shuffl
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Suspended or removed accounts lose their Shuffl access.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with OneLogin
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick OpenID Connect. Keep the values it shows open.
2. In OneLogin Administration, open Applications, add the OpenId Connect (OIDC) app.
3. Paste the login URL into Login Url and the redirect URI into Redirect URI’s. On the SSO tab, set Token Endpoint Authentication Method to Basic.
4. Give users access through a role or directly, then copy the client ID and secret. The issuer is your OneLogin domain followed by /oidc/2.
5. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
6. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## Good to know
OneLogin signs SAML with SHA-1 by default, which Shuffl refuses. Choose SHA-256 and sign Both.
## With your other systems
OneLogin sends no managers or start dates. Connect your HR system for those, or set them in People.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
If people stop arriving, read the provisioning errors in OneLogin. Tokens expire after 90 days: choose Rotate token in Shuffl, paste the new one into OneLogin, test it, then revoke the old one.
Unassigning someone in OneLogin suspends their access at once. Restoring them doesn’t undo a suspension made by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Personio
> Connect Personio to keep People current, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/personio
## What Personio does in Shuffl
Personio is the HR system at many European companies. Connect an API credential and People keeps titles, managers, departments, teams, start dates and leavers from Personio.
You need to be a Shuffl workspace administrator, with an administrator in Personio for the steps there.
- [Shuffl + Personio](https://shuffl.ai/integrations/personio)
## Connect Personio to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Personio.
2. In Personio, open Settings → Integrations → API credentials and generate a new credential named Shuffl.
3. Let it read Employees with these attributes: name, preferred name, email, status, position, supervisor, department, team, hire date and termination date.
4. Paste the client ID and secret into Shuffl. Shuffl checks them by reading employees before saving them.
5. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Personio once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Personio.
Personio’s values replace People’s on every read, so fix a wrong title or manager in Personio. A blank keeps what People has.
### From Personio into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Start dates
- Leavers
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello knows each person’s title, manager and department when it answers.
## Good to know
Allow every attribute the credential asks for. One left out comes through blank, and a blank keeps what People has.
Personio sends no live changes, so Shuffl reads it once a day.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Personio refused Shuffl’s key or sign-in. Create a new one in Personio and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Rippling
> Connect Rippling to keep People current and sign everyone in, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/rippling
## What Rippling does in Shuffl
Rippling runs HR, IT and payroll in one place. Connect a token to keep People current and let Mello tell each person their time-off balance. People can sign in with Rippling too.
You need to be a Shuffl workspace administrator, with an administrator in Rippling for the steps there.
- [Shuffl + Rippling](https://shuffl.ai/integrations/rippling)
## Connect Rippling to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Rippling.
2. In Rippling, open Tools → Developer → API Tokens and create a token.
3. Select the read scopes companies.read, departments.read, teams.read, users.read, workers.read and finish creating it.
4. Paste the token into Shuffl. Shuffl checks it against your company and workers before saving it. Rippling expires a token unused for 30 days, so keep syncing on.
5. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
6. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Rippling once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Rippling.
Rippling’s values replace People’s on every read, so fix a wrong title or manager in Rippling. A blank keeps what People has.
### From Rippling into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Teams and groups, the ones you choose
- Start dates
- Leavers
- Each person’s own time-off balances
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Teams you bring in become synced groups for Pulse questions, automations, Connections and messages.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello tells each employee their own time-off balance in a private chat, in Rippling’s policy names.
- Mello knows each person’s title, manager and department when it answers.
## Sign in with Rippling
1. In Shuffl, open Settings → Workspace → Integrations → Single sign-on, choose Add connection and pick SAML. Keep the values it shows open.
2. In Rippling, open App Shop, choose Create New App, and set it up with SAML single sign-on.
3. Paste the ACS URL and entity ID. Under advanced settings, turn on SP-initiated login and paste the login URL, so people can start from Shuffl and from Rippling.
4. Send the work email as the NameID, sign the assertion with SHA-256, then give the app to the people or groups who should sign in.
5. Copy the IdP metadata XML and paste it into Shuffl.
6. Add the DNS TXT record the connection shows at your DNS provider, then choose Check DNS record until it reads Verified.
7. In a private window, choose Sign in with SSO with a work email that is in People with access enabled.
Single sign-on proves who someone is; People still decides who gets in. Set up People first, and password sign-in keeps working while you test.
- [Open Single sign-on](https://shuffl.ai/app/settings/company/sso)
- [Verify and test](https://shuffl.ai/docs/single-sign-on#verify-and-test)
## Good to know
Rippling expires a token unused for 30 days. Keep Sync connected; the daily read keeps it alive.
Add leave-balances.read to the token if you want Mello to answer time-off balance questions.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Rippling refused Shuffl’s key or sign-in. Create a new one in Rippling and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Set up single sign-on and directory provisioning](https://shuffl.ai/docs/single-sign-on)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with SharePoint and OneDrive
> Connect SharePoint and OneDrive to let Mello answer from your documents, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/sharepoint
## What SharePoint and OneDrive does in Shuffl
Keep HR files in SharePoint or OneDrive and Mello answers from the ones you pick. Shuffl gets read access only, and a changed file waits for HR’s review.
You need to be a Shuffl workspace administrator, with an administrator in SharePoint and OneDrive for the steps there.
- [Shuffl + SharePoint and OneDrive](https://shuffl.ai/integrations/sharepoint)
## Answer from SharePoint and OneDrive
1. On Knowledge → Connections, choose Connect next to SharePoint and OneDrive.
2. Sign in with the work account that can open the HR files.
3. Grant Shuffl read access to files and sites. It writes nothing.
4. Pick a file from OneDrive, a site library or a search; it is read as a draft for review.
5. Check the draft’s text, audience and review date, then publish it.
Shuffl reads: PDF, Word, PowerPoint, Markdown, HTML, text. You pick each one, and Shuffl never writes to SharePoint and OneDrive.
### In Shuffl
- Mello answers from what you publish, with a citation, to the audience you set.
- A new version in SharePoint and OneDrive becomes a draft for HR to review. The old text stops being used once the change is found.
- Disconnecting withdraws every document it brought in. The originals stay where they are.
- [Open Connections](https://shuffl.ai/app/knowledge/connections)
- [Freshness and review](https://shuffl.ai/docs/connected-sources#freshness)
## Good to know
Shuffl reads PDF, Word, PowerPoint, Markdown, HTML and text files. Spreadsheets, images and older Office files are refused.
## If it stops working
When a source reads Access lost or Sync needs attention, check that the connected account can still open it in SharePoint and OneDrive, then choose Check now.
Disconnect and withdraw deletes the stored key and withdraws what it brought in. Drafts, versions and the originals stay.
- [Fix a connection](https://shuffl.ai/docs/connected-sources#recover)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Manage connected sources](https://shuffl.ai/docs/connected-sources)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with Workday
> Connect Workday to keep People current, and see what Shuffl does with it.
Audience: HR and IT administrators
Kind: How-to guide
Canonical: https://shuffl.ai/docs/workday
## What Workday does in Shuffl
Workday holds the worker record at larger companies. Share a custom report with an integration user and People follows Workday: titles, managers, organizations, hire dates and leavers.
You need to be a Shuffl workspace administrator, with an administrator in Workday for the steps there.
- [Shuffl + Workday](https://shuffl.ai/integrations/workday)
## Connect Workday to People
1. In Shuffl, open People, then the Sync tab. Under Add a source, choose Connect on Workday.
2. In Workday, create an integration system user for Shuffl with access to workers, organizations and managers.
3. Build an advanced custom report of all workers, including terminated ones, with the XML aliases below.
```
Employee_ID
Preferred_Name
Email
Business_Title
Manager_Employee_ID
Supervisory_Organization
Hire_Date
Active
Termination_Date
```
4. Include terminated workers: Shuffl ends someone’s employment only when Active says they left or their termination date has passed.
5. Enable the report as a web service and share it with the integration user.
6. Paste its JSON URL and the user’s sign-in into Shuffl. Shuffl runs the report once before saving.
7. Choose Connect and sync. The first sync runs straight away and says how many people were new or linked.
8. Review the new people in People and enable access for those who should use Shuffl. A sync never turns access on.
- [Open Sync](https://shuffl.ai/app/people?view=sync)
- [Which value wins](https://shuffl.ai/docs/people-sync#what-syncs)
## What comes in
Shuffl reads Workday once a day. Sync now on its card reads it at once. Shuffl only reads; it never changes anything in Workday.
Workday’s values replace People’s on every read, so fix a wrong title or manager in Workday. A blank keeps what People has.
### From Workday into Shuffl
- Everyone, with names and work emails
- Job titles
- Managers
- Departments
- Start dates
- Leavers
## What it does for HR
### In Shuffl
- Start dates start onboarding playbooks on their own, put new hires on Home and drive work anniversaries.
- Managers fill the org chart, so playbook meet steps, manager to-dos and 30/60/90 plans reach the right person.
- Departments become department groups, so Pulse, eNPS and Culture compare teams without exposing anyone.
- Leavers lose access when they leave, and a termination date sets their last day, which can start a leaving playbook.
- Mello knows each person’s title, manager and department when it answers.
## Good to know
Keep terminated workers in the report. Workday ends employment from Active or a passed Termination_Date.
Use the report’s JSON URL from Actions → Web Service → View URLs, with ?format=json.
## With your other systems
Connect your HR system before an identity provider such as Okta, so it owns start dates, managers and departments. Slack and single sign-on keep names and emails.
- [Which source wins](https://shuffl.ai/docs/people-sync#what-syncs)
## If it stops working
When a card reads Needs attention, Workday refused Shuffl’s key or sign-in. Create a new one in Workday and connect again; Shuffl replaces the stored one. A failed run changes nobody.
Disconnect stops syncing and deletes the stored key. Everyone stays in People to edit by hand.
- [Fix a connection](https://shuffl.ai/docs/people-sync#runs)
- [Troubleshooting](https://shuffl.ai/docs/troubleshooting)
## Related guides
- [Sync People from your HR system](https://shuffl.ai/docs/people-sync)
- [Groups](https://shuffl.ai/docs/groups)
- [Playbooks and onboarding](https://shuffl.ai/docs/playbooks)
- [Switch to Shuffl from your current tools](https://shuffl.ai/docs/switch-to-shuffl)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use Shuffl with your agent
> Use the built-in assistant, or connect your own agent over MCP, the API, the SDK or the CLI.
Audience: Workspace administrators and agent builders
Kind: Tutorial
Canonical: https://shuffl.ai/docs/agent-quick-start
## Use the built-in assistant
Open Chat in your workspace, ask about an approved source and follow the citation. The built-in assistant needs no API key. Workspace membership, employee access and source visibility still apply.
### What Mello does for people
Mello also acts for a person, within what their role allows. Reads run at once. A change appears as a card in Chat or Slack first and runs when the person chooses Run.
- Never offered as actions: credentials, exports, HR request cases, identity links, billing, Pulse answers and new hire check-ins.
- From the People directory it answers who someone’s manager or reports are, their department and groups, who is in a group, and how to reach a colleague.
- It cites the person or unit, says when a field isn’t recorded, and doesn’t discuss access, pay, benefits, performance or HR matters.
- In a shared Slack channel or group message it can’t use the directory and asks you to message it directly.
- Requests to change a record, and concerns about a person, go to Contact HR as a reviewed request.
- [Open Chat](https://shuffl.ai/app/chat)
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Let your agent set it up](https://shuffl.ai/docs/agent-setup)
- [Prepare approved knowledge](https://shuffl.ai/docs/knowledge)
## Connect an existing agent
A workspace key’s MCP permission turns on MCP access. Its endpoint permissions decide what it can do over HTTP and MCP alike.
After you create a key, Check connection sends a tools/list request to the MCP server and a permissions request to the API. It lists the key’s tools and permissions and explains a denial, revoked key, rate limit or network failure.
The check tests the key, not a particular agent product.
### Pick a route
- MCP: an agent works in Shuffl through the remote MCP server, with OAuth or an API key as a bearer header.
- API, TypeScript SDK or CLI: scripts run the same operations. Install @shuffl/sdk and @shuffl/cli from npm.
### Where to connect
- Set this up with your agent, under the workspace setup steps, has a prompt to copy into your agent. It runs setup over MCP and asks before it publishes or invites anyone.
- Steps for other agents covers Claude, Claude Code, Codex, Cursor, ChatGPT, VS Code and other clients, with Add to Cursor and Install in VS Code buttons.
- An OAuth client signs in in your browser and appears under Connected apps. It needs no API key.
- For the API, SDK or CLI, an administrator creates a key in Workspace settings → API keys. It is shown once and expires after 30 days.
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
- [Use the SDK or HTTP API](https://shuffl.ai/docs/sdk)
- [Use the CLI](https://shuffl.ai/docs/cli)
## Start with a capability read
1. Sign in, select the workspace and create a separate credential for this integration. Copy the one-time secret into your credential manager.
2. For MCP, call get_team, then search_knowledge. For the API, SDK or CLI, read teams.current and permissions.list, then use only endpoints you’ve granted.
3. Check the returned workspace and capabilities before running the integration. Empty knowledge results mean no current matching source is visible to the connected person.
The application origin is https://shuffl.ai. Send credentials over HTTPS in the Authorization header, only to the deployment that issued them. Keep them out of prompts, URLs, logs and public documents.
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
- [Recover from an API error](https://shuffl.ai/docs/sdk#errors)
## Add actions deliberately
The API, SDK and CLI also include reviewed management operations.
### Before you grant a write
- Grant each operation separately. Write doesn’t include Read.
- Check inputs, confirmation, revisions and request keys in the reference first.
- Over MCP, a key’s endpoint permissions are its tools, with the same checks.
- OAuth consent, billing confirmation and provider installation stay in the browser.
- An operation in the catalog may still need a provider your workspace hasn’t set up.
- Revoking a credential stops future calls. It can’t erase what an agent already saved.
- [How management writes work](https://shuffl.ai/docs/sdk#writes)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Give your agent the Shuffl skill
The Shuffl skill teaches your agent how to connect, which MCP tool to use when, and what to ask you before it acts. Every guide is a reference file in it. It holds no workspace data.
In Claude, upload the zip as a skill. In Claude Code, unzip it into ~/.claude/skills so the shuffl folder sits there. Other agents can read SKILL.md and the guides it links to.
Every guide page also has Open in Claude and Open in ChatGPT, which start a chat that reads the guide’s Markdown.
- [Download the Shuffl skill](https://shuffl.ai/skills/shuffl.zip)
- [Read the Shuffl skill](https://shuffl.ai/skills/shuffl/SKILL.md)
## Related guides
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Set up a workspace with your agent
> Hand workspace setup to Claude Code or another MCP agent: what it does, in what order, and what stays with you.
Audience: Workspace administrators and the agents they run
Kind: How-to guide
Canonical: https://shuffl.ai/docs/agent-setup
## What you do
1. Create your account and name your company. Shuffl creates its first workspace with it.
2. In Workspace setup, under the steps, choose Show prompt, then Copy prompt, and paste it into your agent.
3. When your browser opens, pick the workspace, choose Choose what setup needs, and allow access.
4. Answer your agent when it asks: approve Slack, and say yes before it publishes knowledge or invites anyone.
- [Create an account](https://shuffl.ai/sign-up)
- [Open workspace setup](https://shuffl.ai/app/setup)
## Connect the agent
The agent connects to Shuffl’s MCP server and signs in with OAuth in your browser, so it needs no API key. It works as you, with your role, in the one workspace you choose.
The connection lasts 30 days unless you disconnect it in Settings → Connected apps.
```sh
claude mcp add --transport http shuffl https://shuffl.ai/api/mcp
```
- [Connect another MCP client](https://shuffl.ai/docs/mcp)
## Work through setup
1. slack: you can’t install Slack. Send the person to Workspace setup → Connect Slack and wait. A Slack admin may need to approve it.
2. knowledge: ask for the handbook or policy as a file or web page. For a page, call knowledge_sources_importWebsite.
3. For a file, call knowledge_uploads_create, knowledge_uploads_appendPart with base64 parts and knowledge_uploads_complete. Poll knowledge_uploads_get until it is read.
4. Each section becomes a private draft. Show the person the titles and audience, then call knowledge_sources_publish only after they say yes.
5. preview: call assistant_send with a question the published source answers, and check the answer cites it. The step counts your own cited answer.
6. employees: ask for one coworker’s email and, after a yes, call invitations_create. They accept by email, then the person turns on their access in People.
7. Optional programs, each after a yes: pulse_saveProgram, programs_create for coffee chats (with channels_list and programs_options), playbooks_saveProgram, and celebrations_save after celebrations_preview.
8. If another Slack app runs intros, shoutouts or celebrations, teams_slackChannels lists those channels with a guess for each. Show the list.
9. Then call teams_moveSlackChannels with the person’s choices. Programs it creates start paused.
Instructions for the agent.
### Rules for the agent
- Call teams_setup first and after each step. Its steps list is the checklist.
- Steps with required true count toward progress. The rest are optional programs.
- Access and HR steps appear only when something needs fixing. Relay what they say.
- Never publish, invite, send or turn on a program without the person’s yes in this conversation.
## Actions setup uses
Choose what setup needs on the consent screen selects these actions. Each tool is the permission with dots replaced by underscores, such as knowledge_sources_publish.
Granting HR responders, deleting the workspace and transferring ownership stay in the app.
### assistant.send
Write · Ask Mello a question in a conversation
Exact permission: `assistant.send`. Underlying role scope: `assistant:write`.
### celebrations.preview
Read · Preview a celebration message
Exact permission: `celebrations.preview`. Underlying role scope: `celebrations:read`.
### celebrations.program
Read · Read the Celebrations settings
Exact permission: `celebrations.program`. Underlying role scope: `celebrations:read`.
### celebrations.save
Write · Save celebration settings; enabling them schedules messages
Exact permission: `celebrations.save`. Underlying role scope: `celebrations:write`.
### channels.list
Read · List available Slack channels
Exact permission: `channels.list`. Underlying role scope: `programs:read`.
### invitations.list
Read · List pending workspace invitations
Exact permission: `invitations.list`. Underlying role scope: `access:read`.
### invitations.create
Write · Invite this person with the selected team role
Exact permission: `invitations.create`. Underlying role scope: `access:write`.
### knowledge.sources.get
Read · Read a Knowledge source
Exact permission: `knowledge.sources.get`. Underlying role scope: `knowledge:manage`.
### knowledge.sources.list
Read · List Knowledge sources
Exact permission: `knowledge.sources.list`. Underlying role scope: `knowledge:manage`.
### knowledge.sources.importWebsite
Write · Import a website page into Knowledge for review
Exact permission: `knowledge.sources.importWebsite`. Underlying role scope: `knowledge:write`.
### knowledge.sources.publish
Write · Publish this knowledge version to its audience
Exact permission: `knowledge.sources.publish`. Underlying role scope: `knowledge:write`.
### knowledge.sources.write
Write · Write a Knowledge page with Mello from its title and a request; nothing is saved
Exact permission: `knowledge.sources.write`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.get
Read · Read the progress of a Knowledge file upload
Exact permission: `knowledge.uploads.get`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.appendPart
Write · Upload the next part of a Knowledge file
Exact permission: `knowledge.uploads.appendPart`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.complete
Write · Finish a Knowledge file upload and start reading it
Exact permission: `knowledge.uploads.complete`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.create
Write · Start uploading a file to Knowledge
Exact permission: `knowledge.uploads.create`. Underlying role scope: `knowledge:write`.
### playbooks.program
Read · Read the Onboarding program settings
Exact permission: `playbooks.program`. Underlying role scope: `playbooks:read`.
### playbooks.saveProgram
Write · Save a playbook: its day 0, steps and messages
Exact permission: `playbooks.saveProgram`. Underlying role scope: `playbooks:write`.
### programs.options
Read · List program setting choices
Exact permission: `programs.options`. Underlying role scope: `programs:read`.
### programs.create
Write · Create a program
Exact permission: `programs.create`. Underlying role scope: `programs:write`.
### pulse.program
Read · Read the Pulse settings
Exact permission: `pulse.program`. Underlying role scope: `pulse:read`.
### pulse.saveProgram
Write · Save Pulse settings; enabling Pulse schedules questions to everyone
Exact permission: `pulse.saveProgram`. Underlying role scope: `pulse:write`.
### teams.setup
Read · Read the workspace's setup checklist
Exact permission: `teams.setup`. Underlying role scope: `team:read`.
### teams.slackChannels
Read · List community channels in the connected Slack and what each would become
Exact permission: `teams.slackChannels`. Underlying role scope: `integrations:read`.
### teams.moveSlackChannels
Write · Set up each channel in Shuffl: paused intros, praise and celebrations
Exact permission: `teams.moveSlackChannels`. Underlying role scope: `integrations:write`.
### teams.saveAgentSetup
Write · Choose the built-in assistant or an external agent for the workspace
Exact permission: `teams.saveAgentSetup`. Underlying role scope: `team:write`.
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Related guides
- [Set up your workspace](https://shuffl.ai/docs/getting-started)
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use the SDK and HTTP API
> Install the TypeScript client from npm, select exact permissions and verify reads before writes.
Audience: Developers and agent builders
Kind: How-to guide
Canonical: https://shuffl.ai/docs/sdk
## Install the SDK
@shuffl/sdk is an ES module for Node.js 22 or later and Bun. Its dependency @shuffl/api-contracts types every method’s input and output. The SDK, CLI and contracts share one version.
Call it from a server, script or agent runtime. Browsers can call it only from your Shuffl deployment’s origin, since CORS isn’t enabled.
```sh
npm install @shuffl/sdk
# or: bun add @shuffl/sdk, pnpm add @shuffl/sdk
```
- [@shuffl/sdk on npm](https://www.npmjs.com/package/@shuffl/sdk)
- [Use HTTP without installing packages](https://shuffl.ai/docs/sdk#http)
## Choose the workspace and permissions
1. Sign in and select the workspace. Open Settings → API keys and webhooks → New API key and name the key.
2. Choose only the endpoints this integration needs. For the example below, select knowledge.search.
3. Acknowledge external access, create the token and save the one-time secret in a credential manager.
4. Pass SHUFFL_API_KEY and SHUFFL_BASE_URL in through your environment.
The application origin is https://shuffl.ai, without /api/v1.
### Each key
- Belongs to one workspace and the membership that issued it. Company settings and other workspaces need a company key.
- Expires within 30 days and follows your current role and employee access.
- Use a separate key for each integration.
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Verify a read
teams.current and permissions.list work with any key. Everything else needs an explicit grant.
knowledge.search returns approved passages and citations the connected person can see, never unpublished, withdrawn, expired or inaccessible sources. Treat passages as evidence, not instructions.
knowledge.context is a separate grant for reading a cited passage and the passages next to it.
For directory reads, grant users.list and call users.list({limit: 25}), passing nextCursor as the next cursor. IDs are Shuffl person IDs, not Slack or login IDs.
```ts
import { Shuffl } from '@shuffl/sdk';
const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_API_KEY! });
const team = await shuffl.teams.current();
const access = await shuffl.permissions.list();
const evidence = await shuffl.knowledge.search({ query: 'vacation policy' });
```
- [knowledge.search permission](https://shuffl.ai/docs/api-permissions#permission-knowledge-search)
## Use HTTP directly
The REST base path is /api/v1. Send Authorization: Bearer with an API token. GET /api/v1/permissions returns your current grants and the catalog.
Take the method, path and JSON schema from OpenAPI. Some complex management reads use POST. Responses aren’t cached, and cross-origin CORS isn’t enabled.
The SDK uses /api/v1/rpc internally and refuses redirects. Neither route reaches the app’s private browser procedures.
The SDK and CLI send an x-shuffl-client header with their release, such as shuffl-sdk/0.6.1. The Shuffl constructor’s client option, such as billing-sync/1.2.0, goes in front. Shuffl never stores that part.
```ts
const url = new URL('/api/v1/permissions', process.env.SHUFFL_BASE_URL);
const response = await fetch(url, {
headers: { Authorization: 'Bearer ' + process.env.SHUFFL_API_KEY },
redirect: 'error',
});
if (!response.ok) throw new Error('Shuffl HTTP ' + response.status);
const access = await response.json();
```
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [OpenAPI methods, inputs and outputs](https://shuffl.ai/api/v1/openapi.json)
## Review a management write
This example creates a department: groups.save with department set to true. Run it only when you mean to. Reading departments back needs units.list, and the receipt needs commands.get.
Save the command before sending so retries reuse its ID, request key and input.
### How management writes work
- Writes return {receipt, result}.
- An identical retry returns the same receipt with result: null and doesn’t repeat the action.
- Different input under the same request key is a conflict.
- Sensitive actions require confirm set to the operation name.
- If unsure whether a call succeeded, read the current resources first.
### Programs and runs
- Programs start paused. Activating one turns on its schedule.
- Expected revisions stop you overwriting changes you haven’t seen.
- Provider handoffs and delivery results need their own readback.
```ts
const command = {
kind: 'list' as const,
name: 'Customer Success',
department: true,
confirm: 'groups.save' as const,
requestKey: 'create-customer-success-2026-10',
};
// Persist command before sending, so retries reuse the exact input.
const saved = await shuffl.groups.save(command);
const receipt = await shuffl.commands.get({ id: saved.receipt.id });
const departments = await shuffl.units.list({});
```
- [groups.save permission](https://shuffl.ai/docs/api-permissions#permission-groups-save)
- [Check the operation schema](https://shuffl.ai/api/v1/openapi.json)
## Manage company settings with a company key
A company owner or administrator creates a company key (shuffl_company_) in Settings → API keys and webhooks → Company keys.
The same Shuffl client takes it in place of a workspace key and calls the operations under /api/v1/company through shuffl.company, with the same types, errors and HTTPS rules.
company.current() returns the key’s company and grants with any company key. Every other method needs its own grant, such as company.members.list, which paginates like users.list.
Writes such as company.members.remove run once and take no requestKey.
A company key can’t call the workspace methods, and a workspace key can’t call shuffl.company. The SDK refuses the wrong kind with UNAUTHORIZED before sending anything.
```ts
import { Shuffl } from '@shuffl/sdk';
const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_COMPANY_KEY! });
const { permissions } = await shuffl.company.current();
const page = await shuffl.company.members.list({ limit: 100 });
const next = page.nextCursor
? await shuffl.company.members.list({ cursor: page.nextCursor, limit: 100 })
: null;
```
- [Company settings API reference](https://shuffl.ai/docs/api-reference/company)
- [Company keys and their grants](https://shuffl.ai/docs/api-permissions#company-keys)
## Handle errors and revoke access
SDK errors carry an oRPC code and HTTP status. The error codes list says what each one means and what to check.
### Retrying
- The SDK never retries writes. Retry with the same command input, then check the receipt or resource after an interrupted call.
- Don’t retry automatically with broader permissions.
- To cancel, pass an abort signal in the call options.
### Revoking
- Revoking a key in Workspace settings → API keys disables it and any keys issued from it. Deleting the local secret doesn’t.
- To change permissions, create a replacement and revoke the old one.
- Recreating a membership doesn’t revive an old key.
- [Error codes](https://shuffl.ai/docs/api-reference#errors)
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Related guides
- [Use Shuffl with your agent](https://shuffl.ai/docs/agent-quick-start)
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [SDK and CLI recipes](https://shuffl.ai/docs/sdk-cookbook)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Use the Shuffl CLI
> Run Shuffl operations from scripts without a model, with JSON output and the same endpoint permissions as the SDK.
Audience: Developers and automation owners
Kind: How-to guide
Canonical: https://shuffl.ai/docs/cli
## Install the CLI
The CLI needs Node.js 22 or later and installs a shuffl command. It shares the SDK’s version, so shuffl --version names the API contract.
To pin it, add @shuffl/cli as a dev dependency and run npx shuffl.
```sh
npm install --global @shuffl/cli
shuffl --version
shuffl --help
# Or run it once without installing:
npx @shuffl/cli --help
```
- [@shuffl/cli on npm](https://www.npmjs.com/package/@shuffl/cli)
- [Install the SDK instead](https://shuffl.ai/docs/sdk#install)
## Connect a workspace key
An administrator creates the API key in Workspace settings → API keys. Pass SHUFFL_API_KEY and SHUFFL_BASE_URL through the environment, or pipe the secret into login --token-stdin. Never put it in an argument.
Login checks the key before saving it.
### How the CLI keeps credentials
- SHUFFL_API_KEY wins over a saved login, and --base-url overrides the saved URL.
- A token works in one workspace only, so create a key in each workspace you need.
- Saved credentials work only with the base URL they were saved for.
- The config is saved with mode 0600 at $XDG_CONFIG_HOME/shuffl/config.json (default ~/.config/shuffl/config.json). SHUFFL_CONFIG_DIR overrides the directory.
- Logout removes the local copy. Revoke the key in Settings to stop other copies.
```sh
# credential-command represents your credential manager; replace it.
credential-command | shuffl login --base-url https://shuffl.ai --token-stdin
shuffl teams current --json
shuffl permissions list --json
```
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Read supported capabilities
Grant knowledge.search for the knowledge example, and users.list only for directory access.
Each command’s help needs no credentials. It names the command’s permission and whether it reads or writes.
```sh
shuffl knowledge search --help
shuffl knowledge search --query "vacation policy" --json
shuffl users list --limit 25 --json
```
- [Evidence and pagination behavior](https://shuffl.ai/docs/sdk#read)
## Supply explicit command input
For a management write, put the full command and a stable request key in a file, check it, then send it once.
shuffl groups save --input-file department-command.json --json behaves like groups.save in the SDK guide. Grant groups.save separately from units.list and commands.get.
Sensitive writes need the confirm value. Commands never start a model.
### Ways to pass input
- --input JSON, --input - for stdin, or --input-file FILE, one form per call.
- Top-level properties become flags. Nested arrays and objects are JSON.
- [Department command and retry example](https://shuffl.ai/docs/sdk#writes)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Manage company settings
shuffl company commands use a company key (shuffl_company_) from Settings → API keys and webhooks → Company keys. Pipe it into shuffl login --company --token-stdin, or set SHUFFL_COMPANY_KEY with SHUFFL_BASE_URL.
It is saved apart from the workspace key, in company.json next to config.json. Only shuffl company commands send it.
shuffl company current shows the key’s company and grants. Every other command names its grant in --help. shuffl logout --company removes the saved key; revoke it under Company keys to stop other copies.
```sh
credential-command | shuffl login --company --base-url https://shuffl.ai --token-stdin
shuffl company current --json
shuffl company members list --limit 100 --json
shuffl company members remove --user-id USER_ID --json
shuffl logout --company
```
- [Company settings API reference](https://shuffl.ai/docs/api-reference/company)
- [Company keys and their grants](https://shuffl.ai/docs/api-permissions#company-keys)
## Handle output, errors and logout
--json writes one JSON value to stdout, including {error: {code, message}} on failure. Human-readable errors go to stderr. Repeated flags and ambiguous input are rejected.
If a call is denied, check permissions, workspace and role. After a network failure or interrupted write, check the receipt before sending a new command.
shuffl logout removes the stored credential. When access should end, revoke the key in Settings and clear any token you supplied through the environment. Keep one-time credentials out of shared logs.
### Exit codes
- 0: success.
- 1: service failure.
- 2: usage or validation.
- 3: authentication or authorization.
- [Recover from an API error](https://shuffl.ai/docs/sdk#errors)
- [Error codes](https://shuffl.ai/docs/api-reference#errors)
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [SDK and CLI recipes](https://shuffl.ai/docs/sdk-cookbook)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use Shuffl with your agent](https://shuffl.ai/docs/agent-quick-start)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Connect an MCP client
> Connect an agent to the Shuffl MCP server over Streamable HTTP with OAuth or an API key, whose permissions choose its tools.
Audience: Workspace members and agent builders
Kind: How-to guide
Canonical: https://shuffl.ai/docs/mcp
## Create an API key for MCP
1. Sign in as an administrator, select the workspace and open Workspace settings → API keys → New API key. Keep the MCP permission selected under MCP server.
2. Name the key, acknowledge external access and save the one-time secret in the client’s secret store. Use one key per client.
3. Optionally choose Check connection. It sends one tools/list request with the key and lists the tools it can call. The check counts toward the key’s budget.
4. In the check, 401 means the key isn’t accepted, 403 that it lacks the MCP permission, and a network failure names the unreachable endpoint.
5. Configure the remote Streamable HTTP endpoint https://shuffl.ai/api/mcp. The client must send Authorization: Bearer with the API key on every request.
Anyone in a workspace can connect their own agent.
Connected apps also shows steps for other agents and lists your connections, each with Disconnect. Administrators see everyone’s connections and keys in Workspace settings → API keys.
### Two ways in
- A client with OAuth for remote MCP servers, such as Claude, needs only the Connector URL from Settings → Connected apps and no key. See Connect with OAuth below.
- A client that only sends a bearer header needs an API key with the MCP permission (mcp.knowledge). Keys without it are refused.
### An API key is
- Personal to you, this workspace and this deployment. Tools run with your current role, employee access and knowledge audience.
- Each endpoint permission on it is also an MCP tool, and the key works over the API, SDK and CLI too.
- Expires after 30 days. You can have ten active keys per workspace.
- [Open Connected apps](https://shuffl.ai/app/settings/connected-apps)
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
## Connect Claude
1. In Claude on the web or desktop, open Customize → Connectors, choose + and then Add custom connector.
2. Name it Shuffl, paste this URL and choose Add.
```
https://shuffl.ai/api/mcp
```
3. Choose Connect and allow access in your browser. On Team and Enterprise, an owner adds it first in Organization settings → Connectors.
- [Claude connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
## Connect Claude Code
1. Run:
```
claude mcp add --scope user \
--transport http shuffl \
https://shuffl.ai/api/mcp
```
2. In Claude Code, run /mcp, choose shuffl, then Authenticate and allow access in your browser.
### With an API key
1. Set SHUFFL_API_KEY to your key, then run:
```
claude mcp add --scope user \
--transport http shuffl \
https://shuffl.ai/api/mcp \
--header "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Claude Code MCP guide](https://code.claude.com/docs/en/mcp)
## Connect Codex
1. Run this, then allow access in your browser:
```
codex mcp add shuffl \
--url https://shuffl.ai/api/mcp
```
2. If the browser doesn’t open, sign in with:
```
codex mcp login shuffl
```
### With an API key
1. Set SHUFFL_API_KEY to your key, then run:
```
codex mcp add shuffl \
--url https://shuffl.ai/api/mcp \
--bearer-token-env-var SHUFFL_API_KEY
```
- [Codex MCP guide](https://developers.openai.com/codex/mcp)
## Connect Cursor
1. Choose Add to Cursor, or add this to ~/.cursor/mcp.json:
[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=shuffl&config=eyJ1cmwiOiJodHRwczovL3NodWZmbC5haS9hcGkvbWNwIn0=)
```
{
"mcpServers": {
"shuffl": {
"url": "https://shuffl.ai/api/mcp"
}
}
}
```
2. In Cursor’s MCP settings, choose Connect on shuffl and allow access in your browser.
### With an API key
1. Add this to ~/.cursor/mcp.json and set SHUFFL_API_KEY to your key:
```
{
"mcpServers": {
"shuffl": {
"headers": {
"Authorization": "Bearer ${env:SHUFFL_API_KEY}"
},
"url": "https://shuffl.ai/api/mcp"
}
}
}
```
- [Cursor MCP guide](https://cursor.com/docs/context/mcp)
## Connect ChatGPT
1. In ChatGPT on the web, turn on Developer mode in Settings → Security and login. It needs a paid plan, and on a workspace plan an admin must allow it.
2. Add an app with the + button in Plugins, name it Shuffl, paste this URL and choose OAuth.
```
https://shuffl.ai/api/mcp
```
3. Allow access in your browser, then turn on Shuffl from Developer mode in a chat’s + menu.
- [ChatGPT custom MCP server guide](https://developers.openai.com/api/docs/guides/custom-mcp-server)
## Connect VS Code
1. Choose Install in VS Code, or add this to .vscode/mcp.json:
[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=shuffl&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fshuffl.ai%2Fapi%2Fmcp%22%7D)
```
{
"servers": {
"shuffl": {
"type": "http",
"url": "https://shuffl.ai/api/mcp"
}
}
}
```
2. Start the server and allow access in the browser window VS Code opens.
### With an API key
1. Add this to .vscode/mcp.json. VS Code asks for the key once and stores it securely:
```
{
"inputs": [
{
"id": "shuffl-api-key",
"password": true,
"type": "promptString"
}
],
"servers": {
"shuffl": {
"headers": {
"Authorization": "Bearer ${input:shuffl-api-key}"
},
"type": "http",
"url": "https://shuffl.ai/api/mcp"
}
}
}
```
- [VS Code MCP guide](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
## Connect another client
1. Add this URL to any client that supports remote MCP servers over Streamable HTTP with OAuth. It opens a consent screen in your browser.
```
https://shuffl.ai/api/mcp
```
### With an API key
1. A client that only sends a header uses an API key with MCP access on every request:
```
Authorization: Bearer
```
2. The SDK, CLI and HTTP API use this base URL with the same kind of key:
```
https://shuffl.ai
```
3. Check a key over HTTP:
```
curl https://shuffl.ai/api/v1/permissions \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
4. Install the SDK or CLI:
```
npm install @shuffl/sdk
npm install --global @shuffl/cli
```
- [Agent quick start](https://shuffl.ai/docs/agent-quick-start)
## Connect with OAuth
1. Give the client the endpoint https://shuffl.ai/api/mcp with no key. It gets a 401, reads the metadata, registers itself and opens the authorization URL.
2. In Claude, use Customize → Connectors → Add custom connector with the recommended sign-in settings.
3. Sign in if asked. Check the client name and return address, choose the workspace, acknowledge external access and choose Allow access. Don’t allow sends the client access_denied.
4. The client exchanges the code for tokens and can call the knowledge tools plus the actions you chose. To change its actions, connect again.
Shuffl is an OAuth 2.1 authorization server for its MCP endpoint. The consent screen names the client and its return address.
### Discovery
- Protected-resource metadata: /.well-known/oauth-protected-resource, also at /.well-known/oauth-protected-resource/api/mcp.
- Authorization-server metadata: /.well-known/oauth-authorization-server, which advertises client_id_metadata_document_supported.
- Every 401 carries a WWW-Authenticate challenge naming the metadata and the scope knowledge:read.
### Clients and grants
- Clients identify with a client ID metadata document (an https URL, as Claude does) or register dynamically, always as public clients with no secret.
- Only the authorization-code grant with PKCE S256 is allowed.
- Both the authorization and token requests carry resource=https://shuffl.ai/api/mcp. Tokens are bound to that resource.
- Redirect URIs must be registered and https, or plain http on the loopback host only. A loopback redirect may use any port; any other must match exactly.
### Consent
- You pick one workspace where you have employee access.
- Actions can be any permission an API key could hold, except API key management and operator access. Every connection gets the three knowledge tools.
- Consent is per person, workspace and client.
### Tokens and disconnecting
- Access tokens last one hour and renew with a rotating refresh token for up to 30 days.
- Replaying a code or reusing a refresh token revokes the connection.
- Every request is checked like a key, before and after each tool runs.
- Connected apps lists each client, who connected it, expiry and last use. Disconnect your own there. Administrators can disconnect any, there or in Workspace settings → API keys.
- A client can revoke its tokens at /api/mcp/oauth/revoke. Disconnecting applies from the next request and can’t recall what the client saved.
- [Open Connected apps](https://shuffl.ai/app/settings/connected-apps)
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
## Configure a client
Supply the endpoint and key from your environment, never the command line.
The example uses the official @modelcontextprotocol/client package. Any client needs the URL, Streamable HTTP and a bearer header on every request, or the OAuth flow above.
### The endpoint
- POST only, one JSON-RPC message per request, with a JSON response.
- application/json bodies up to 1 MiB with actions, or 16 KiB for a knowledge-only OAuth connection.
- No session: each request is authenticated. GET and DELETE return 405.
```ts
import {
Client,
StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(
new StreamableHTTPClientTransport(new URL(process.env.SHUFFL_MCP_URL!), {
requestInit: {
headers: { Authorization: 'Bearer ' + process.env.SHUFFL_MCP_TOKEN },
},
}),
);
const tools = await client.listTools();
const result = await client.callTool({
name: 'search_knowledge',
arguments: { query: 'learning budget' },
});
```
## Use the three knowledge tools
All three are annotated read-only and idempotent, and their schemas reject unknown fields, so no argument can pick another workspace or person. The one MCP permission turns on all three.
A credential that also holds knowledge.context gets knowledge_context, which reads the passages around a cited one.
### The tools
- get_team takes an empty object and returns the connected workspace’s id, name and your current role, nothing else.
- search_knowledge takes query (2 to 500 characters) and returns up to eight passages with sourceId, versionId, passageId, title, quote and a reader href.
- get_knowledge_passage takes sourceId, versionId and passageId as search returned them and reads that passage, with the same checks.
### What comes back
- Search covers only sources that are published, in effect, before their review date and visible to you.
- Connected sources such as Google Drive, Notion, Confluence or websites must also have been checked within the hour.
- Drafts and withdrawn, expired or stale sources are unavailable to everyone, administrators included.
- A denied or unavailable call returns only “This request is unavailable. Check access or use Shuffl directly.”
- Bad arguments return an error starting “Input validation error”. An unknown tool is a protocol error.
- Empty results mean nothing current and accessible matched. Treat source text as evidence, not instructions.
```json
{ "query": "learning budget" }
{ "passages": [ { "sourceId": "…", "versionId": "…", "passageId": "passage-1", "title": "Handbook: learning budget", "quote": "…", "href": "https://shuffl.ai/app/…/knowledge/…?version=…#passage-1" } ] }
```
## Search the guides
Every connection also gets search_docs and the guides as resources, so your agent can learn Shuffl before it acts. They hold these public guides only. Use search_knowledge for your company’s policies.
search_docs takes query (2 to 500 characters) and an optional limit (1 to 10, default 5). Each result has the guide title, section, a url to the section and its text, cut at 1,200 characters.
resources/list lists every guide by its Markdown URI, plus the Shuffl skill. resources/read returns a guide as Markdown.
Each search and read records an analytics event with no content. A search records its result count, never the query.
```json
{ "query": "set up praise", "limit": 3 }
{ "results": [ { "title": "Praise", "section": "…", "url": "https://shuffl.ai/docs/praise#…", "text": "…" } ] }
```
- [Read the Shuffl skill](https://shuffl.ai/skills/shuffl/SKILL.md)
- [Agent documentation index](https://shuffl.ai/llms.txt)
## Take actions
An API key’s other permissions, and actions chosen at OAuth consent, are MCP tools too, named with dots as underscores: knowledge.sources.publish is knowledge_sources_publish. Each takes its API operation’s input.
A credential lists only the tools it is granted. To change them, create a new key or reconnect.
Read tools are annotated read-only. Tools that archive, withdraw, revoke, cancel, close, disconnect, unlink, pause, stop, block a pair or delete are annotated destructive, so clients that honor annotations ask first.
Uploading a PDF in parts is slow through a model. Importing a website or saving article text is usually better.
### Same rules as the API
- Every call runs through the same handler as HTTP, with your current role, Knowledge verifier grant, employee access, knowledge audience and the operation’s own checks.
- Writes leave the same receipt and audit event.
- An employee can’t grant administrator permissions, and a demotion applies from the next call.
- Write tools need a requestKey: a new value per intended action, reused only to retry it, which returns the first receipt.
- Operations with a confirmation need confirm set to the operation name.
- A refused call returns an error starting with the reason code, such as FORBIDDEN, NOT_FOUND or CONFLICT.
### Pulse with your Self permissions
- pulse_today reads today’s Pulse question. pulse_answer and pulse_skip answer or skip it as you.
- Answering again replaces your answer. No tool returns it, even to an administrator.
- Administrator tools such as pulse_insights, pulse_questionDetail and pulse_actions read totals for groups of seven or more, never one response.
- [Every MCP tool](https://shuffl.ai/docs/mcp-tools)
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
- [How management writes work](https://shuffl.ai/docs/sdk#writes)
## Ask your agent to…
1. How are our new hires finding their first 90 days? playbooks_firstDaysResults reads the combined answers to the 30, 60 and 90 day check-ins, never one person’s.
2. Answer my new hire check-in for me. playbooks_firstDaysCheckIns reads your open check-in and playbooks_answerFirstDaysCheckIn answers it as you.
3. Sign Kwame’s anniversary card and say thanks for the spring launch. celebrations_signCard adds your note to a card you were asked to sign.
4. What is Mello nudging us about this week? digest_nudges lists Mello’s culture nudges. digest_actOnNudge records that you acted on one; digest_dismissNudge dismisses it.
5. Which Pulse questions is Mello suggesting? pulse_proposals lists them. pulse_editProposal rewords one, pulse_decideProposal approves or dismisses it, and pulse_requestProposals asks for more.
6. Add the Psychological safety questions to Pulse. pulse_addTemplate adds a question set from the templates.
7. Upload our old intros report so we can switch. teams_uploadPairHistory stages the CSV for the review screen. Nothing changes until an administrator applies it in Shuffl.
8. Draw a picture for our Mentor of the quarter badge. badges_generatePicture draws it; communities_generateCover does the same for a community.
Each example needs the permission its tool is named after. If your client asks before actions, your agent shows you a write before running it.
- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)
## Follow citations in the browser
Each passage links to the cited version of its source in the Shuffl reader. The link works only for a signed-in member who can read it; the API key isn’t used there. Ask your agent to include the links.
Signed in, the reader opens the cited version at the passage. Signed out, Shuffl sends you to sign in, then back to that version without the passage anchor.
If you can’t read the source, or it was withdrawn or replaced since the search, the reader says it’s unavailable without revealing whether it exists.
- [How sources are published](https://shuffl.ai/docs/knowledge)
## Limits and revocation
Shuffl stores only the key’s issuing membership, request window, last tool name and outcome, and last-used time. It never stores your queries, passages or the key itself.
Each action tool call records an analytics event with its outcome and no content.
### Limits
- Each API key has 120 requests a minute, shared between MCP and HTTP and counted from the window’s first request, initialization included.
- An OAuth access token has 60 a minute.
- Over the limit, MCP returns 429 with Retry-After: 60.
### Revocation
- Administrators list and revoke keys in Workspace settings → API keys. Revocation is immediate: access is checked at authentication and before and after each tool.
- Suspending your employee access deactivates your keys permanently.
- Revoking can’t remove what the agent kept. If a key may be exposed, revoke it first, then replace it.
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [Use Chat](https://shuffl.ai/app/chat)
## Troubleshoot a connection
### By status code
- 401: the bearer header is missing, or the key is unknown, expired, revoked or from another deployment, or your access changed. Check the endpoint’s deployment. If the key shows Revoked or Expired, create a new one.
- 403 with error="insufficient_scope": the key lacks the MCP permission.
- 403 “Origin is not allowed”: the Origin or host doesn’t match the deployment. Fix the URL and don’t proxy through another origin.
- 405: the client used GET or DELETE instead of Streamable HTTP with no session.
- 400: send one application/json object per request, never a batch, within the size limit above.
- 429: wait for Retry-After and reconnect, or revoke unused keys if it happened while creating one.
- 503: retry later and use Shuffl directly if it persists.
### Tool results
- An error tool result means the source isn’t published, fresh and visible to you, the IDs aren’t valid here, or access changed mid-call. Search again for current IDs.
- “Input validation error” names the argument to fix.
- For an empty search, try the source’s own words and check it is Published, before its review date and visible to you.
- A citation that opens sign-in means that browser is signed out. One that says unavailable means that account can’t read the source or it changed.
- An OAuth connection can’t create or revoke keys. An API key can only with those permissions.
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
## What stays in the browser
Confidential clients, client secrets and other grant types aren’t offered. Only the consent flow above issues OAuth tokens, and they can’t call the REST API or SDK.
Clients that only send a bearer header use an API key with the MCP permission.
### Browser only
Most app actions are MCP tools. These stay in the browser so no credential can widen its own authority.
- Deleting or restoring a workspace, and transferring ownership.
- Granting HR responder or Knowledge verifier.
- Verified email domains, single sign-on and SCIM.
- Your own profile photo and cover, and the calendar connection.
- Running or dismissing Mello’s prepared actions.
- [Use the SDK or HTTP API instead](https://shuffl.ai/docs/sdk)
## Related guides
- [Use Shuffl with your agent](https://shuffl.ai/docs/agent-quick-start)
- [MCP tool list](https://shuffl.ai/docs/mcp-tools)
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [Review and publish knowledge](https://shuffl.ai/docs/knowledge)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Webhooks
> Send signed events to your own systems when people, Knowledge, playbooks or the workspace change, and check each request came from Shuffl.
Audience: Workspace administrators and developers
Kind: How-to guide
Canonical: https://shuffl.ai/docs/webhooks
## Add an endpoint
1. Open Settings → API keys and webhooks → Webhooks and choose Add endpoint.
2. Enter the URL that should receive events and, optionally, a description.
3. Pick whole groups or open a group to pick single events.
4. Save the signing secret Shuffl shows next. You can reveal it again later from the endpoint.
5. Shuffl sends a webhook.test event straight away. Check it under Deliveries, or press Send test event at any time.
Workspace owners and administrators manage webhooks in Settings → API keys and webhooks → Webhooks. A workspace can have up to 10 endpoints, each with its own URL, events and signing secret.
Shuffl sends one HTTPS POST per event to every endpoint subscribed to it, a few seconds after the change is saved. Endpoints must use https and a public address; Shuffl doesn’t follow redirects.
- [Open Webhooks](https://shuffl.ai/app/settings/webhooks)
## What each request carries
Every request body is one JSON event. id is unique per event and stays the same on every retry and resend, so use it to ignore duplicates.
Events can arrive out of order. Compare created_at, or read the current state through the API.
Payloads are thin on purpose. They carry ids, states, counts and revisions, never names, emails, Slack ids, message text or document titles.
To learn more, read the record through the API with a key that holds the event group’s read scope.
actor.type is user when a person made the change, with their user id. It is system, with id null, when Shuffl, Slack, an HR system or a schedule did.
```json
{
"id": "evt_6f1c2a8e4b3d4f0a9c7e5d2b1a0f3e4c",
"type": "person.created",
"api_version": "2026-10-17",
"created_at": "2026-10-17T09:12:44.512Z",
"workspace_id": "",
"actor": { "type": "user", "id": "" },
"data": { "person_id": "" }
}
```
## Check the signature
Shuffl signs every request the Standard Webhooks way, so most webhook libraries verify it as is. @shuffl/sdk exports verifyWebhook, which does all of this and returns the typed event.
The signature is HMAC-SHA256 over id.timestamp.body, keyed with the base64 part of your whsec_ secret, then base64-encoded and prefixed v1,.
While a rolled secret’s old value is still kept, the header carries both signatures separated by a space. Accept the request if either matches.
### Headers on each request
- webhook-id: the event id.
- webhook-timestamp: Unix seconds.
- webhook-signature: one or more v1, signatures.
### If you verify by hand
- Verify the raw body before parsing it.
- Compare in constant time.
- Refuse timestamps more than five minutes from your clock.
SDK:
```ts
import { verifyWebhook, WebhookVerificationError } from '@shuffl/sdk';
// Read the raw body: verify before parsing or reformatting it.
export async function POST(request: Request) {
const body = await request.text();
try {
const event = await verifyWebhook({
body,
headers: request.headers,
secret: process.env.SHUFFL_WEBHOOK_SECRET!,
});
if (event.type === 'person.created') {
// event.data.person_id is typed
}
return new Response(null, { status: 204 });
} catch (error) {
if (error instanceof WebhookVerificationError)
return new Response('Bad signature', { status: 401 });
throw error;
}
}
```
Node:
```js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(body, headers, secret) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300)
throw new Error('Too old');
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key)
.update(`${id}.${timestamp}.${body}`)
.digest();
const valid = headers['webhook-signature']
.split(' ')
.map((part) => Buffer.from(part.replace(/^v1,/, ''), 'base64'))
.some((given) => given.length === expected.length && timingSafeEqual(given, expected));
if (!valid) throw new Error('Bad signature');
return JSON.parse(body);
}
```
Python:
```python
import base64, hashlib, hmac, json, time
def verify(body: bytes, headers, secret: str):
msg_id = headers['webhook-id']
timestamp = headers['webhook-timestamp']
if abs(time.time() - int(timestamp)) > 300:
raise ValueError('Too old')
key = base64.b64decode(secret.removeprefix('whsec_'))
signed = f'{msg_id}.{timestamp}.'.encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
given = [p.split(',', 1)[1].encode() for p in headers['webhook-signature'].split(' ')]
if not any(hmac.compare_digest(expected, g) for g in given):
raise ValueError('Bad signature')
return json.loads(body)
```
- [Standard Webhooks specification](https://www.standardwebhooks.com/)
## Answer quickly; Shuffl retries the rest
Answer with any 2xx within 10 seconds to accept an event. Do the work afterwards, not before answering.
Shuffl retries timeouts, connection errors, 408, 429 and 5xx answers. The tries come after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours: a little over a day in all.
A Retry-After header pushes the next try later. Other 4xx answers and redirects are not retried.
### When an endpoint is turned off
- An endpoint that answers 410 Gone is turned off at once.
- One whose deliveries have failed for five days is turned off too, and workspace owners and administrators get an email.
- If the administrator who added an endpoint loses that role, it pauses until another administrator turns it back on.
## Read deliveries, resend and roll the secret
Open an endpoint to see its deliveries: each one’s request body, headers with the signature hidden, and every attempt’s status, time and the start of the response.
Shuffl keeps 30 days of deliveries. Endpoint changes, secret reveals and resends appear in Settings → Activity.
### Actions on an endpoint
- Resend sends one delivery again with the same event id.
- Resend failed deliveries sends every failed event from the last hour, day or week once more.
- Roll secret makes a new secret and can keep the old one for an hour, a day or a week while you update your receiver.
- Turning an endpoint off stops deliveries. Events that happen while it is off are not sent later.
- Deleting an endpoint removes its delivery log.
- [Open Webhooks](https://shuffl.ai/app/settings/webhooks)
## Manage webhooks from code
Everything in Settings → API keys and webhooks → Webhooks is also in the API, the SDK, the CLI and the workspace MCP server.
Changes are management commands like any other. Each takes confirm set to the operation name and a requestKey, and returns {receipt, result}.
### Operations
- webhooks.list, webhooks.catalog, webhooks.get, webhooks.create, webhooks.update, webhooks.delete, webhooks.rotateSecret and webhooks.sendTest.
- webhooks.deliveries.list, deliveries.get, deliveries.replay and deliveries.replayFailed.
### Permissions
- A key needs webhooks:read or webhooks:write.
- It can subscribe an endpoint only to the event groups whose read scope it also holds.
- A key gets the secret when it creates an endpoint or rolls the secret. Revealing it again is only in Settings.
SDK:
```ts
const { result } = await shuffl.webhooks.create({
confirm: 'webhooks.create',
requestKey: 'hr-sync-endpoint',
url: 'https://example.com/webhooks/shuffl',
events: ['person.created', 'person.access_changed'],
});
// Save result.secret now; a retry with the same requestKey returns result: null.
const { deliveries } = await shuffl.webhooks.deliveries.list({
endpointId: result!.endpoint.id,
state: 'failed',
});
```
CLI:
```sh
shuffl webhooks list --json
shuffl webhooks deliveries list --endpoint-id "" --state failed --json
```
HTTP:
```sh
curl -X POST https://shuffl.ai/api/v1/manage/webhooks/list \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" -d '{}'
```
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
## Events
Each event lists the data fields it can carry. An endpoint receives only the events it picked.
### Actions
Requests Mello filed in another platform for a person, and what the platform decided. Needs users:read for an API key.
- `action.approved`: The platform approved a request Mello filed (`action_id`, `person_id`, `kind`, `provider`)
- `action.cancelled`: A request Mello filed was cancelled (`action_id`, `person_id`, `kind`, `provider`)
- `action.declined`: The platform declined a request Mello filed (`action_id`, `person_id`, `kind`, `provider`)
- `action.failed`: A request could not be filed in the platform (`action_id`, `person_id`, `kind`, `provider`)
- `action.submitted`: Mello filed a request in the platform, pending there (`action_id`, `person_id`, `kind`, `provider`)
### Connections
Connections programs, rounds and who takes part. Needs programs:read for an API key.
- `participant.opted_in`: A person joined a Connections program (`person_id`, `program_id`, `revision`)
- `participant.opted_out`: A person left a Connections program (`person_id`, `program_id`, `revision`)
- `participant.profile_updated`: A person updated their profile (`person_id`)
- `program.archived`: A program was archived (`program_id`)
- `program.created`: A Connections program or playbook was created (`program_id`, `kind`)
- `program.paused`: A program was paused (`program_id`)
- `program.resumed`: A program was switched on (`program_id`)
- `program.updated`: A program’s settings changed (`program_id`, `kind`)
- `round.planned`: Shuffl planned a round of introductions (`round_id`, `groups`, `unmatched`)
- `round.requested`: Someone asked for a round of introductions (`round_id`, `retry`)
### HR team
Who answers HR requests. Needs hr:read for an API key.
- `hr.responder.granted`: Someone joined the HR team that answers requests (`person_id`, `revision`)
- `hr.responder.revoked`: Someone left the HR team (`person_id`, `revision`)
- `hr.team.renamed`: The HR team’s name changed (`revision`)
### Knowledge
Proposals, drafts, published pages and connected sources. Needs knowledge:read for an API key.
- `knowledge.document.archived`: A page was archived (`document_id`)
- `knowledge.document.audience_changed`: Who can read a published page changed (`document_id`, `version_id`, `audience`, `previous_audience`)
- `knowledge.document.published`: A page was published (`document_id`, `version_id`, `audience`)
- `knowledge.document.restored`: An archived page was restored (`document_id`)
- `knowledge.document.withdrawn`: A published page was withdrawn (`document_id`)
- `knowledge.draft.saved`: A draft of a page was saved (`document_id`, `version_id`)
- `knowledge.proposal.created`: Mello proposed new or changed Knowledge for review (`proposal_id`, `revision`)
- `knowledge.proposal.published`: A verifier approved a proposal, as written or edited (`proposal_id`, `revision`, `document_id`, `edited`)
- `knowledge.proposal.rejected`: A verifier turned a proposal down (`proposal_id`, `revision`)
- `knowledge.section.removed`: A section was removed from a handbook page (`document_id`)
- `knowledge.source.access_lost`: Shuffl can no longer read a connected document (`document_id`)
- `knowledge.source.connected`: A Knowledge source such as Google Drive was connected (`connection_id`)
- `knowledge.source.disconnected`: A Knowledge source was disconnected (`connection_id`)
- `knowledge.verifier.granted`: Someone can now verify Knowledge (`person_id`, `revision`)
- `knowledge.verifier.revoked`: Someone can no longer verify Knowledge (`person_id`, `revision`)
### People
People, roles, access, identities and departments. Needs users:read for an API key.
- `person.access_changed`: A person’s app access or employment changed (`person_id`, `status`, `previous_status`, `employment`, `previous_employment`, `revision`)
- `person.access_suspended`: A person’s access was suspended (`person_id`)
- `person.created`: A person was added to the directory (`person_id`, `revision`)
- `person.identity_linked`: A Slack or single sign-on identity was linked to a person (`person_id`, `identity_id`, `provider`)
- `person.identity_revoked`: A linked identity was removed from a person (`person_id`, `identity_id`, `provider`)
- `person.manager_changed`: A person’s manager changed (`person_id`)
- `person.role_changed`: A person’s workspace role changed (`person_id`, `role`, `previous_role`)
- `person.updated`: A person’s directory record changed (`person_id`, `revision`)
### Playbooks
Playbook enrollments, steps, buddies and check-ins. Needs playbooks:read for an API key.
- `playbooks.approved`: HR approved a person’s playbook steps (`enrollment_id`)
- `playbooks.buddy.accepted`: A buddy said yes (`enrollment_id`)
- `playbooks.buddy.assigned`: A buddy was asked to help a new hire (`enrollment_id`, `buddy_person_id`)
- `playbooks.buddy.declined`: A buddy said no (`enrollment_id`)
- `playbooks.check_in.answered`: A new hire answered a check-in: all_good, or need_help when they asked HR for help (`step_id`, `enrollment_id`, `answer`)
- `playbooks.enrolled`: A person started a playbook (`enrollment_id`, `person_id`, `program_id`, `with_buddy`)
- `playbooks.enrollment_removed`: A person was taken off a playbook (`enrollment_id`, `reason`)
- `playbooks.schedule_changed`: A person’s playbook schedule changed (`enrollment_id`)
- `playbooks.step.failed`: A playbook step could not be delivered (`step_id`, `reason`)
- `playbooks.step.needs_review`: A playbook step waits for HR before it sends (`step_id`)
- `playbooks.step.sent`: A playbook step reached its person (`step_id`)
### Webhooks
Test events and endpoints Shuffl turned off. Needs webhooks:read for an API key.
- `webhook.endpoint.disabled`: Shuffl turned an endpoint off after it kept failing (`endpoint_id`, `reason`)
- `webhook.test`: A test event someone sent from Settings or the API (`endpoint_id`)
### Workspace
The workspace itself and its Slack connection. Needs team:read for an API key.
- `slack.connected`: Slack was connected
- `slack.connection_expired`: Slack stopped accepting Shuffl’s connection (`reason`)
- `slack.uninstalled`: Shuffl was removed from Slack (`reason`)
- `workspace.deletion_requested`: An owner asked to delete the workspace (`delete_after`)
- `workspace.exported`: Someone exported the workspace’s data
- `workspace.renamed`: The workspace was renamed
- `workspace.restored`: The workspace was restored (`deletion_canceled`)
- `workspace.slack_join_access_changed`: Who can join from Slack changed
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
Agent documentation index: https://shuffl.ai/llms.txt
---
# API endpoint permissions
> Choose Read and Write grants and look up the permission ID for every supported API operation.
Audience: Administrators and integration developers
Kind: Reference
Canonical: https://shuffl.ai/docs/api-permissions
## Choose exact grants
In Settings, search for a resource or operation, select Read or Write for a group, or expand it to pick individual endpoints. A minus means a partial selection.
teams.current and permissions.list work with any authorized key. Every other operation needs an exact grant plus current tenant, membership, role, employee-access and resource checks.
The catalog may list operations your role or deployment doesn’t offer. To see what you can grant and hold, use permissions.list in the SDK, GET /api/v1/permissions or shuffl permissions list --json.
### Grants don’t imply each other
- users.list doesn’t grant users.get.
- groups.save doesn’t grant groups.list or groups.remove.
- Write never includes Read.
- [Open API keys](https://shuffl.ai/app/settings/api-keys)
- [OpenAPI input/output schemas and HTTP paths](https://shuffl.ai/api/v1/openapi.json)
## Revocation, replacement and delegation
Grants are fixed when a key is issued. To change them, create a replacement and revoke the old key. Revocation and expiry also invalidate keys issued from it. New endpoints never join an existing key.
MCP access is the mcp.knowledge permission, checked by the MCP server rather than an HTTP endpoint. API permissions don’t grant browser sign-in, provider OAuth consent or access to another workspace.
### Delegating keys
- Creating a credential through the SDK, API or CLI takes permissions: ["users.list"].
- The issuer must hold credentials.api.create and every permission it grants. The grants must fit within the parent and all its ancestors.
- Delegation goes at most three generations deep and can’t outlive its parent.
- A key with credentials.api.create can delegate mcp.knowledge only if it holds mcp.knowledge itself.
## Company keys
The company API is in OpenAPI, the SDK (shuffl.company) and the CLI (shuffl login --company or SHUFFL_COMPANY_KEY). The Company settings API reference has examples for each.
Deleting or restoring the company, transferring ownership, company roles, email domains, single sign-on, SCIM, Slack mapping, billing and product analytics stay in Settings for every credential.
### Two kinds of key
- A workspace key (shuffl_api_) works in one workspace with the permissions above.
- A company key (shuffl_company_) manages one company’s settings. It can’t read or change anything inside a workspace: no People, Knowledge, requests or programs.
- Neither works where the other does. The wrong kind gets 401.
### Company keys
- Company owners and administrators create them in Settings → API keys and webhooks → Company keys.
- A key acts as its creator, with their current company role. It pauses while they aren’t a company owner or administrator.
- Keys last 7, 30 or 90 days with 120 requests a minute. A company can have 10 active.
- Creating or revoking a key, and every change made with one, is recorded for Shuffl support.
### Over HTTP
- GET /api/v1/company shows the key’s company and grants.
- GET /api/v1/company/ runs a read. POST with a JSON body runs a change.
- The company always comes from the key.
### Company keys can be granted
- company.details: read the company name, logo and default workspace
- company.workspaces.list: list the company's workspaces
- company.members.list: list company members and their company roles
- company.emailDomains.list: list the company's email domains and their verification
- company.slack.list: list the slack workspaces connected to the company
- company.rename: rename the company
- company.workspaces.setDefault: choose the workspace new email domain and single sign-on members join
- company.members.remove: remove someone from the company (administrators only with an owner’s key)
SDK:
```ts
import { Shuffl } from '@shuffl/sdk';
const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_COMPANY_KEY! });
const { items } = await shuffl.company.members.list({ limit: 100 });
await shuffl.company.members.remove({ userId: '' });
```
CLI:
```sh
shuffl company members list --limit 100 --json
shuffl company members remove --user-id "" --json
```
HTTP:
```sh
curl "https://shuffl.ai/api/v1/company/members.list?limit=100" \
-H "Authorization: Bearer $SHUFFL_COMPANY_KEY"
curl -X POST https://shuffl.ai/api/v1/company/members.remove \
-H "Authorization: Bearer $SHUFFL_COMPANY_KEY" \
-H "Content-Type: application/json" \
-d '{"userId":""}'
```
- [Open Company API keys](https://shuffl.ai/app/settings/company/api-keys)
- [Company settings API reference](https://shuffl.ai/docs/api-reference/company)
## access
### access.get
Read · Read one person's workspace role and app access
Exact permission: `access.get`. Underlying role scope: `access:read`.
### access.slackWaiting
Read · List Slack members waiting for access to Shuffl
Exact permission: `access.slackWaiting`. Underlying role scope: `access:read`.
### access.enableSlack
Write · Give these Slack people employee access
Exact permission: `access.enableSlack`. Underlying role scope: `access:write`.
### access.save
Write · Change employee product access
Exact permission: `access.save`. Underlying role scope: `access:write`.
### access.saveRole
Write · Change a member’s team role
Exact permission: `access.saveRole`. Underlying role scope: `access:write`.
## actions
### actions.mine
Read · List the requests Mello filed for you and where each stands
Exact permission: `actions.mine`. Underlying role scope: `self:read`.
## assistant
### assistant.conversations
Read · List your conversations with Mello
Exact permission: `assistant.conversations`. Underlying role scope: `assistant:read`.
### assistant.history
Read · Read the messages in one of your conversations with Mello
Exact permission: `assistant.history`. Underlying role scope: `assistant:read`.
### assistant.delete
Write · Delete one of your conversations with Mello
Exact permission: `assistant.delete`. Underlying role scope: `assistant:write`.
### assistant.send
Write · Ask Mello a question in a conversation
Exact permission: `assistant.send`. Underlying role scope: `assistant:write`.
### assistant.stop
Write · Stop an answer Mello is still writing
Exact permission: `assistant.stop`. Underlying role scope: `assistant:write`.
## badges
### badges.holders
Read · List the people who hold a badge, as far as each lets you see
Exact permission: `badges.holders`. Underlying role scope: `users:read`.
### badges.list
Read · List the team’s badges, who holds them and any open requests you decide
Exact permission: `badges.list`. Underlying role scope: `users:read`.
### badges.ofPerson
Read · List a person's badges
Exact permission: `badges.ofPerson`. Underlying role scope: `users:read`.
### badges.settings
Read · Read the badge suggestion settings
Exact permission: `badges.settings`. Underlying role scope: `praise:read`.
### badges.award
Write · Give a badge you own to a person
Exact permission: `badges.award`. Underlying role scope: `profile:write`.
### badges.claim
Write · Claim a badge with its code
Exact permission: `badges.claim`. Underlying role scope: `profile:write`.
### badges.decideRequest
Write · Approve or decline a request for a badge
Exact permission: `badges.decideRequest`. Underlying role scope: `profile:write`.
### badges.generatePicture
Write · Draw an AI picture for a badge you own. Keeps a picture already set unless replace is true; idea says what to draw
Exact permission: `badges.generatePicture`. Underlying role scope: `profile:write`.
### badges.hideOwn
Write · Hide or show one of your badges on your profile
Exact permission: `badges.hideOwn`. Underlying role scope: `profile:write`.
### badges.request
Write · Ask for a badge
Exact permission: `badges.request`. Underlying role scope: `profile:write`.
### badges.revoke
Write · Take a badge back from a person
Exact permission: `badges.revoke`. Underlying role scope: `profile:write`.
### badges.save
Write · Create or edit a badge you own
Exact permission: `badges.save`. Underlying role scope: `profile:write`.
### badges.saveSettings
Write · Turn badge offers from praise on or off, and choose the launch channel
Exact permission: `badges.saveSettings`. Underlying role scope: `praise:write`.
### badges.setHidden
Write · Hide or show a badge for the whole workspace
Exact permission: `badges.setHidden`. Underlying role scope: `users:write`.
### badges.uploadPicture
Write · Set a badge picture from a PNG, JPEG or WebP picture sent as base64, for a badge you own
Exact permission: `badges.uploadPicture`. Underlying role scope: `profile:write`.
## capabilities
### capabilities.requests
Read · How many people asked HR to connect a system, per capability
Exact permission: `capabilities.requests`. Underlying role scope: `integrations:read`.
### capabilities.sheet
Read · What Mello can answer and do for you here, and what connecting a system would add
Exact permission: `capabilities.sheet`. Underlying role scope: `self:read`.
### capabilities.unlocks
Read · What people can ask and do once an HR system or document tool is connected
Exact permission: `capabilities.unlocks`. Underlying role scope: `self:read`.
### capabilities.dismissRequests
Write · Clear the asks to connect a system for one capability
Exact permission: `capabilities.dismissRequests`. Underlying role scope: `integrations:write`.
### capabilities.requestConnection
Write · Ask HR to connect the system this needs
Exact permission: `capabilities.requestConnection`. Underlying role scope: `self:write`.
## celebrations
### celebrations.card
Read · Open a celebration card you can sign or were given
Exact permission: `celebrations.card`. Underlying role scope: `self:read`.
### celebrations.cards
Read · List celebration cards to sign and cards you were given
Exact permission: `celebrations.cards`. Underlying role scope: `self:read`.
### celebrations.deliveries
Read · List the celebration messages Shuffl sent
Exact permission: `celebrations.deliveries`. Underlying role scope: `celebrations:read`.
### celebrations.mine
Read · List the celebrations you received
Exact permission: `celebrations.mine`. Underlying role scope: `self:read`.
### celebrations.preferences
Read · Read your birthday and work anniversary sharing preferences
Exact permission: `celebrations.preferences`. Underlying role scope: `self:read`.
### celebrations.preview
Read · Preview a celebration message
Exact permission: `celebrations.preview`. Underlying role scope: `celebrations:read`.
### celebrations.program
Read · Read the Celebrations settings
Exact permission: `celebrations.program`. Underlying role scope: `celebrations:read`.
### celebrations.review
Read · Review upcoming birthdays and work anniversaries
Exact permission: `celebrations.review`. Underlying role scope: `celebrations:read`.
### celebrations.startDates
Read · Read which start date anniversaries count from and the start dates that look wrong
Exact permission: `celebrations.startDates`. Underlying role scope: `celebrations:read`.
### celebrations.thisWeek
Read · List who was celebrated in a channel in the last seven days
Exact permission: `celebrations.thisWeek`. Underlying role scope: `self:read`.
### celebrations.refresh
Write · Look for new birthdays and work anniversaries to celebrate now
Exact permission: `celebrations.refresh`. Underlying role scope: `celebrations:write`.
### celebrations.removeCardNote
Write · Remove your note from this celebration card
Exact permission: `celebrations.removeCardNote`. Underlying role scope: `self:write`.
### celebrations.save
Write · Save celebration settings; enabling them schedules messages
Exact permission: `celebrations.save`. Underlying role scope: `celebrations:write`.
### celebrations.saveAnniversaryDate
Write · Choose which start date work anniversaries count from; reschedules them
Exact permission: `celebrations.saveAnniversaryDate`. Underlying role scope: `celebrations:write`.
### celebrations.savePreferences
Write · Save your birthday and work anniversary sharing preferences
Exact permission: `celebrations.savePreferences`. Underlying role scope: `self:write`.
### celebrations.signCard
Write · Sign this celebration card with your note
Exact permission: `celebrations.signCard`. Underlying role scope: `self:write`.
## channels
### channels.list
Read · List available Slack channels
Exact permission: `channels.list`. Underlying role scope: `programs:read`.
## commands
### commands.get
Read · Read your own command receipt
Exact permission: `commands.get`. Underlying role scope: `null`.
## communities
### communities.channelSuggestions
Read · List Slack channels, with the ones that look like communities suggested
Exact permission: `communities.channelSuggestions`. Underlying role scope: `programs:read`.
### communities.createCapabilities
Read · Read the current permission to create public or private community channels
Exact permission: `communities.createCapabilities`. Underlying role scope: `programs:read`.
### communities.list
Read · List communities with the members you may see
Exact permission: `communities.list`. Underlying role scope: `users:read`.
### communities.members
Read · List a community's members
Exact permission: `communities.members`. Underlying role scope: `users:read`.
### communities.ofPerson
Read · List the communities a person belongs to
Exact permission: `communities.ofPerson`. Underlying role scope: `users:read`.
### communities.archive
Write · Archive a community
Exact permission: `communities.archive`. Underlying role scope: `profile:write`.
### communities.createSlackChannel
Write · Create an explicitly public or private Slack channel as an authorized community owner or administrator, retaining its request id across retries
Exact permission: `communities.createSlackChannel`. Underlying role scope: `programs:write`.
### communities.fromChannels
Write · Create one community per chosen Slack channel, as an administrator
Exact permission: `communities.fromChannels`. Underlying role scope: `programs:write`.
### communities.generateCover
Write · Draw an AI cover for a community, as its owner, moderator or an administrator. Keeps a cover already set unless replace is true; idea says what to draw
Exact permission: `communities.generateCover`. Underlying role scope: `profile:write`.
### communities.invite
Write · Invite selected people to a community as its owner or administrator; each person must accept
Exact permission: `communities.invite`. Underlying role scope: `profile:write`.
### communities.join
Write · Join a community
Exact permission: `communities.join`. Underlying role scope: `profile:write`.
### communities.leave
Write · Leave a community
Exact permission: `communities.leave`. Underlying role scope: `profile:write`.
### communities.removeMember
Write · Remove someone from a community, as its owner or moderator
Exact permission: `communities.removeMember`. Underlying role scope: `profile:write`.
### communities.revokeInvitation
Write · Revoke a pending community invitation as its owner or administrator
Exact permission: `communities.revokeInvitation`. Underlying role scope: `profile:write`.
### communities.save
Write · Create or edit a community, optionally tied to a Slack channel
Exact permission: `communities.save`. Underlying role scope: `profile:write`.
### communities.setVisibility
Write · Show or hide a community on your profile
Exact permission: `communities.setVisibility`. Underlying role scope: `profile:write`.
### communities.sync
Write · Sync a community's members with its Slack channel now
Exact permission: `communities.sync`. Underlying role scope: `profile:write`.
### communities.uploadCover
Write · Set a community cover from a PNG, JPEG or WebP picture sent as base64, as its owner, moderator or an administrator
Exact permission: `communities.uploadCover`. Underlying role scope: `profile:write`.
## credentials.api
### credentials.api.list
Read · List the workspace's API keys and what each can do
Exact permission: `credentials.api.list`. Underlying role scope: `credentials:read`.
### credentials.api.create
Write · Delegate a subset of this credential with bounded expiry and inherited revocation
Exact permission: `credentials.api.create`. Underlying role scope: `credentials:write`.
### credentials.api.revoke
Write · Revoke an API key
Exact permission: `credentials.api.revoke`. Underlying role scope: `credentials:write`.
## digest
### digest.culture
Read · List the Culture page’s recommendations in order and what happened after each one acted on
Exact permission: `digest.culture`. Underlying role scope: `reports:read`.
### digest.nudge
Read · Read one of Mello’s culture nudges
Exact permission: `digest.nudge`. Underlying role scope: `reports:read`.
### digest.nudges
Read · List Mello’s culture nudges for the workspace
Exact permission: `digest.nudges`. Underlying role scope: `reports:read`.
### digest.preview
Read · Preview the HR digest for the last period
Exact permission: `digest.preview`. Underlying role scope: `reports:read`.
### digest.settings
Read · Read the HR digest schedule
Exact permission: `digest.settings`. Underlying role scope: `team:read`.
### digest.actOnNudge
Write · Record that a culture nudge was acted on and get where its action goes
Exact permission: `digest.actOnNudge`. Underlying role scope: `team:write`.
### digest.dismissNudge
Write · Dismiss a culture nudge for 90 days
Exact permission: `digest.dismissNudge`. Underlying role scope: `team:write`.
### digest.saveSettings
Write · Save the HR digest schedule and admin channel
Exact permission: `digest.saveSettings`. Underlying role scope: `team:write`.
## exports
### exports.team
Read · Export the workspace's programs, people and introduction history
Exact permission: `exports.team`. Underlying role scope: `exports:read`.
## getStarted
### getStarted.celebration
Read · Read the first-action celebration waiting for you, if any
Exact permission: `getStarted.celebration`. Underlying role scope: `self:read`.
### getStarted.get
Read · Read your own Get started steps and whether the welcome still shows
Exact permission: `getStarted.get`. Underlying role scope: `self:read`.
### getStarted.celebrate
Write · Record that a celebration was shown, shared or dismissed
Exact permission: `getStarted.celebrate`. Underlying role scope: `profile:write`.
### getStarted.dismiss
Write · Hide the Get started card
Exact permission: `getStarted.dismiss`. Underlying role scope: `profile:write`.
### getStarted.draftIntro
Write · Draft a short hello to your coworkers with Mello; nothing is posted
Exact permission: `getStarted.draftIntro`. Underlying role scope: `profile:write`.
### getStarted.intro
Write · Post your hello on Home, or skip it
Exact permission: `getStarted.intro`. Underlying role scope: `profile:write`.
### getStarted.wizard
Write · Record that you opened, finished or skipped the welcome
Exact permission: `getStarted.wizard`. Underlying role scope: `profile:write`.
## groups
### groups.allAutomations
Read · Every join and leave automation in the workspace: group automations with their group and last runs, playbooks that start on each start date or each last day (`dayZero`) and Connections programs whose people are a group; or only those that start one playbook, program or community
Exact permission: `groups.allAutomations`. Underlying role scope: `users:read`.
### groups.automationChoices
Read · The Pulse questions, badges and Shuffl lists a group automation can ask, give or add people to
Exact permission: `groups.automationChoices`. Underlying role scope: `users:read`.
### groups.automationInsights
Read · Group automation runs over the last `days` (30, 90 or 180) against the period before: done, skipped and failed, people reached, by week and kind, the top reasons a run did nothing, runs still scheduled and automations on; `groupId` narrows it
Exact permission: `groups.automationInsights`. Underlying role scope: `users:read`.
### groups.automationRuns
Read · Every group automation run in the workspace, newest first, 50 at a time (`next` is the cursor for the page after), with `counts` by outcome; `outcome` and `groupId` narrow it
Exact permission: `groups.automationRuns`. Underlying role scope: `users:read`.
### groups.automations
Read · A group’s automations (what happens when someone joins or leaves) and their last runs
Exact permission: `groups.automations`. Underlying role scope: `users:read`.
### groups.directory
Read · List the groups shown on profiles, yours first, with a few faces each
Exact permission: `groups.directory`. Underlying role scope: `users:read`.
### groups.directoryGroup
Read · Read one group shown on profiles and everyone in it
Exact permission: `groups.directoryGroup`. Underlying role scope: `users:read`.
### groups.export
Read · A group’s members as a CSV file: name, email, title, department, manager and when they joined
Exact permission: `groups.export`. Underlying role scope: `users:read`.
### groups.get
Read · Read one group: its rules, members and recent entries and exits
Exact permission: `groups.get`. Underlying role scope: `users:read`.
### groups.glance
Read · One group at a glance: size, joins, departments, tenure and time zones
Exact permission: `groups.glance`. Underlying role scope: `users:read`.
### groups.list
Read · List the workspace’s groups with who is in each
Exact permission: `groups.list`. Underlying role scope: `users:read`.
### groups.members
Read · One page of a group’s members
Exact permission: `groups.members`. Underlying role scope: `users:read`.
### groups.message
Read · One message to a group: its words, who it would reach now and how it reads to one member
Exact permission: `groups.message`. Underlying role scope: `users:read`.
### groups.messages
Read · The drafts and sends of messages to a group, newest first
Exact permission: `groups.messages`. Underlying role scope: `users:read`.
### groups.options
Read · The departments, teams, communities, programs, titles, locations and time zones a rule may name
Exact permission: `groups.options`. Underlying role scope: `users:read`.
### groups.preview
Read · Count and sample who a set of rules would hold today
Exact permission: `groups.preview`. Underlying role scope: `users:read`.
### groups.searchPeople
Read · Find people by name to pick for a group
Exact permission: `groups.searchPeople`. Underlying role scope: `users:read`.
### groups.suggestions
Read · Starter groups not made yet, with how many people each would hold
Exact permission: `groups.suggestions`. Underlying role scope: `users:read`.
### groups.discardMessage
Write · Drop a drafted message to a group
Exact permission: `groups.discardMessage`. Underlying role scope: `users:write`.
### groups.prepareMessage
Write · Write a message to everyone in a group and see who it would reach; nothing is sent
Exact permission: `groups.prepareMessage`. Underlying role scope: `users:write`.
### groups.refresh
Write · Re-evaluate a dynamic group’s rules now
Exact permission: `groups.refresh`. Underlying role scope: `users:write`.
### groups.remove
Write · Remove a group
Exact permission: `groups.remove`. Underlying role scope: `users:write`.
### groups.removeAutomation
Write · Remove an automation from a group, with its runs
Exact permission: `groups.removeAutomation`. Underlying role scope: `users:write`.
### groups.save
Write · Create or change a group or a department: a list of people or rules that keep it up to date
Exact permission: `groups.save`. Underlying role scope: `users:write`.
### groups.sendMessage
Write · Send a drafted message to a group once per request key, on each person’s chosen channel
Exact permission: `groups.sendMessage`. Underlying role scope: `users:write`.
### groups.setAutomation
Write · Add or change an automation on a group: send a message, ask a Pulse question, start a playbook, invite to a community, add to Connections, give a badge, add to or remove from another group, add to or post in a Slack channel (`config.channelId`, read back from Slack), or tell HR, their manager or someone named, right away or days later; a new one starts paused
Exact permission: `groups.setAutomation`. Underlying role scope: `users:write`.
### groups.setAutomationState
Write · Pause or resume an automation on a group
Exact permission: `groups.setAutomationState`. Underlying role scope: `users:write`.
### groups.setPlaybookAutoStart
Write · Turn on, pause or remove a playbook’s automation that starts it on each new hire’s start date, or a leaving playbook’s on each last day, for everyone or one group
Exact permission: `groups.setPlaybookAutoStart`. Underlying role scope: `users:write`.
## home
### home.feed
Read · What happened to people you know, and who Mello thinks you should meet
Exact permission: `home.feed`. Underlying role scope: `self:read`.
### home.places
Read · The areas turned on for you, what is waiting for you, and your onboarding progress
Exact permission: `home.places`. Underlying role scope: `self:read`.
### home.preferences
Write · Choose how Home looks: cards or compact, stories, autoplay, For you
Exact permission: `home.preferences`. Underlying role scope: `profile:write`.
### home.react
Write · Add or remove your emoji reaction on a Home moment
Exact permission: `home.react`. Underlying role scope: `profile:write`.
### home.story
Write · Record Home stories you opened, sent a note from, or skipped
Exact permission: `home.story`. Underlying role scope: `profile:write`.
## hr
### hr.categories
Read · Read the HR request categories and response target
Exact permission: `hr.categories`. Underlying role scope: `hr:read`.
### hr.get
Read · Read one HR request and its messages
Exact permission: `hr.get`. Underlying role scope: `hr:read`.
### hr.list
Read · List the HR requests you asked or can answer
Exact permission: `hr.list`. Underlying role scope: `hr:read`.
### hr.mine
Read · List the HR requests you asked, with HR’s latest reply
Exact permission: `hr.mine`. Underlying role scope: `hr:read`.
### hr.readiness
Read · Check whether HR requests have a destination and someone to answer them
Exact permission: `hr.readiness`. Underlying role scope: `hr:read`.
### hr.settings
Read · Read the HR team name and who answers HR requests
Exact permission: `hr.settings`. Underlying role scope: `hr:read`.
### hr.shareSources
Read · List your recent Mello conversations that an HR request can include
Exact permission: `hr.shareSources`. Underlying role scope: `hr:read`.
### hr.command
Write · Claim, release, reply to, note, categorize, resolve or reopen an HR request
Exact permission: `hr.command`. Underlying role scope: `hr:write`.
### hr.configure
Write · Change the HR request destination
Exact permission: `hr.configure`. Underlying role scope: `hr:write`.
### hr.deliver
Write · Deliver your HR reply to the employee
Exact permission: `hr.deliver`. Underlying role scope: `hr:write`.
### hr.rebuildCategories
Write · Have Mello rebuild the HR request categories from published Knowledge
Exact permission: `hr.rebuildCategories`. Underlying role scope: `hr:write`.
### hr.renameTeam
Write · Rename the HR team employees send requests to
Exact permission: `hr.renameTeam`. Underlying role scope: `hr:write`.
### hr.retryDelivery
Write · Retry HR request delivery
Exact permission: `hr.retryDelivery`. Underlying role scope: `hr:write`.
### hr.saveCategories
Write · Save the HR request categories, their owners and the response target
Exact permission: `hr.saveCategories`. Underlying role scope: `hr:write`.
### hr.share
Write · Share this request with the selected HR responders
Exact permission: `hr.share`. Underlying role scope: `hr:write`.
## identities
### identities.list
Read · List the Slack and web accounts linked to a person
Exact permission: `identities.list`. Underlying role scope: `identities:read`.
### identities.slackAccounts
Read · List Slack accounts that can be linked to people
Exact permission: `identities.slackAccounts`. Underlying role scope: `identities:read`.
### identities.webAccounts
Read · List web accounts that can be linked to people
Exact permission: `identities.webAccounts`. Underlying role scope: `identities:read`.
### identities.linkSlack
Write · Link a verified Slack account
Exact permission: `identities.linkSlack`. Underlying role scope: `identities:write`.
### identities.linkWeb
Write · Link a verified web account
Exact permission: `identities.linkWeb`. Underlying role scope: `identities:write`.
### identities.unlink
Write · Revoke an employee identity link
Exact permission: `identities.unlink`. Underlying role scope: `identities:write`.
## integrations
### integrations.authorize
Read · Get the link that connects Slack, Google Drive or Notion to the workspace
Exact permission: `integrations.authorize`. Underlying role scope: `integrations:write`.
## invitations
### invitations.candidates
Read · List people in the directory who can be invited to the workspace
Exact permission: `invitations.candidates`. Underlying role scope: `access:read`.
### invitations.list
Read · List pending workspace invitations
Exact permission: `invitations.list`. Underlying role scope: `access:read`.
### invitations.cancel
Write · Cancel a pending workspace invitation
Exact permission: `invitations.cancel`. Underlying role scope: `access:write`.
### invitations.create
Write · Invite this person with the selected team role
Exact permission: `invitations.create`. Underlying role scope: `access:write`.
### invitations.createMany
Write · Invite these people with the selected team role
Exact permission: `invitations.createMany`. Underlying role scope: `access:write`.
### invitations.inviteDirectory
Write · Invite everyone in the directory who is not invited yet
Exact permission: `invitations.inviteDirectory`. Underlying role scope: `access:write`.
## knowledge
### knowledge.context
Read · Read nearby approved passages
Exact permission: `knowledge.context`. Underlying role scope: `knowledge:read`.
### knowledge.search
Read · Search approved knowledge
Exact permission: `knowledge.search`. Underlying role scope: `knowledge:read`.
## knowledge.acknowledgements
### knowledge.acknowledgements.mine
Read · List the Knowledge pages you are asked to read and confirm
Exact permission: `knowledge.acknowledgements.mine`. Underlying role scope: `knowledge:read`.
### knowledge.acknowledgements.status
Read · See who has confirmed a Knowledge page and who has not
Exact permission: `knowledge.acknowledgements.status`. Underlying role scope: `knowledge:manage`.
### knowledge.acknowledgements.close
Write · Stop asking people to confirm this page
Exact permission: `knowledge.acknowledgements.close`. Underlying role scope: `knowledge:write`.
### knowledge.acknowledgements.remind
Write · Message the people who have not confirmed this page yet
Exact permission: `knowledge.acknowledgements.remind`. Underlying role scope: `knowledge:write`.
### knowledge.acknowledgements.request
Write · Ask the people who can read this page to confirm they read it, and message them
Exact permission: `knowledge.acknowledgements.request`. Underlying role scope: `knowledge:write`.
## knowledge.connections
### knowledge.connections.browse
Read · List documents a connected Knowledge source can see
Exact permission: `knowledge.connections.browse`. Underlying role scope: `integrations:read`.
### knowledge.connections.list
Read · List connected Knowledge providers
Exact permission: `knowledge.connections.list`. Underlying role scope: `integrations:read`.
### knowledge.connections.requests
Read · List requests to connect a Knowledge source
Exact permission: `knowledge.connections.requests`. Underlying role scope: `integrations:read`.
### knowledge.connections.connect
Write · Connect a Knowledge provider with a token
Exact permission: `knowledge.connections.connect`. Underlying role scope: `integrations:write`.
### knowledge.connections.disconnect
Write · Disconnect a knowledge provider
Exact permission: `knowledge.connections.disconnect`. Underlying role scope: `integrations:write`.
### knowledge.connections.request
Write · Ask an administrator to connect a Knowledge source
Exact permission: `knowledge.connections.request`. Underlying role scope: `integrations:write`.
## knowledge.handbook
### knowledge.handbook.export
Read · Download the pages published to everyone as one handbook, in Markdown
Exact permission: `knowledge.handbook.export`. Underlying role scope: `knowledge:manage`.
## knowledge.policies
### knowledge.policies.coverage
Read · Check which common HR policies Knowledge covers
Exact permission: `knowledge.policies.coverage`. Underlying role scope: `knowledge:manage`.
## knowledge.sources
### knowledge.sources.get
Read · Read a Knowledge source
Exact permission: `knowledge.sources.get`. Underlying role scope: `knowledge:manage`.
### knowledge.sources.history
Read · List a Knowledge source's versions
Exact permission: `knowledge.sources.history`. Underlying role scope: `knowledge:manage`.
### knowledge.sources.list
Read · List Knowledge sources
Exact permission: `knowledge.sources.list`. Underlying role scope: `knowledge:manage`.
### knowledge.sources.search
Read · Search Knowledge sources by title
Exact permission: `knowledge.sources.search`. Underlying role scope: `knowledge:read`.
### knowledge.sources.archive
Write · Archive an unpublished knowledge source
Exact permission: `knowledge.sources.archive`. Underlying role scope: `knowledge:write`.
### knowledge.sources.changeAudience
Write · Change who can read this knowledge source
Exact permission: `knowledge.sources.changeAudience`. Underlying role scope: `knowledge:write`.
### knowledge.sources.importConnected
Write · Import a document from a connected Knowledge source
Exact permission: `knowledge.sources.importConnected`. Underlying role scope: `knowledge:write`.
### knowledge.sources.importWebsite
Write · Import a website page into Knowledge for review
Exact permission: `knowledge.sources.importWebsite`. Underlying role scope: `knowledge:write`.
### knowledge.sources.publish
Write · Publish this knowledge version to its audience
Exact permission: `knowledge.sources.publish`. Underlying role scope: `knowledge:write`.
### knowledge.sources.refresh
Write · Refresh a Knowledge source from its connected provider
Exact permission: `knowledge.sources.refresh`. Underlying role scope: `knowledge:write`.
### knowledge.sources.restore
Write · Restore an archived knowledge source
Exact permission: `knowledge.sources.restore`. Underlying role scope: `knowledge:write`.
### knowledge.sources.save
Write · Save a Knowledge source draft
Exact permission: `knowledge.sources.save`. Underlying role scope: `knowledge:write`.
### knowledge.sources.withdraw
Write · Withdraw a published Knowledge source
Exact permission: `knowledge.sources.withdraw`. Underlying role scope: `knowledge:write`.
### knowledge.sources.write
Write · Write a Knowledge page with Mello from its title and a request; nothing is saved
Exact permission: `knowledge.sources.write`. Underlying role scope: `knowledge:write`.
## knowledge.templates
### knowledge.templates.facts
Read · Read what Shuffl knows that policy templates ask for
Exact permission: `knowledge.templates.facts`. Underlying role scope: `knowledge:manage`.
### knowledge.templates.draft
Write · Draft a policy template with Mello, researching each value; nothing is saved
Exact permission: `knowledge.templates.draft`. Underlying role scope: `knowledge:write`.
## knowledge.uploads
### knowledge.uploads.get
Read · Read the progress of a Knowledge file upload
Exact permission: `knowledge.uploads.get`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.appendPart
Write · Upload the next part of a Knowledge file
Exact permission: `knowledge.uploads.appendPart`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.complete
Write · Finish a Knowledge file upload and start reading it
Exact permission: `knowledge.uploads.complete`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.create
Write · Start uploading a file to Knowledge
Exact permission: `knowledge.uploads.create`. Underlying role scope: `knowledge:write`.
### knowledge.uploads.retry
Write · Retry reading a Knowledge file that failed
Exact permission: `knowledge.uploads.retry`. Underlying role scope: `knowledge:write`.
## manager
### manager.current
Read · Read your own manager context
Exact permission: `manager.current`. Underlying role scope: `manager:read`.
## mcp
### mcp.knowledge
Read · Connect an agent over MCP
Exact permission: `mcp.knowledge`. Underlying role scope: `knowledge:read`.
## mentorship
### mentorship.mine
Read · Your mentorship programs and pairings, with goals and check-ins
Exact permission: `mentorship.mine`. Underlying role scope: `self:read`.
### mentorship.join
Write · Join a mentorship program as a mentor or mentee, saying what you can help with or want to learn
Exact permission: `mentorship.join`. Underlying role scope: `self:write`.
### mentorship.leave
Write · Leave a mentorship program as a mentor or mentee
Exact permission: `mentorship.leave`. Underlying role scope: `self:write`.
## mentorship.checkIns
### mentorship.checkIns.answer
Write · Answer whether you met your mentor or mentee, and whether it helped
Exact permission: `mentorship.checkIns.answer`. Underlying role scope: `self:write`.
## mentorship.goals
### mentorship.goals.remove
Write · Remove a goal from your mentorship, as the mentee
Exact permission: `mentorship.goals.remove`. Underlying role scope: `self:write`.
### mentorship.goals.save
Write · Add, rename or check off a goal in your mentorship, as the mentee
Exact permission: `mentorship.goals.save`. Underlying role scope: `self:write`.
## mentorship.members
### mentorship.members.setStatus
Write · Take someone off a mentorship program, or put them back
Exact permission: `mentorship.members.setStatus`. Underlying role scope: `mentorship:write`.
## mentorship.mentors
### mentorship.mentors.choose
Write · Choose your mentor from the mentors Shuffl suggests, in a program where mentees choose
Exact permission: `mentorship.mentors.choose`. Underlying role scope: `self:write`.
## mentorship.pairs
### mentorship.pairs.decide
Write · Approve a suggested mentorship pair, which introduces them, or skip it
Exact permission: `mentorship.pairs.decide`. Underlying role scope: `mentorship:write`.
### mentorship.pairs.end
Write · End a mentorship pairing early
Exact permission: `mentorship.pairs.end`. Underlying role scope: `mentorship:write`.
### mentorship.pairs.setMine
Write · Pause, resume or end your own mentorship pairing
Exact permission: `mentorship.pairs.setMine`. Underlying role scope: `self:write`.
### mentorship.pairs.suggest
Write · Suggest a mentor outside their reporting line for every mentee still waiting
Exact permission: `mentorship.pairs.suggest`. Underlying role scope: `mentorship:write`.
## mentorship.programs
### mentorship.programs.get
Read · One mentorship program: who joined, the suggested pairs and whether pairs are meeting
Exact permission: `mentorship.programs.get`. Underlying role scope: `mentorship:read`.
### mentorship.programs.list
Read · List mentorship programs, with how many mentors, mentees and pairs each has
Exact permission: `mentorship.programs.list`. Underlying role scope: `mentorship:read`.
### mentorship.programs.save
Write · Create or change a mentorship program: who can join, how long pairings last and how often pairs check in
Exact permission: `mentorship.programs.save`. Underlying role scope: `mentorship:write`.
### mentorship.programs.setStatus
Write · Turn mentorship programs on, pause one, or archive one and end its pairs
Exact permission: `mentorship.programs.setStatus`. Underlying role scope: `mentorship:write`.
## mentorship.requests
### mentorship.requests.answer
Write · Accept or pass on a mentee who chose you as their mentor
Exact permission: `mentorship.requests.answer`. Underlying role scope: `self:write`.
## mentorship.sessions
### mentorship.sessions.remove
Write · Remove your notes from a mentorship meeting
Exact permission: `mentorship.sessions.remove`. Underlying role scope: `self:write`.
### mentorship.sessions.save
Write · Add or change your notes from a mentorship meeting: what you talked about and one thing to try
Exact permission: `mentorship.sessions.save`. Underlying role scope: `self:write`.
## mentorship.settings
### mentorship.settings.get
Read · What a new mentorship program starts with: pairing length, check-in cadence and mentees per mentor
Exact permission: `mentorship.settings.get`. Underlying role scope: `mentorship:read`.
### mentorship.settings.save
Write · Change what a new mentorship program starts with; existing programs keep their own terms
Exact permission: `mentorship.settings.save`. Underlying role scope: `mentorship:write`.
## network
### network.introductions
Read · Your Connections programs, when your next introduction goes out, and who you met
Exact permission: `network.introductions`. Underlying role scope: `users:read`.
### network.mine
Read · Who you know and who you should meet
Exact permission: `network.mine`. Underlying role scope: `users:read`.
### network.ofPerson
Read · People you and this person both know
Exact permission: `network.ofPerson`. Underlying role scope: `users:read`.
### network.orgChart
Read · Everyone in the team with their manager, for the org chart
Exact permission: `network.orgChart`. Underlying role scope: `users:read`.
### network.claim
Write · Say you know someone or would like to meet them
Exact permission: `network.claim`. Underlying role scope: `profile:write`.
### network.requestIntro
Write · Ask someone you both know to introduce you
Exact permission: `network.requestIntro`. Underlying role scope: `profile:write`.
## notifications
### notifications.preferences
Read · Read your notification preferences
Exact permission: `notifications.preferences`. Underlying role scope: `self:read`.
### notifications.save
Write · Save a notification preference
Exact permission: `notifications.save`. Underlying role scope: `self:write`.
## operations
### operations.activity
Read · Read the workspace's recent audit activity
Exact permission: `operations.activity`. Underlying role scope: `operations:read`.
### operations.status
Read · Read the workspace delivery and provider health summary
Exact permission: `operations.status`. Underlying role scope: `operations:read`.
### operations.dispatchInbox
Write · Resume already-admitted team provider events and support delivery
Exact permission: `operations.dispatchInbox`. Underlying role scope: `operations:write`.
### operations.reconcile
Write · Reconcile an externally verified delivery outcome
Exact permission: `operations.reconcile`. Underlying role scope: `operator:write`.
## permissions
### permissions.list
Read · Discover available and granted permissions
Intrinsic metadata permission; current authorization still applies.
## playbooks
### playbooks.buddyCandidates
Read · Suggested buddies for a new hire: outside their reporting line, volunteers first, with how many hires each is buddying
Exact permission: `playbooks.buddyCandidates`. Underlying role scope: `playbooks:read`.
### playbooks.buddyFollowUps
Read · Your "did you meet?" questions about a new hire or buddy you were paired with
Exact permission: `playbooks.buddyFollowUps`. Underlying role scope: `self:read`.
### playbooks.buddyProgram
Read · Buddy volunteers and recent buddies, with how many of their hires said they met and how many never did
Exact permission: `playbooks.buddyProgram`. Underlying role scope: `playbooks:read`.
### playbooks.buddySuggestions
Read · Suggest coworkers who could be your onboarding buddy
Exact permission: `playbooks.buddySuggestions`. Underlying role scope: `self:read`.
### playbooks.candidates
Read · List people who could be enrolled in onboarding
Exact permission: `playbooks.candidates`. Underlying role scope: `playbooks:read`.
### playbooks.enrollmentPreview
Read · Preview enrolling a new hire in onboarding
Exact permission: `playbooks.enrollmentPreview`. Underlying role scope: `playbooks:read`.
### playbooks.firstDaysCheckIns
Read · Your open 30, 60 or 90-day or one-year new hire check-in
Exact permission: `playbooks.firstDaysCheckIns`. Underlying role scope: `self:read`.
### playbooks.firstDaysResults
Read · What new hires said in their first 90 days check-ins, combined
Exact permission: `playbooks.firstDaysResults`. Underlying role scope: `playbooks:read`.
### playbooks.mine
Read · Read your own onboarding plan and buddy asks
Exact permission: `playbooks.mine`. Underlying role scope: `self:read`.
### playbooks.person
Read · Read a new hire's onboarding plan
Exact permission: `playbooks.person`. Underlying role scope: `playbooks:read`.
### playbooks.plans
Read · The 30/60/90 plans for new hires you manage, and your own once your manager shares it
Exact permission: `playbooks.plans`. Underlying role scope: `self:read`.
### playbooks.previewAs
Read · Which steps of a playbook one person would get, on which day, and why each skipped step is left out
Exact permission: `playbooks.previewAs`. Underlying role scope: `playbooks:read`.
### playbooks.program
Read · Read the Onboarding program settings
Exact permission: `playbooks.program`. Underlying role scope: `playbooks:read`.
### playbooks.run
Read · One of your playbooks (onboarding or another): day 0, buddy, manager, upcoming check-ins, your to-dos and resources, and the other playbooks you are on
Exact permission: `playbooks.run`. Underlying role scope: `self:read`.
### playbooks.answerBuddyAsk
Write · Say yes or not now to being a new hire’s onboarding buddy
Exact permission: `playbooks.answerBuddyAsk`. Underlying role scope: `self:write`.
### playbooks.answerBuddyFollowUp
Write · Answer whether you met your buddy or new hire, and whether it helped
Exact permission: `playbooks.answerBuddyFollowUp`. Underlying role scope: `self:write`.
### playbooks.answerCheckIn
Write · Answer your onboarding program’s help check-in: all good, or ask HR for help
Exact permission: `playbooks.answerCheckIn`. Underlying role scope: `self:write`.
### playbooks.answerFirstDaysCheckIn
Write · Answer your new-hire check-in
Exact permission: `playbooks.answerFirstDaysCheckIn`. Underlying role scope: `self:write`.
### playbooks.answerForm
Write · Answer a playbook’s Tell us about you form; the answers fill in your profile
Exact permission: `playbooks.answerForm`. Underlying role scope: `self:write`.
### playbooks.approve
Write · Approve these exact playbook messages for sending
Exact permission: `playbooks.approve`. Underlying role scope: `playbooks:write`.
### playbooks.askBuddy
Write · Ask this coworker to be your onboarding buddy
Exact permission: `playbooks.askBuddy`. Underlying role scope: `self:write`.
### playbooks.assignBuddy
Write · Assign an onboarding buddy to a new hire
Exact permission: `playbooks.assignBuddy`. Underlying role scope: `playbooks:write`.
### playbooks.completeTodo
Write · Check off (or reopen) one of your own playbook to-dos
Exact permission: `playbooks.completeTodo`. Underlying role scope: `self:write`.
### playbooks.draftPlan
Write · Have Mello draft the 30/60/90 plan for a new hire you manage (not yet shared)
Exact permission: `playbooks.draftPlan`. Underlying role scope: `self:write`.
### playbooks.enroll
Write · Put this person on a playbook
Exact permission: `playbooks.enroll`. Underlying role scope: `playbooks:write`.
### playbooks.nudge
Write · Send someone one Slack nudge about a hire’s overdue playbook to-dos, at most once a day
Exact permission: `playbooks.nudge`. Underlying role scope: `playbooks:write`.
### playbooks.previewEnrollment
Write · Preview the onboarding steps for a new hire
Exact permission: `playbooks.previewEnrollment`. Underlying role scope: `playbooks:write`.
### playbooks.remove
Write · Remove a new hire from onboarding
Exact permission: `playbooks.remove`. Underlying role scope: `playbooks:write`.
### playbooks.respondBuddy
Write · Accept or decline being an onboarding buddy
Exact permission: `playbooks.respondBuddy`. Underlying role scope: `self:write`.
### playbooks.retry
Write · Retry a failed onboarding step
Exact permission: `playbooks.retry`. Underlying role scope: `playbooks:write`.
### playbooks.savePlan
Write · Write the goals of the 30/60/90 plan for a new hire you manage
Exact permission: `playbooks.savePlan`. Underlying role scope: `self:write`.
### playbooks.saveProgram
Write · Save a playbook: its day 0, steps and messages
Exact permission: `playbooks.saveProgram`. Underlying role scope: `playbooks:write`.
### playbooks.setBuddyVolunteer
Write · Put someone on the buddy volunteer list, take them off it, or clear it
Exact permission: `playbooks.setBuddyVolunteer`. Underlying role scope: `playbooks:write`.
### playbooks.setPlanGoal
Write · Tick a goal on a shared 30/60/90 plan done, or not done
Exact permission: `playbooks.setPlanGoal`. Underlying role scope: `self:write`.
### playbooks.sharePlan
Write · Share the 30/60/90 plan with the new hire you manage
Exact permission: `playbooks.sharePlan`. Underlying role scope: `self:write`.
### playbooks.update
Write · Change a new hire's onboarding start date or time zone
Exact permission: `playbooks.update`. Underlying role scope: `playbooks:write`.
### playbooks.volunteerAsBuddy
Write · Say you are happy to be an onboarding buddy, or stop
Exact permission: `playbooks.volunteerAsBuddy`. Underlying role scope: `self:write`.
## praise
### praise.composer
Read · Read who you can praise, the praise channels and company values
Exact permission: `praise.composer`. Underlying role scope: `self:read`.
### praise.feed
Read · Read the Praise feed
Exact permission: `praise.feed`. Underlying role scope: `self:read`.
### praise.insights
Read · Read Praise totals by value (groups of seven or more)
Exact permission: `praise.insights`. Underlying role scope: `praise:read`.
### praise.mine
Read · Read praise you gave and received
Exact permission: `praise.mine`. Underlying role scope: `self:read`.
### praise.ofPerson
Read · Read the public praise one person received
Exact permission: `praise.ofPerson`. Underlying role scope: `self:read`.
### praise.settings
Read · Read the Praise settings
Exact permission: `praise.settings`. Underlying role scope: `praise:read`.
### praise.addChannel
Write · Read praise from this Slack channel from now on
Exact permission: `praise.addChannel`. Underlying role scope: `praise:write`.
### praise.removeChannel
Write · Stop reading praise from a Slack channel
Exact permission: `praise.removeChannel`. Underlying role scope: `praise:write`.
### praise.saveSettings
Write · Save the Praise settings and company values
Exact permission: `praise.saveSettings`. Underlying role scope: `praise:write`.
### praise.send
Write · Praise coworkers in a praise channel
Exact permission: `praise.send`. Underlying role scope: `self:write`.
### praise.setDigest
Write · Choose whether you get the daily Praise digest
Exact permission: `praise.setDigest`. Underlying role scope: `self:write`.
### praise.setHidden
Write · Hide or show a praise you received
Exact permission: `praise.setHidden`. Underlying role scope: `self:write`.
### praise.setRecognition
Write · Choose whether praise for you is posted publicly or sent to you privately
Exact permission: `praise.setRecognition`. Underlying role scope: `self:write`.
## profiles
### profiles.get
Read · Read a person’s profile as this team sees it
Exact permission: `profiles.get`. Underlying role scope: `users:read`.
### profiles.whoKnows
Read · Find coworkers who know about a topic, place or skill from what they share on their profiles, with the words that matched
Exact permission: `profiles.whoKnows`. Underlying role scope: `users:read`.
### profiles.draft
Write · Draft the empty parts of your own profile with Mello; nothing is saved
Exact permission: `profiles.draft`. Underlying role scope: `profile:write`.
### profiles.employeeNumber
Write · Set a person’s employee number to an unused number
Exact permission: `profiles.employeeNumber`. Underlying role scope: `users:write`.
### profiles.save
Write · Save your own profile: pronouns, location, phone, bio, interests, links and what you are working on
Exact permission: `profiles.save`. Underlying role scope: `profile:write`.
### profiles.settings
Write · Choose who sees the optional parts of your own profile
Exact permission: `profiles.settings`. Underlying role scope: `profile:write`.
## profiles.cover
### profiles.cover.delete
Write · Remove your profile cover picture
Exact permission: `profiles.cover.delete`. Underlying role scope: `profile:write`.
## profiles.photo
### profiles.photo.delete
Write · Remove your profile photo
Exact permission: `profiles.photo.delete`. Underlying role scope: `profile:write`.
## profiles.positions
### profiles.positions.delete
Write · Remove a past position from your profile
Exact permission: `profiles.positions.delete`. Underlying role scope: `profile:write`.
### profiles.positions.save
Write · Add or change a past position on your profile
Exact permission: `profiles.positions.save`. Underlying role scope: `profile:write`.
## programs
### programs.communities
Read · List communities a Connections program can take its people from, with how many members show each one on their profile
Exact permission: `programs.communities`. Underlying role scope: `programs:read`.
### programs.get
Read · Read a program
Exact permission: `programs.get`. Underlying role scope: `programs:read`.
### programs.list
Read · List programs
Exact permission: `programs.list`. Underlying role scope: `programs:read`.
### programs.options
Read · List program setting choices
Exact permission: `programs.options`. Underlying role scope: `programs:read`.
### programs.people
Read · List the people in a program and whether they take part
Exact permission: `programs.people`. Underlying role scope: `programs:read`.
### programs.preview
Read · Preview matches without sending
Exact permission: `programs.preview`. Underlying role scope: `programs:read`.
### programs.schedulePreview
Read · Preview a program's upcoming rounds
Exact permission: `programs.schedulePreview`. Underlying role scope: `programs:read`.
### programs.archive
Write · Archive a program
Exact permission: `programs.archive`. Underlying role scope: `programs:write`.
### programs.create
Write · Create a program
Exact permission: `programs.create`. Underlying role scope: `programs:write`.
### programs.joinChannel
Write · Add Shuffl to this public Slack channel
Exact permission: `programs.joinChannel`. Underlying role scope: `programs:write`.
### programs.pause
Write · Pause a Connections program and its introductions
Exact permission: `programs.pause`. Underlying role scope: `programs:write`.
### programs.resume
Write · Activate a program and schedule
Exact permission: `programs.resume`. Underlying role scope: `programs:write`.
### programs.syncRoster
Write · Refresh channel membership
Exact permission: `programs.syncRoster`. Underlying role scope: `programs:write`.
### programs.update
Write · Update a program
Exact permission: `programs.update`. Underlying role scope: `programs:write`.
## pulse
### pulse.actions
Read · List Pulse actions: what is being done about each result, its owner, due date and before and after
Exact permission: `pulse.actions`. Underlying role scope: `pulse:read`.
### pulse.asked
Read · List the Pulse questions asked so far
Exact permission: `pulse.asked`. Underlying role scope: `self:read`.
### pulse.groupTrends
Read · Read each group's Pulse results over time, period by period, with the change since the start (published group totals only)
Exact permission: `pulse.groupTrends`. Underlying role scope: `pulse:read`.
### pulse.insights
Read · Read Pulse totals and trends (groups of seven or more)
Exact permission: `pulse.insights`. Underlying role scope: `pulse:read`.
### pulse.latestRead
Read · Read what stands out in a closed Pulse question’s result
Exact permission: `pulse.latestRead`. Underlying role scope: `pulse:read`.
### pulse.mine
Read · Read your own Pulse streak, how many took part, and what changed because of it
Exact permission: `pulse.mine`. Underlying role scope: `self:read`.
### pulse.program
Read · Read the Pulse settings
Exact permission: `pulse.program`. Underlying role scope: `pulse:read`.
### pulse.proposals
Read · List the Pulse questions Mello suggested that wait for approval
Exact permission: `pulse.proposals`. Underlying role scope: `pulse:read`.
### pulse.questionDetail
Read · Read one closed Pulse question: its answer spread, every time it was asked, and results by group (groups of seven or more)
Exact permission: `pulse.questionDetail`. Underlying role scope: `pulse:read`.
### pulse.questions
Read · List the Pulse question library
Exact permission: `pulse.questions`. Underlying role scope: `pulse:read`.
### pulse.today
Read · Read today’s Pulse question
Exact permission: `pulse.today`. Underlying role scope: `self:read`.
### pulse.addQuestion
Write · Add a Pulse question to the library
Exact permission: `pulse.addQuestion`. Underlying role scope: `pulse:write`.
### pulse.addTemplate
Write · Add a Pulse question set from a template
Exact permission: `pulse.addTemplate`. Underlying role scope: `pulse:write`.
### pulse.answer
Write · Answer today’s Pulse question as yourself
Exact permission: `pulse.answer`. Underlying role scope: `self:write`.
### pulse.createAction
Write · Plan an action about a closed Pulse question, with an owner and a due date
Exact permission: `pulse.createAction`. Underlying role scope: `pulse:write`.
### pulse.decideProposal
Write · Approve a suggested Pulse question so it is asked next, or dismiss it
Exact permission: `pulse.decideProposal`. Underlying role scope: `pulse:write`.
### pulse.editProposal
Write · Reword a suggested Pulse question before approving it
Exact permission: `pulse.editProposal`. Underlying role scope: `pulse:write`.
### pulse.proposeQuestions
Write · Save drafted Pulse questions as suggestions for HR to approve (never asked until approved)
Exact permission: `pulse.proposeQuestions`. Underlying role scope: `pulse:write`.
### pulse.requestProposals
Write · Ask Mello to suggest Pulse questions from recent results, optionally about a topic
Exact permission: `pulse.requestProposals`. Underlying role scope: `pulse:write`.
### pulse.saveProgram
Write · Save Pulse settings; enabling Pulse schedules questions to everyone
Exact permission: `pulse.saveProgram`. Underlying role scope: `pulse:write`.
### pulse.setQuestionGroup
Write · Aim a Pulse question at one of the workspace’s groups, or at everyone
Exact permission: `pulse.setQuestionGroup`. Underlying role scope: `pulse:write`.
### pulse.setQuestionStatus
Write · Retire or restore a Pulse question
Exact permission: `pulse.setQuestionStatus`. Underlying role scope: `pulse:write`.
### pulse.skip
Write · Skip today’s Pulse question
Exact permission: `pulse.skip`. Underlying role scope: `self:write`.
### pulse.updateAction
Write · Change a Pulse action’s wording, owner, due date or status
Exact permission: `pulse.updateAction`. Underlying role scope: `pulse:write`.
## reminders
### reminders.mine
Read · Read your own Praise and Pulse reminder choices
Exact permission: `reminders.mine`. Underlying role scope: `self:read`.
### reminders.settings
Read · Read whether Praise and Pulse reminders are on, and their timing
Exact permission: `reminders.settings`. Underlying role scope: `team:read`.
### reminders.saveMine
Write · Change or turn off your own Praise or Pulse reminders
Exact permission: `reminders.saveMine`. Underlying role scope: `self:write`.
### reminders.saveSetting
Write · Turn a Praise or Pulse reminder on or off, or change its timing
Exact permission: `reminders.saveSetting`. Underlying role scope: `team:write`.
## reports
### reports.answerFeedback
Read · Read feedback on Mello's answers
Exact permission: `reports.answerFeedback`. Underlying role scope: `reports:read`.
### reports.celebrations
Read · Celebrations sent, people celebrated, birthdays and anniversaries, shared with the team, team cards and notes, share answers and missed messages over 30, 90 or 180 days against the period before, with a weekly series
Exact permission: `reports.celebrations`. Underlying role scope: `reports:read`.
### reports.connections
Read · Read Connections insights
Exact permission: `reports.connections`. Underlying role scope: `reports:read`.
### reports.knowledge
Read · Read Knowledge activity
Exact permission: `reports.knowledge`. Underlying role scope: `reports:read`.
### reports.knowledgeSource
Read · Read activity for one Knowledge source
Exact permission: `reports.knowledgeSource`. Underlying role scope: `reports:read`.
### reports.melloTrial
Read · What Mello handled during the trial, from day 25 of a trial until it ends
Exact permission: `reports.melloTrial`. Underlying role scope: `reports:read`.
### reports.melloValue
Read · What Mello handled this week, this month and all time, with time saved once the team has set its minutes per question
Exact permission: `reports.melloValue`. Underlying role scope: `reports:read`.
### reports.mentorship
Read · Mentorship over 30, 90 or 180 days against the period before: pairs started, ended early and completed, check-ins answered and met, pairs meeting and mentees waiting now; `programId` narrows it. Never goals
Exact permission: `reports.mentorship`. Underlying role scope: `reports:read`.
### reports.needsYou
Read · Read HR request and Knowledge draft insights
Exact permission: `reports.needsYou`. Underlying role scope: `reports:read`.
### reports.overview
Read · Read the workspace overview figures
Exact permission: `reports.overview`. Underlying role scope: `reports:read`.
### reports.people
Read · Read People insights: headcount, teams and growth
Exact permission: `reports.people`. Underlying role scope: `reports:read`.
### reports.playbooks
Read · Read Onboarding insights
Exact permission: `reports.playbooks`. Underlying role scope: `reports:read`.
## runs
### runs.details
Read · Read one introduction round and its pairs
Exact permission: `runs.details`. Underlying role scope: `runs:read`.
### runs.get
Read · Read a run status
Exact permission: `runs.get`. Underlying role scope: `runs:read`.
### runs.list
Read · List a program's introduction rounds
Exact permission: `runs.list`. Underlying role scope: `runs:read`.
### runs.dispatch
Write · Dispatch this queued introduction run
Exact permission: `runs.dispatch`. Underlying role scope: `runs:write`.
### runs.request
Write · Request introductions from a preview
Exact permission: `runs.request`. Underlying role scope: `runs:write`.
### runs.retry
Write · Retry introduction delivery
Exact permission: `runs.retry`. Underlying role scope: `runs:write`.
### runs.stopKnownFailures
Write · Stop retrying known failed deliveries and advance the preserved monthly schedule
Exact permission: `runs.stopKnownFailures`. Underlying role scope: `runs:write`.
## runs.history
### runs.history.get
Read · Read one introduction round imported from the previous Shuffl
Exact permission: `runs.history.get`. Underlying role scope: `exports:read`.
### runs.history.list
Read · List introduction rounds imported from the previous Shuffl
Exact permission: `runs.history.list`. Underlying role scope: `exports:read`.
## support
### support.get
Read · Read one Shuffl support conversation
Exact permission: `support.get`. Underlying role scope: `support:read`.
### support.list
Read · List the workspace's support conversations with Shuffl
Exact permission: `support.list`. Underlying role scope: `support:read`.
### support.assign
Write · Assign a Shuffl support conversation
Exact permission: `support.assign`. Underlying role scope: `support:write`.
### support.close
Write · Close a Shuffl support conversation
Exact permission: `support.close`. Underlying role scope: `support:write`.
### support.create
Write · Start a support conversation with Shuffl
Exact permission: `support.create`. Underlying role scope: `support:write`.
### support.reply
Write · Reply in a Shuffl support conversation
Exact permission: `support.reply`. Underlying role scope: `support:write`.
## sync
### sync.current
Read · Read the People sync provider, its last sync and what it found
Exact permission: `sync.current`. Underlying role scope: `integrations:read`.
### sync.groups
Read · List this source’s groups and which ones come into Shuffl
Exact permission: `sync.groups`. Underlying role scope: `integrations:read`.
### sync.connect
Write · Connect a directory sync provider with the credential given
Exact permission: `sync.connect`. Underlying role scope: `integrations:write`.
### sync.disconnect
Write · Disconnect this directory sync provider
Exact permission: `sync.disconnect`. Underlying role scope: `integrations:write`.
### sync.request
Write · Ask for a People sync provider Shuffl does not support yet
Exact permission: `sync.request`. Underlying role scope: `integrations:write`.
### sync.run
Write · Sync People from the connected provider now
Exact permission: `sync.run`. Underlying role scope: `integrations:write`.
### sync.setGroup
Write · Change which of this source’s groups come into Shuffl
Exact permission: `sync.setGroup`. Underlying role scope: `integrations:write`.
### sync.setWrites
Write · Let Mello file requests in this source, or stop it
Exact permission: `sync.setWrites`. Underlying role scope: `integrations:write`.
## team
### team.launchPost
Read · Read the launch announcement for the workspace
Exact permission: `team.launchPost`. Underlying role scope: `team:read`.
### team.answerMinutes
Write · Set the team estimate of minutes per HR question, used for time saved
Exact permission: `team.answerMinutes`. Underlying role scope: `team:write`.
### team.dismissLaunchPost
Write · Dismiss the Tell your team what they can ask post on Today for everyone
Exact permission: `team.dismissLaunchPost`. Underlying role scope: `team:write`.
## teams
### teams.connectionPermissions
Read · List connections whose permissions are behind what Shuffl asks for
Exact permission: `teams.connectionPermissions`. Underlying role scope: `team:read`.
### teams.current
Read · Read this token’s team
Intrinsic metadata permission; current authorization still applies.
### teams.setup
Read · Read the workspace's setup checklist
Exact permission: `teams.setup`. Underlying role scope: `team:read`.
### teams.slackChannels
Read · List community channels in the connected Slack and what each would become
Exact permission: `teams.slackChannels`. Underlying role scope: `integrations:read`.
### teams.slackConnection
Read · Read whether the workspace's Slack is connected, and why not
Exact permission: `teams.slackConnection`. Underlying role scope: `integrations:read`.
### teams.slackJoinAccess
Read · Read whether Slack members can join Shuffl on their own
Exact permission: `teams.slackJoinAccess`. Underlying role scope: `team:read`.
### teams.slackProfileLink
Read · Read the Shuffl profile link setting for Slack profiles
Exact permission: `teams.slackProfileLink`. Underlying role scope: `team:read`.
### teams.discardPairHistory
Write · Remove this staged past-intros report
Exact permission: `teams.discardPairHistory`. Underlying role scope: `integrations:write`.
### teams.initialize
Write · Finish setting up a new workspace
Exact permission: `teams.initialize`. Underlying role scope: `team:write`.
### teams.moveSlackChannels
Write · Set up each channel in Shuffl: paused intros, praise and celebrations
Exact permission: `teams.moveSlackChannels`. Underlying role scope: `integrations:write`.
### teams.rename
Write · Rename the workspace
Exact permission: `teams.rename`. Underlying role scope: `team:write`.
### teams.resendSlackWelcome
Write · Send the Slack install welcome to your own Slack DM again
Exact permission: `teams.resendSlackWelcome`. Underlying role scope: `integrations:write`.
### teams.saveAgentSetup
Write · Choose the built-in assistant or an external agent for the workspace
Exact permission: `teams.saveAgentSetup`. Underlying role scope: `team:write`.
### teams.saveSlackJoinAccess
Write · Choose whether Slack members can join Shuffl on their own
Exact permission: `teams.saveSlackJoinAccess`. Underlying role scope: `team:write`.
### teams.saveSlackProfileLink
Write · Turn the Shuffl profile link on Slack profiles on or off
Exact permission: `teams.saveSlackProfileLink`. Underlying role scope: `team:write`.
### teams.status
Write · Pause or resume the whole workspace
Exact permission: `teams.status`. Underlying role scope: `team:write`.
### teams.syncSlackProfileLinks
Write · Write the Shuffl profile link to every Slack profile again
Exact permission: `teams.syncSlackProfileLinks`. Underlying role scope: `team:write`.
### teams.uploadPairHistory
Write · Stage this past-intros report for the switch; nothing changes until it is applied
Exact permission: `teams.uploadPairHistory`. Underlying role scope: `integrations:write`.
## timeOff
### timeOff.balances
Read · Read your own time-off balances from the connected HR system
Exact permission: `timeOff.balances`. Underlying role scope: `self:read`.
## units
### units.list
Read · List the departments in the People directory
Exact permission: `units.list`. Underlying role scope: `users:read`.
## users
### users.activity
Read · Read a person's recent activity in Shuffl
Exact permission: `users.activity`. Underlying role scope: `users:read`.
### users.blockedPairs
Read · List pairs of people who are never introduced
Exact permission: `users.blockedPairs`. Underlying role scope: `users:read`.
### users.details
Read · Read one person's People directory record
Exact permission: `users.details`. Underlying role scope: `users:read`.
### users.filterOptions
Read · List the teams, departments, managers and locations People can filter by
Exact permission: `users.filterOptions`. Underlying role scope: `users:read`.
### users.get
Read · Read a person
Exact permission: `users.get`. Underlying role scope: `users:read`.
### users.glance
Read · Headcount, growth, departments, tenure and time zones, and where you fit
Exact permission: `users.glance`. Underlying role scope: `users:read`.
### users.list
Read · List people
Exact permission: `users.list`. Underlying role scope: `users:read`.
### users.managerHistory
Read · Read a person's recorded manager history
Exact permission: `users.managerHistory`. Underlying role scope: `users:read`.
### users.managers
Read · List the managers in the People directory
Exact permission: `users.managers`. Underlying role scope: `users:read`.
### users.page
Read · List people in the People directory: search, or filter by team, department, manager, location, access or workspace role such as owner, admin or HR responder
Exact permission: `users.page`. Underlying role scope: `users:read`.
### users.participants
Read · List the people who take part in programs
Exact permission: `users.participants`. Underlying role scope: `users:read`.
### users.reportingLineProposal
Read · Read the reporting lines Mello proposed that wait for review
Exact permission: `users.reportingLineProposal`. Underlying role scope: `users:read`.
### users.assignManagers
Write · Set the manager of several people at once
Exact permission: `users.assignManagers`. Underlying role scope: `users:write`.
### users.blockPair
Write · Stop two people from being introduced to each other
Exact permission: `users.blockPair`. Underlying role scope: `users:write`.
### users.participation
Write · Opt a person in to or out of a program
Exact permission: `users.participation`. Underlying role scope: `participation:write`.
### users.profile
Write · Edit a person's profile as an administrator
Exact permission: `users.profile`. Underlying role scope: `profile:write`.
### users.proposeReportingLines
Write · Ask Mello to propose managers for people without one; nothing changes until reviewed
Exact permission: `users.proposeReportingLines`. Underlying role scope: `users:write`.
### users.reviewReportingLines
Write · Approve chosen proposed reporting lines and close the proposal
Exact permission: `users.reviewReportingLines`. Underlying role scope: `users:write`.
### users.save
Write · Change someone's People directory record as an administrator: name, job title, manager, team, department or start date
Exact permission: `users.save`. Underlying role scope: `users:write`.
## webhooks
### webhooks.catalog
Read · List the webhook event types and which ones this key can subscribe to
Exact permission: `webhooks.catalog`. Underlying role scope: `webhooks:read`.
### webhooks.get
Read · Read one webhook endpoint
Exact permission: `webhooks.get`. Underlying role scope: `webhooks:read`.
### webhooks.list
Read · List webhook endpoints, their status and delivery success over 24 hours
Exact permission: `webhooks.list`. Underlying role scope: `webhooks:read`.
### webhooks.create
Write · Add a webhook endpoint that receives the chosen events, and get its signing secret
Exact permission: `webhooks.create`. Underlying role scope: `webhooks:write`.
### webhooks.delete
Write · Delete a webhook endpoint and its delivery log
Exact permission: `webhooks.delete`. Underlying role scope: `webhooks:write`.
### webhooks.rotateSecret
Write · Roll a webhook endpoint’s signing secret, keeping the old one valid for a while
Exact permission: `webhooks.rotateSecret`. Underlying role scope: `webhooks:write`.
### webhooks.sendTest
Write · Send a webhook.test event to an endpoint now
Exact permission: `webhooks.sendTest`. Underlying role scope: `webhooks:write`.
### webhooks.update
Write · Change a webhook endpoint’s URL, description or events, or turn it on or off
Exact permission: `webhooks.update`. Underlying role scope: `webhooks:write`.
## webhooks.deliveries
### webhooks.deliveries.get
Read · Read one webhook delivery: the request body and every attempt’s answer
Exact permission: `webhooks.deliveries.get`. Underlying role scope: `webhooks:read`.
### webhooks.deliveries.list
Read · List an endpoint’s webhook deliveries, newest first
Exact permission: `webhooks.deliveries.list`. Underlying role scope: `webhooks:read`.
### webhooks.deliveries.replay
Write · Resend one webhook delivery with the same event id
Exact permission: `webhooks.deliveries.replay`. Underlying role scope: `webhooks:write`.
### webhooks.deliveries.replayFailed
Write · Resend every failed webhook delivery of an endpoint since a time
Exact permission: `webhooks.deliveries.replayFailed`. Underlying role scope: `webhooks:write`.
## Related guides
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
Agent documentation index: https://shuffl.ai/llms.txt
---
# REST API reference
> Every REST operation by area, with its permission, fields and examples, plus authentication, errors, rate limits and pagination.
Audience: Developers and integration builders
Kind: Reference
Canonical: https://shuffl.ai/docs/api-reference
## Authentication
The base URL is https://shuffl.ai/api/v1. Send a workspace API key in the Authorization header as a bearer token, over HTTPS, on every request.
A key belongs to one workspace and acts as the person who created it, with their current role. Each operation also needs its own permission on the key.
GET /api/v1/team and GET /api/v1/permissions work with any valid key, so start with them to check the key and see what it can do.
### Other credentials
- A company key (shuffl_company_), sent the same way, calls only the Company settings operations under /api/v1/company. A workspace key can’t call those.
- In the SDK, new Shuffl takes a company key and calls shuffl.company. In the CLI, use shuffl login --company or SHUFFL_COMPANY_KEY.
- MCP OAuth tokens work only with the MCP server.
HTTP:
```sh
curl https://shuffl.ai/api/v1/team \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Create a workspace key](https://shuffl.ai/docs/sdk#credentials)
- [Company keys](https://shuffl.ai/docs/api-permissions#company-keys)
- [Company settings API](https://shuffl.ai/docs/api-reference/company)
- [@shuffl/sdk on npm](https://www.npmjs.com/package/@shuffl/sdk)
- [@shuffl/cli on npm](https://www.npmjs.com/package/@shuffl/cli)
## Requests and responses
Most operations are POST requests with a JSON body under /api/v1/manage. A few reads are GET requests with query parameters, and a few program and run operations take an id in the path.
Each operation’s page shows its method, path and fields. Responses are JSON and never cached.
Call the API from a server, a script or the CLI. Cross-origin browser requests aren’t allowed.
### Writes
- Writes take a requestKey and return {receipt, result}.
- Send a new key for each thing you mean to do, and the same key only to retry it. A retry returns the first receipt with result null.
- Sensitive writes also need confirm set to the operation name. Their pages say so.
- [OpenAPI document](https://shuffl.ai/api/v1/openapi.json)
- [How management writes work](https://shuffl.ai/docs/sdk#writes)
## Errors
A failed request returns an HTTP error status and a JSON body with code, status and message. Branch on code, not on message: the message is for people and can change. Some errors add a data object with details.
Don’t retry 400, 401, 403 or 404 without changing something. After a network failure or a 500, retry with the same input and request key, or read the resource first to see whether the write happened.
### Error codes
- `BAD_REQUEST` (400): the input does not match the operation’s schema. The message names the field.
- `UNAUTHORIZED` (401): the key is missing, expired, revoked or from another deployment. The response carries `WWW-Authenticate: Bearer`.
- `FORBIDDEN` (403): the key lacks this operation’s permission, or the key’s owner can’t do this in the app.
- `NOT_FOUND` (404): the resource or operation doesn’t exist in this workspace, or you can’t see it.
- `CONFLICT` (409): the expectedRevision is out of date, or a request key was reused with different input.
- `PRECONDITION_FAILED` (412): the workspace isn’t ready for this yet, such as a program with no channel.
- `TOO_MANY_REQUESTS` (429): the key is over its rate limit. Wait for `Retry-After`.
- `INTERNAL_SERVER_ERROR` (500): something failed on Shuffl’s side. Retry later with the same request key.
Error response:
```json
{
"defined": false,
"code": "FORBIDDEN",
"status": 403,
"message": "API access is unavailable."
}
```
## Rate limits
Each API key can make 120 requests a minute, shared between HTTP and MCP. The window starts with the first request. An MCP OAuth connection gets 60 a minute, and each company key gets 120.
Over the limit, the API answers 429 with code TOO_MANY_REQUESTS and a Retry-After header in seconds. Wait that long before the next request. Spread scheduled jobs out rather than retrying in a loop.
## Pagination
Paginated lists take limit (1 to 100, 25 by default) and cursor, and return items and nextCursor. Pass nextCursor back as cursor until it is null.
Every other list returns all its results in one response.
### Paginated operations
- groups.automationRuns
- identities.slackAccounts
- knowledge.connections.browse
- knowledge.sources.list
- programs.list
- users.list
- users.managerHistory
- company.members.list
HTTP:
```sh
curl "https://shuffl.ai/api/v1/users?limit=100" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
# { "items": [...], "nextCursor": "..." }
curl "https://shuffl.ai/api/v1/users?limit=100&cursor=" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Export people](https://shuffl.ai/docs/sdk-cookbook#export-people)
## Webhooks
Shuffl can call your server when something changes, so you don’t have to poll the list operations.
Add an endpoint in Settings → API keys and webhooks → Webhooks or with webhooks.create. Shuffl sends a signed request for each event it subscribes to.
- [Set up webhooks](https://shuffl.ai/docs/webhooks)
## Operations by area
418 operations in 43 areas. Each page is generated from the OpenAPI document and lists every operation’s method, path, permission, request and response fields, with an HTTP, SDK and CLI example.
- [API keys (3)](https://shuffl.ai/docs/api-reference/credentials)
- [Badges (15)](https://shuffl.ai/docs/api-reference/badges)
- [Celebrations (16)](https://shuffl.ai/docs/api-reference/celebrations)
- [Command receipts (1)](https://shuffl.ai/docs/api-reference/commands)
- [Communities (18)](https://shuffl.ai/docs/api-reference/communities)
- [Company settings (9)](https://shuffl.ai/docs/api-reference/company)
- [Connections programs (14)](https://shuffl.ai/docs/api-reference/programs)
- [Connections rounds (9)](https://shuffl.ai/docs/api-reference/runs)
- [Departments (1)](https://shuffl.ai/docs/api-reference/units)
- [Directory sync (8)](https://shuffl.ai/docs/api-reference/sync)
- [Employee access (5)](https://shuffl.ai/docs/api-reference/access)
- [Exports (1)](https://shuffl.ai/docs/api-reference/exports)
- [Get started (7)](https://shuffl.ai/docs/api-reference/get-started)
- [Groups (28)](https://shuffl.ai/docs/api-reference/groups)
- [Home (5)](https://shuffl.ai/docs/api-reference/home)
- [HR digest and nudges (8)](https://shuffl.ai/docs/api-reference/digest)
- [HR requests (15)](https://shuffl.ai/docs/api-reference/hr)
- [Integrations (1)](https://shuffl.ai/docs/api-reference/integrations)
- [Invitations (6)](https://shuffl.ai/docs/api-reference/invitations)
- [Knowledge (36)](https://shuffl.ai/docs/api-reference/knowledge)
- [Linked accounts (6)](https://shuffl.ai/docs/api-reference/identities)
- [Manager context (1)](https://shuffl.ai/docs/api-reference/manager)
- [Mello conversations (5)](https://shuffl.ai/docs/api-reference/assistant)
- [Mentorship (21)](https://shuffl.ai/docs/api-reference/mentorship)
- [Network (6)](https://shuffl.ai/docs/api-reference/network)
- [Notifications (2)](https://shuffl.ai/docs/api-reference/notifications)
- [Operations and audit (4)](https://shuffl.ai/docs/api-reference/operations)
- [People (19)](https://shuffl.ai/docs/api-reference/users)
- [Permissions (1)](https://shuffl.ai/docs/api-reference/permissions)
- [Playbooks (37)](https://shuffl.ai/docs/api-reference/playbooks)
- [Praise (13)](https://shuffl.ai/docs/api-reference/praise)
- [Profiles (10)](https://shuffl.ai/docs/api-reference/profiles)
- [Pulse (24)](https://shuffl.ai/docs/api-reference/pulse)
- [Reminders (4)](https://shuffl.ai/docs/api-reference/reminders)
- [Reports and insights (12)](https://shuffl.ai/docs/api-reference/reports)
- [Requests Mello filed (1)](https://shuffl.ai/docs/api-reference/actions)
- [Shuffl support (6)](https://shuffl.ai/docs/api-reference/support)
- [Slack channels (1)](https://shuffl.ai/docs/api-reference/channels)
- [Time off (1)](https://shuffl.ai/docs/api-reference/time-off)
- [Webhooks (12)](https://shuffl.ai/docs/api-reference/webhooks)
- [What Mello can do (5)](https://shuffl.ai/docs/api-reference/capabilities)
- [Workspace (18)](https://shuffl.ai/docs/api-reference/teams)
- [Workspace launch (3)](https://shuffl.ai/docs/api-reference/team)
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [SDK and CLI recipes](https://shuffl.ai/docs/sdk-cookbook)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
Agent documentation index: https://shuffl.ai/llms.txt
---
# SDK and CLI recipes
> Copyable recipes for common jobs, each with the SDK, the CLI and HTTP side by side.
Audience: Developers and automation owners
Kind: How-to guide
Canonical: https://shuffl.ai/docs/sdk-cookbook
## Before you start
Every recipe uses a workspace API key with the permissions it names, and nothing more. List company members is the exception: it uses a company key.
The SDK examples start from the client below. The CLI and HTTP examples read the same two environment variables.
Writes send a requestKey. Use a new one for each thing you mean to do, and the same one only to retry it. A retry with the same key returns the first receipt and doesn’t do the work again.
SDK:
```ts
import { Shuffl } from '@shuffl/sdk';
const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_API_KEY! });
```
CLI and HTTP:
```sh
# Load these from your credential manager. Never type the key on the command line.
export SHUFFL_BASE_URL=https://shuffl.ai
export SHUFFL_API_KEY="$(credential-command)"
```
- [Create a key](https://shuffl.ai/docs/sdk#credentials)
- [Install the CLI](https://shuffl.ai/docs/cli#install)
## Invite people from a CSV
Read the email column of a CSV and invite everyone in it to the workspace as members. Each person gets an email invitation. People already invited or already in the workspace are counted, not invited twice.
Use one request key per batch. If the call is cut off, send the same batch with the same key: you get the first receipt back and nobody is invited twice.
Send a large file in batches, each with its own key.
Permissions: invitations.createMany.
SDK:
```ts
import { readFile } from 'node:fs/promises';
const [header = '', ...rows] = (await readFile('people.csv', 'utf8'))
.trim()
.split('\n');
const column = header.split(',').indexOf('email');
const emails = rows
.map((row) => row.split(',')[column]?.trim() ?? '')
.filter((email) => email.includes('@'));
const { receipt, result } = await shuffl.invitations.createMany({
emails,
role: 'member',
confirm: 'invitations.createMany',
requestKey: 'invite-november-hires',
});
console.log(receipt.status, result?.invited.length, result?.alreadyMember);
```
CLI:
```sh
# Build invite.json from your CSV's email column.
cat > invite.json <<'JSON'
{
"confirm": "invitations.createMany",
"emails": [
"maya@example.com",
"sam@example.com"
],
"requestKey": "invite-november-hires",
"role": "member"
}
JSON
shuffl invitations create-many --input-file invite.json --json
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/invitations/createMany" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm":"invitations.createMany","emails":["maya@example.com","sam@example.com"],"requestKey":"invite-november-hires","role":"member"}'
```
- [invitations.createMany](https://shuffl.ai/docs/api-reference/invitations#operation-invitations-createMany)
## Publish a Knowledge article
Save a Knowledge article as a draft, then publish it to its audience. A new article needs a new UUID as its sourceId and expectedRevision 0. Publishing takes the version id and revision the save returned.
Publishing is what makes the text answerable: Mello and search_knowledge only use published sources. The key’s owner must be allowed to publish Knowledge.
Set reviewAt to when someone should check the article again. After that date it stops being used until it is reviewed.
Permissions: knowledge.sources.save, knowledge.sources.publish.
SDK:
```ts
const saved = await shuffl.knowledge.sources.save({
sourceId: crypto.randomUUID(),
expectedRevision: 0,
title: 'Parental leave',
body: 'Write the policy here. Once it is published, Mello answers from this text and cites it.',
audience: 'everyone',
effectiveAt: new Date().toISOString(),
reviewAt: '2027-05-01T00:00:00.000Z',
requestKey: 'parental-leave-draft',
});
// A repeated request key returns result: null. Read the source instead.
if (!saved.result) throw new Error('Already saved: read it with knowledge.sources.get');
await shuffl.knowledge.sources.publish({
sourceId: saved.result.source.id,
versionId: saved.result.version.id,
expectedRevision: saved.result.source.revision,
confirm: 'knowledge.sources.publish',
requestKey: 'parental-leave-publish',
});
```
CLI:
```sh
cat > draft.json <<'JSON'
{
"audience": "everyone",
"body": "Write the policy here. Once it is published, Mello answers from this text and cites it.",
"effectiveAt": "2026-11-01T00:00:00.000Z",
"expectedRevision": 0,
"requestKey": "parental-leave-draft",
"reviewAt": "2027-05-01T00:00:00.000Z",
"sourceId": "0b6f7a2e-3c1d-4f8e-9a51-2d7c4e8b1f60",
"title": "Parental leave"
}
JSON
shuffl knowledge sources save --input-file draft.json --json
# Use the version id and revision the save returned.
cat > publish.json <<'JSON'
{
"confirm": "knowledge.sources.publish",
"expectedRevision": 1,
"requestKey": "parental-leave-publish",
"sourceId": "0b6f7a2e-3c1d-4f8e-9a51-2d7c4e8b1f60",
"versionId": ""
}
JSON
shuffl knowledge sources publish --input-file publish.json --json
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/knowledge/sources/save" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"audience":"everyone","body":"Write the policy here. Once it is published, Mello answers from this text and cites it.","effectiveAt":"2026-11-01T00:00:00.000Z","expectedRevision":0,"requestKey":"parental-leave-draft","reviewAt":"2027-05-01T00:00:00.000Z","sourceId":"0b6f7a2e-3c1d-4f8e-9a51-2d7c4e8b1f60","title":"Parental leave"}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/knowledge/sources/publish" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm":"knowledge.sources.publish","expectedRevision":1,"requestKey":"parental-leave-publish","sourceId":"0b6f7a2e-3c1d-4f8e-9a51-2d7c4e8b1f60","versionId":""}'
```
- [knowledge.sources.save](https://shuffl.ai/docs/api-reference/knowledge#operation-knowledge-sources-save)
- [knowledge.sources.publish](https://shuffl.ai/docs/api-reference/knowledge#operation-knowledge-sources-publish)
## Create a Connections program
Pick a Slack channel, create a Connections program for its members, then turn it on. channels.list shows each channel’s readiness: use one that says ready. The program starts paused, so nothing is sent until you resume it.
Resuming turns on the program’s schedule. To see who would meet before you do, call programs.preview first.
Permissions: channels.list, programs.create, programs.resume.
SDK:
```ts
const channels = await shuffl.channels.list();
const channel = channels.find((entry) => entry.name === 'coffee-chats');
if (channel?.readiness !== 'ready') throw new Error('Add Shuffl to the channel first');
const created = await shuffl.programs.create({
draft: true,
requestKey: 'coffee-chats-create',
program: {
name: 'Coffee chats',
channelId: channel.id,
channelName: channel.name,
includeBios: true,
intro: 'Meet someone new this fortnight. Pick a time that suits you both.',
match: { strategy: 'new-connections', groupSize: 2, maxGroupSize: 3, iterations: 50 },
schedule: {
frequency: 'weeks',
interval: 2,
anchor: '2026-11-02T09:00:00',
timezone: 'America/New_York',
},
},
});
await shuffl.programs.resume({ id: created.id });
```
CLI:
```sh
shuffl channels list --json
cat > program.json <<'JSON'
{
"draft": true,
"program": {
"channelId": "C0123456789",
"channelName": "coffee-chats",
"includeBios": true,
"intro": "Meet someone new this fortnight. Pick a time that suits you both.",
"match": {
"groupSize": 2,
"iterations": 50,
"maxGroupSize": 3,
"strategy": "new-connections"
},
"name": "Coffee chats",
"schedule": {
"anchor": "2026-11-02T09:00:00",
"frequency": "weeks",
"interval": 2,
"timezone": "America/New_York"
}
},
"requestKey": "coffee-chats-create"
}
JSON
shuffl programs create --input-file program.json --json
shuffl programs resume --id "" --json
```
HTTP:
```sh
curl "$SHUFFL_BASE_URL/api/v1/channels" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
curl -X POST "$SHUFFL_BASE_URL/api/v1/programs" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"draft":true,"program":{"channelId":"C0123456789","channelName":"coffee-chats","includeBios":true,"intro":"Meet someone new this fortnight. Pick a time that suits you both.","match":{"groupSize":2,"iterations":50,"maxGroupSize":3,"strategy":"new-connections"},"name":"Coffee chats","schedule":{"anchor":"2026-11-02T09:00:00","frequency":"weeks","interval":2,"timezone":"America/New_York"}},"requestKey":"coffee-chats-create"}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/programs//resume" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
- [channels.list](https://shuffl.ai/docs/api-reference/channels#operation-channels-list)
- [programs.create](https://shuffl.ai/docs/api-reference/programs#operation-programs-create)
- [programs.resume](https://shuffl.ai/docs/api-reference/programs#operation-programs-resume)
## Schedule Pulse
Read the Pulse settings, change when questions go out, and turn Pulse on. sendDays runs from 1 for Monday to 7 for Sunday. sendHour and sendMinute are in the timezone you give.
expectedRevision is the revision you read, so you never overwrite a change someone made since.
Setting status to active schedules questions to everyone in the workspace. Answers are only shown for groups of reportingFloor people or more, and never one person’s answer.
Permissions: pulse.program, pulse.saveProgram.
SDK:
```ts
const current = await shuffl.pulse.program({});
await shuffl.pulse.saveProgram({
...current.settings,
sendDays: [2],
sendHour: 10,
sendMinute: 0,
timezone: 'America/New_York',
status: 'active',
expectedRevision: current.revision,
confirm: 'pulse.saveProgram',
requestKey: 'pulse-tuesdays',
});
```
CLI:
```sh
shuffl pulse program --json
# Copy your current settings and revision into pulse.json, then change them.
cat > pulse.json <<'JSON'
{
"aiAnalysis": true,
"confirm": "pulse.saveProgram",
"expectedRevision": 3,
"openHours": 48,
"reportingFloor": 7,
"requestKey": "pulse-tuesdays",
"sendDays": [
2
],
"sendHour": 10,
"sendMinute": 0,
"status": "active",
"timezone": "America/New_York"
}
JSON
shuffl pulse save-program --input-file pulse.json --json
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/pulse/program" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/pulse/saveProgram" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"aiAnalysis":true,"confirm":"pulse.saveProgram","expectedRevision":3,"openHours":48,"reportingFloor":7,"requestKey":"pulse-tuesdays","sendDays":[2],"sendHour":10,"sendMinute":0,"status":"active","timezone":"America/New_York"}'
```
- [pulse.program](https://shuffl.ai/docs/api-reference/pulse#operation-pulse-program)
- [pulse.saveProgram](https://shuffl.ai/docs/api-reference/pulse#operation-pulse-saveProgram)
## Give praise or a badge
Praise is posted as the key’s owner in a praise channel. Badges are given by someone who owns the badge.
praise.composer lists the channels, the people you can praise and your company values, or says why praise is unavailable. Pick recipients from its people.
composerKey identifies one praise message, so a retry with the same key never posts it twice. Use 8 to 64 letters, digits, hyphens or underscores. badges.list marks the badges you can give with canAward.
Permissions: praise.composer, praise.send, badges.list, badges.award.
SDK:
```ts
const composer = await shuffl.praise.composer({});
if (composer.blocked) throw new Error('Praise is unavailable: ' + composer.blocked);
await shuffl.praise.send({
channelId: composer.channels[0]!.id,
recipientIds: [''],
text: 'Thank you for running the onboarding session this week.',
composerKey: 'thanks-onboarding-session',
confirm: 'praise.send',
requestKey: 'thanks-onboarding-session',
});
const badges = await shuffl.badges.list({});
const mentor = badges.find((badge) => badge.canAward && badge.name === 'Mentor');
if (mentor)
await shuffl.badges.award({
badgeId: mentor.id,
personId: '',
reason: 'Mentored two new hires this quarter.',
confirm: 'badges.award',
requestKey: 'mentor-badge-maya',
});
```
CLI:
```sh
shuffl praise composer --json
cat > praise.json <<'JSON'
{
"channelId": "",
"composerKey": "thanks-onboarding-session",
"confirm": "praise.send",
"recipientIds": [
""
],
"requestKey": "thanks-onboarding-session",
"text": "Thank you for running the onboarding session this week."
}
JSON
shuffl praise send --input-file praise.json --json
shuffl badges list --json
cat > award.json <<'JSON'
{
"badgeId": "",
"confirm": "badges.award",
"personId": "",
"reason": "Mentored two new hires this quarter.",
"requestKey": "mentor-badge-maya"
}
JSON
shuffl badges award --input-file award.json --json
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/praise/composer" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/praise/send" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"channelId":"","composerKey":"thanks-onboarding-session","confirm":"praise.send","recipientIds":[""],"requestKey":"thanks-onboarding-session","text":"Thank you for running the onboarding session this week."}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/badges/list" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/badges/award" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"badgeId":"","confirm":"badges.award","personId":"","reason":"Mentored two new hires this quarter.","requestKey":"mentor-badge-maya"}'
```
- [praise.composer](https://shuffl.ai/docs/api-reference/praise#operation-praise-composer)
- [praise.send](https://shuffl.ai/docs/api-reference/praise#operation-praise-send)
- [badges.list](https://shuffl.ai/docs/api-reference/badges#operation-badges-list)
- [badges.award](https://shuffl.ai/docs/api-reference/badges#operation-badges-award)
## Read Pulse insights
Read Pulse participation, favourable scores and trends for the last 30, 90 or 180 days. Results only cover groups at or above the reporting floor, which is never below seven people, and no operation returns one person’s answer.
withheld counts the questions whose results stay hidden because too few people answered. Use pulse.questionDetail for one closed question and pulse.actions for what the company is doing about it.
Permissions: pulse.insights.
SDK:
```ts
const insights = await shuffl.pulse.insights({ days: 90 });
console.log(insights.participationPct, insights.favourablePct, insights.withheld);
```
CLI:
```sh
shuffl pulse insights --days 90 --json
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/pulse/insights" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"days":90}'
```
- [pulse.insights](https://shuffl.ai/docs/api-reference/pulse#operation-pulse-insights)
## List open HR requests
List the HR requests that still need someone: every request whose status is open, waiting_on_hr or waiting_on_employee.
hr.list returns the requests the key’s owner asked or can answer. An HR responder sees their queue and an employee sees their own.
HR requests are confidential. Keep the output out of shared logs and chat. dueAt is when the response target runs out.
Permissions: hr.list.
SDK:
```ts
const requests = await shuffl.hr.list({});
const open = requests.filter((request) => request.status !== 'resolved');
for (const request of open)
console.log(request.id, request.status, request.category?.name, request.dueAt);
```
CLI:
```sh
shuffl hr list --json | jq '[.[] | select(.status != "resolved")]'
```
HTTP:
```sh
curl -X POST "$SHUFFL_BASE_URL/api/v1/manage/hr/list" \
-H "Authorization: Bearer $SHUFFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
| jq '[.[] | select(.status != "resolved")]'
```
- [hr.list](https://shuffl.ai/docs/api-reference/hr#operation-hr-list)
## Export people
Page through the People directory and write it to a CSV. Each page holds up to 100 people; pass nextCursor back as cursor until it comes back null.
For a full copy of the workspace, with programs and introduction history as well as people, an administrator can use exports.team.
Permissions: users.list.
SDK:
```ts
import { writeFile } from 'node:fs/promises';
const people = [];
let cursor: string | undefined;
do {
const page = await shuffl.users.list({ limit: 100, cursor });
people.push(...page.items);
cursor = page.nextCursor ?? undefined;
} while (cursor);
const cell = (value: string | null) => JSON.stringify(value ?? '');
await writeFile(
'people.csv',
['id,name,email', ...people.map((p) => [p.id, p.name, p.email].map(cell).join(','))].join('\n'),
);
```
CLI:
```sh
shuffl users list --limit 100 --json
# Repeat with the nextCursor from each page until it is null.
shuffl users list --limit 100 --cursor "" --json
```
HTTP:
```sh
curl "$SHUFFL_BASE_URL/api/v1/users?limit=100" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
curl "$SHUFFL_BASE_URL/api/v1/users?limit=100&cursor=" \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
- [users.list](https://shuffl.ai/docs/api-reference/users#operation-users-list)
## List company members
List everyone in the company, across all its workspaces, with their company role.
This recipe takes a company key instead of a workspace key. A company owner or administrator creates one in Settings → API keys and webhooks → Company keys with the company.members.list permission.
In the SDK, pass the company key to new Shuffl and call shuffl.company. In the CLI, save it with shuffl login --company or set SHUFFL_COMPANY_KEY. To offboard someone, company.members.remove takes a userId from this list.
Permissions: company.members.list.
SDK:
```ts
import { Shuffl } from '@shuffl/sdk';
const shuffl = new Shuffl({ apiKey: process.env.SHUFFL_COMPANY_KEY! });
const members = [];
let cursor: string | undefined;
do {
const page = await shuffl.company.members.list({ limit: 100, cursor });
members.push(...page.items);
cursor = page.nextCursor ?? undefined;
} while (cursor);
for (const member of members)
console.log(member.userId, member.role, member.email);
```
CLI:
```sh
shuffl company members list --limit 100 --json
# Repeat with the nextCursor from each page until it is null.
shuffl company members list --limit 100 --cursor "" --json
```
HTTP:
```sh
curl "$SHUFFL_BASE_URL/api/v1/company/members.list?limit=100" \
-H "Authorization: Bearer $SHUFFL_COMPANY_KEY"
curl "$SHUFFL_BASE_URL/api/v1/company/members.list?limit=100&cursor=" \
-H "Authorization: Bearer $SHUFFL_COMPANY_KEY"
```
- [company.members.list](https://shuffl.ai/docs/api-reference/company#operation-company-members-list)
## Find another operation
Every operation has the same three forms. The REST API reference shows each one’s fields with an SDK call, a CLI command and a curl example.
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [Handle errors](https://shuffl.ai/docs/sdk#errors)
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
- [REST API reference](https://shuffl.ai/docs/api-reference)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
Agent documentation index: https://shuffl.ai/llms.txt
---
# MCP tool list
> Every tool the Shuffl MCP server can offer, with what it does and the permission that turns it on.
Audience: Agent builders and workspace administrators
Kind: Reference
Canonical: https://shuffl.ai/docs/mcp-tools
## How tools are chosen
Every connection gets the three knowledge tools. Each other tool is one API operation, named after its permission with dots as underscores, and a connection lists only the tools its permissions grant. That is 406 action tools in all.
A tool takes the same input as its API operation, so the REST API reference documents every argument.
Read tools are marked read only. Tools that remove, stop or withdraw something are marked destructive, so clients that honor the mark ask before running them.
- [How action tools work](https://shuffl.ai/docs/mcp#actions)
- [Fields for each operation](https://shuffl.ai/docs/api-reference)
## Knowledge tools
The MCP permission turns these on for an API key, and every OAuth connection has them.
- `get_team`: Get the connected workspace’s name and id and your current role. Read only. Permission `mcp.knowledge`.
- `search_knowledge`: Search current, approved knowledge you can see. Returns up to eight passages with citation links. Read only. Permission `mcp.knowledge`.
- `get_knowledge_passage`: Read one passage that search_knowledge returned. Read only. Permission `mcp.knowledge`.
## API keys
- `credentials_api_list`: List the workspace's API keys and what each can do. Read only. Permission `credentials.api.list`.
- `credentials_api_create`: Delegate a subset of this credential with bounded expiry and inherited revocation. Write. Permission `credentials.api.create`.
- `credentials_api_revoke`: Revoke an API key. Write, destructive. Permission `credentials.api.revoke`.
- [API keys API reference](https://shuffl.ai/docs/api-reference/credentials)
## Badges
- `badges_holders`: List the people who hold a badge, as far as each lets you see. Read only. Permission `badges.holders`.
- `badges_list`: List the team’s badges, who holds them and any open requests you decide. Read only. Permission `badges.list`.
- `badges_ofPerson`: List a person's badges. Read only. Permission `badges.ofPerson`.
- `badges_settings`: Read the badge suggestion settings. Read only. Permission `badges.settings`.
- `badges_award`: Give a badge you own to a person. Write. Permission `badges.award`.
- `badges_claim`: Claim a badge with its code. Write. Permission `badges.claim`.
- `badges_decideRequest`: Approve or decline a request for a badge. Write. Permission `badges.decideRequest`.
- `badges_generatePicture`: Draw an AI picture for a badge you own. Keeps a picture already set unless replace is true; idea says what to draw. Write. Permission `badges.generatePicture`.
- `badges_hideOwn`: Hide or show one of your badges on your profile. Write. Permission `badges.hideOwn`.
- `badges_request`: Ask for a badge. Write. Permission `badges.request`.
- `badges_revoke`: Take a badge back from a person. Write, destructive. Permission `badges.revoke`.
- `badges_save`: Create or edit a badge you own. Write. Permission `badges.save`.
- `badges_saveSettings`: Turn badge offers from praise on or off, and choose the launch channel. Write. Permission `badges.saveSettings`.
- `badges_setHidden`: Hide or show a badge for the whole workspace. Write. Permission `badges.setHidden`.
- `badges_uploadPicture`: Set a badge picture from a PNG, JPEG or WebP picture sent as base64, for a badge you own. Write. Permission `badges.uploadPicture`.
- [Badges API reference](https://shuffl.ai/docs/api-reference/badges)
## Celebrations
- `celebrations_card`: Open a celebration card you can sign or were given. Read only. Permission `celebrations.card`.
- `celebrations_cards`: List celebration cards to sign and cards you were given. Read only. Permission `celebrations.cards`.
- `celebrations_deliveries`: List the celebration messages Shuffl sent. Read only. Permission `celebrations.deliveries`.
- `celebrations_mine`: List the celebrations you received. Read only. Permission `celebrations.mine`.
- `celebrations_preferences`: Read your birthday and work anniversary sharing preferences. Read only. Permission `celebrations.preferences`.
- `celebrations_preview`: Preview a celebration message. Read only. Permission `celebrations.preview`.
- `celebrations_program`: Read the Celebrations settings. Read only. Permission `celebrations.program`.
- `celebrations_review`: Review upcoming birthdays and work anniversaries. Read only. Permission `celebrations.review`.
- `celebrations_startDates`: Read which start date anniversaries count from and the start dates that look wrong. Read only. Permission `celebrations.startDates`.
- `celebrations_thisWeek`: List who was celebrated in a channel in the last seven days. Read only. Permission `celebrations.thisWeek`.
- `celebrations_refresh`: Look for new birthdays and work anniversaries to celebrate now. Write. Permission `celebrations.refresh`.
- `celebrations_removeCardNote`: Remove your note from this celebration card. Write. Permission `celebrations.removeCardNote`.
- `celebrations_save`: Save celebration settings; enabling them schedules messages. Write. Permission `celebrations.save`.
- `celebrations_saveAnniversaryDate`: Choose which start date work anniversaries count from; reschedules them. Write. Permission `celebrations.saveAnniversaryDate`.
- `celebrations_savePreferences`: Save your birthday and work anniversary sharing preferences. Write. Permission `celebrations.savePreferences`.
- `celebrations_signCard`: Sign this celebration card with your note. Write. Permission `celebrations.signCard`.
- [Celebrations API reference](https://shuffl.ai/docs/api-reference/celebrations)
## Command receipts
- `commands_get`: Read your own command receipt. Read only. Permission `commands.get`.
- [Command receipts API reference](https://shuffl.ai/docs/api-reference/commands)
## Communities
- `communities_channelSuggestions`: List Slack channels, with the ones that look like communities suggested. Read only. Permission `communities.channelSuggestions`.
- `communities_createCapabilities`: Read the current permission to create public or private community channels. Read only. Permission `communities.createCapabilities`.
- `communities_list`: List communities with the members you may see. Read only. Permission `communities.list`.
- `communities_members`: List a community's members. Read only. Permission `communities.members`.
- `communities_ofPerson`: List the communities a person belongs to. Read only. Permission `communities.ofPerson`.
- `communities_archive`: Archive a community. Write, destructive. Permission `communities.archive`.
- `communities_createSlackChannel`: Create an explicitly public or private Slack channel as an authorized community owner or administrator, retaining its request id across retries. Write. Permission `communities.createSlackChannel`.
- `communities_fromChannels`: Create one community per chosen Slack channel, as an administrator. Write. Permission `communities.fromChannels`.
- `communities_generateCover`: Draw an AI cover for a community, as its owner, moderator or an administrator. Keeps a cover already set unless replace is true; idea says what to draw. Write. Permission `communities.generateCover`.
- `communities_invite`: Invite selected people to a community as its owner or administrator; each person must accept. Write. Permission `communities.invite`.
- `communities_join`: Join a community. Write. Permission `communities.join`.
- `communities_leave`: Leave a community. Write. Permission `communities.leave`.
- `communities_removeMember`: Remove someone from a community, as its owner or moderator. Write. Permission `communities.removeMember`.
- `communities_revokeInvitation`: Revoke a pending community invitation as its owner or administrator. Write. Permission `communities.revokeInvitation`.
- `communities_save`: Create or edit a community, optionally tied to a Slack channel. Write. Permission `communities.save`.
- `communities_setVisibility`: Show or hide a community on your profile. Write. Permission `communities.setVisibility`.
- `communities_sync`: Sync a community's members with its Slack channel now. Write. Permission `communities.sync`.
- `communities_uploadCover`: Set a community cover from a PNG, JPEG or WebP picture sent as base64, as its owner, moderator or an administrator. Write. Permission `communities.uploadCover`.
- [Communities API reference](https://shuffl.ai/docs/api-reference/communities)
## Connections programs
- `programs_communities`: List communities a Connections program can take its people from, with how many members show each one on their profile. Read only. Permission `programs.communities`.
- `programs_get`: Read a program. Read only. Permission `programs.get`.
- `programs_list`: List programs. Read only. Permission `programs.list`.
- `programs_options`: List program setting choices. Read only. Permission `programs.options`.
- `programs_people`: List the people in a program and whether they take part. Read only. Permission `programs.people`.
- `programs_preview`: Preview matches without sending. Read only. Permission `programs.preview`.
- `programs_schedulePreview`: Preview a program's upcoming rounds. Read only. Permission `programs.schedulePreview`.
- `programs_archive`: Archive a program. Write, destructive. Permission `programs.archive`.
- `programs_create`: Create a program. Write. Permission `programs.create`.
- `programs_joinChannel`: Add Shuffl to this public Slack channel. Write. Permission `programs.joinChannel`.
- `programs_pause`: Pause a Connections program and its introductions. Write, destructive. Permission `programs.pause`.
- `programs_resume`: Activate a program and schedule. Write. Permission `programs.resume`.
- `programs_syncRoster`: Refresh channel membership. Write. Permission `programs.syncRoster`.
- `programs_update`: Update a program. Write. Permission `programs.update`.
- [Connections programs API reference](https://shuffl.ai/docs/api-reference/programs)
## Connections rounds
- `runs_details`: Read one introduction round and its pairs. Read only. Permission `runs.details`.
- `runs_get`: Read a run status. Read only. Permission `runs.get`.
- `runs_list`: List a program's introduction rounds. Read only. Permission `runs.list`.
- `runs_dispatch`: Dispatch this queued introduction run. Write. Permission `runs.dispatch`.
- `runs_request`: Request introductions from a preview. Write. Permission `runs.request`.
- `runs_retry`: Retry introduction delivery. Write. Permission `runs.retry`.
- `runs_stopKnownFailures`: Stop retrying known failed deliveries and advance the preserved monthly schedule. Write, destructive. Permission `runs.stopKnownFailures`.
- `runs_history_get`: Read one introduction round imported from the previous Shuffl. Read only. Permission `runs.history.get`.
- `runs_history_list`: List introduction rounds imported from the previous Shuffl. Read only. Permission `runs.history.list`.
- [Connections rounds API reference](https://shuffl.ai/docs/api-reference/runs)
## Departments
- `units_list`: List the departments in the People directory. Read only. Permission `units.list`.
- [Departments API reference](https://shuffl.ai/docs/api-reference/units)
## Directory sync
- `sync_current`: Read the People sync provider, its last sync and what it found. Read only. Permission `sync.current`.
- `sync_groups`: List this source’s groups and which ones come into Shuffl. Read only. Permission `sync.groups`.
- `sync_connect`: Connect a directory sync provider with the credential given. Write. Permission `sync.connect`.
- `sync_disconnect`: Disconnect this directory sync provider. Write, destructive. Permission `sync.disconnect`.
- `sync_request`: Ask for a People sync provider Shuffl does not support yet. Write. Permission `sync.request`.
- `sync_run`: Sync People from the connected provider now. Write. Permission `sync.run`.
- `sync_setGroup`: Change which of this source’s groups come into Shuffl. Write. Permission `sync.setGroup`.
- `sync_setWrites`: Let Mello file requests in this source, or stop it. Write. Permission `sync.setWrites`.
- [Directory sync API reference](https://shuffl.ai/docs/api-reference/sync)
## Employee access
- `access_get`: Read one person's workspace role and app access. Read only. Permission `access.get`.
- `access_slackWaiting`: List Slack members waiting for access to Shuffl. Read only. Permission `access.slackWaiting`.
- `access_enableSlack`: Give these Slack people employee access. Write. Permission `access.enableSlack`.
- `access_save`: Change employee product access. Write. Permission `access.save`.
- `access_saveRole`: Change a member’s team role. Write. Permission `access.saveRole`.
- [Employee access API reference](https://shuffl.ai/docs/api-reference/access)
## Exports
- `exports_team`: Export the workspace's programs, people and introduction history. Read only. Permission `exports.team`.
- [Exports API reference](https://shuffl.ai/docs/api-reference/exports)
## Get started
- `getStarted_celebration`: Read the first-action celebration waiting for you, if any. Read only. Permission `getStarted.celebration`.
- `getStarted_get`: Read your own Get started steps and whether the welcome still shows. Read only. Permission `getStarted.get`.
- `getStarted_celebrate`: Record that a celebration was shown, shared or dismissed. Write. Permission `getStarted.celebrate`.
- `getStarted_dismiss`: Hide the Get started card. Write. Permission `getStarted.dismiss`.
- `getStarted_draftIntro`: Draft a short hello to your coworkers with Mello; nothing is posted. Write. Permission `getStarted.draftIntro`.
- `getStarted_intro`: Post your hello on Home, or skip it. Write. Permission `getStarted.intro`.
- `getStarted_wizard`: Record that you opened, finished or skipped the welcome. Write. Permission `getStarted.wizard`.
- [Get started API reference](https://shuffl.ai/docs/api-reference/get-started)
## Groups
- `groups_allAutomations`: Every join and leave automation in the workspace: group automations with their group and last runs, playbooks that start on each start date or each last day (`dayZero`) and Connections programs whose people are a group; or only those that start one playbook, program or community. Read only. Permission `groups.allAutomations`.
- `groups_automationChoices`: The Pulse questions, badges and Shuffl lists a group automation can ask, give or add people to. Read only. Permission `groups.automationChoices`.
- `groups_automationInsights`: Group automation runs over the last `days` (30, 90 or 180) against the period before: done, skipped and failed, people reached, by week and kind, the top reasons a run did nothing, runs still scheduled and automations on; `groupId` narrows it. Read only. Permission `groups.automationInsights`.
- `groups_automationRuns`: Every group automation run in the workspace, newest first, 50 at a time (`next` is the cursor for the page after), with `counts` by outcome; `outcome` and `groupId` narrow it. Read only. Permission `groups.automationRuns`.
- `groups_automations`: A group’s automations (what happens when someone joins or leaves) and their last runs. Read only. Permission `groups.automations`.
- `groups_directory`: List the groups shown on profiles, yours first, with a few faces each. Read only. Permission `groups.directory`.
- `groups_directoryGroup`: Read one group shown on profiles and everyone in it. Read only. Permission `groups.directoryGroup`.
- `groups_export`: A group’s members as a CSV file: name, email, title, department, manager and when they joined. Read only. Permission `groups.export`.
- `groups_get`: Read one group: its rules, members and recent entries and exits. Read only. Permission `groups.get`.
- `groups_glance`: One group at a glance: size, joins, departments, tenure and time zones. Read only. Permission `groups.glance`.
- `groups_list`: List the workspace’s groups with who is in each. Read only. Permission `groups.list`.
- `groups_members`: One page of a group’s members. Read only. Permission `groups.members`.
- `groups_message`: One message to a group: its words, who it would reach now and how it reads to one member. Read only. Permission `groups.message`.
- `groups_messages`: The drafts and sends of messages to a group, newest first. Read only. Permission `groups.messages`.
- `groups_options`: The departments, teams, communities, programs, titles, locations and time zones a rule may name. Read only. Permission `groups.options`.
- `groups_preview`: Count and sample who a set of rules would hold today. Read only. Permission `groups.preview`.
- `groups_searchPeople`: Find people by name to pick for a group. Read only. Permission `groups.searchPeople`.
- `groups_suggestions`: Starter groups not made yet, with how many people each would hold. Read only. Permission `groups.suggestions`.
- `groups_discardMessage`: Drop a drafted message to a group. Write. Permission `groups.discardMessage`.
- `groups_prepareMessage`: Write a message to everyone in a group and see who it would reach; nothing is sent. Write. Permission `groups.prepareMessage`.
- `groups_refresh`: Re-evaluate a dynamic group’s rules now. Write. Permission `groups.refresh`.
- `groups_remove`: Remove a group. Write. Permission `groups.remove`.
- `groups_removeAutomation`: Remove an automation from a group, with its runs. Write. Permission `groups.removeAutomation`.
- `groups_save`: Create or change a group or a department: a list of people or rules that keep it up to date. Write. Permission `groups.save`.
- `groups_sendMessage`: Send a drafted message to a group once per request key, on each person’s chosen channel. Write. Permission `groups.sendMessage`.
- `groups_setAutomation`: Add or change an automation on a group: send a message, ask a Pulse question, start a playbook, invite to a community, add to Connections, give a badge, add to or remove from another group, add to or post in a Slack channel (`config.channelId`, read back from Slack), or tell HR, their manager or someone named, right away or days later; a new one starts paused. Write. Permission `groups.setAutomation`.
- `groups_setAutomationState`: Pause or resume an automation on a group. Write. Permission `groups.setAutomationState`.
- `groups_setPlaybookAutoStart`: Turn on, pause or remove a playbook’s automation that starts it on each new hire’s start date, or a leaving playbook’s on each last day, for everyone or one group. Write. Permission `groups.setPlaybookAutoStart`.
- [Groups API reference](https://shuffl.ai/docs/api-reference/groups)
## Home
- `home_feed`: What happened to people you know, and who Mello thinks you should meet. Read only. Permission `home.feed`.
- `home_places`: The areas turned on for you, what is waiting for you, and your onboarding progress. Read only. Permission `home.places`.
- `home_preferences`: Choose how Home looks: cards or compact, stories, autoplay, For you. Write. Permission `home.preferences`.
- `home_react`: Add or remove your emoji reaction on a Home moment. Write. Permission `home.react`.
- `home_story`: Record Home stories you opened, sent a note from, or skipped. Write. Permission `home.story`.
- [Home API reference](https://shuffl.ai/docs/api-reference/home)
## HR digest and nudges
- `digest_culture`: List the Culture page’s recommendations in order and what happened after each one acted on. Read only. Permission `digest.culture`.
- `digest_nudge`: Read one of Mello’s culture nudges. Read only. Permission `digest.nudge`.
- `digest_nudges`: List Mello’s culture nudges for the workspace. Read only. Permission `digest.nudges`.
- `digest_preview`: Preview the HR digest for the last period. Read only. Permission `digest.preview`.
- `digest_settings`: Read the HR digest schedule. Read only. Permission `digest.settings`.
- `digest_actOnNudge`: Record that a culture nudge was acted on and get where its action goes. Write. Permission `digest.actOnNudge`.
- `digest_dismissNudge`: Dismiss a culture nudge for 90 days. Write. Permission `digest.dismissNudge`.
- `digest_saveSettings`: Save the HR digest schedule and admin channel. Write. Permission `digest.saveSettings`.
- [HR digest and nudges API reference](https://shuffl.ai/docs/api-reference/digest)
## HR requests
- `hr_categories`: Read the HR request categories and response target. Read only. Permission `hr.categories`.
- `hr_get`: Read one HR request and its messages. Read only. Permission `hr.get`.
- `hr_list`: List the HR requests you asked or can answer. Read only. Permission `hr.list`.
- `hr_mine`: List the HR requests you asked, with HR’s latest reply. Read only. Permission `hr.mine`.
- `hr_readiness`: Check whether HR requests have a destination and someone to answer them. Read only. Permission `hr.readiness`.
- `hr_settings`: Read the HR team name and who answers HR requests. Read only. Permission `hr.settings`.
- `hr_shareSources`: List your recent Mello conversations that an HR request can include. Read only. Permission `hr.shareSources`.
- `hr_command`: Claim, release, reply to, note, categorize, resolve or reopen an HR request. Write. Permission `hr.command`.
- `hr_configure`: Change the HR request destination. Write. Permission `hr.configure`.
- `hr_deliver`: Deliver your HR reply to the employee. Write. Permission `hr.deliver`.
- `hr_rebuildCategories`: Have Mello rebuild the HR request categories from published Knowledge. Write. Permission `hr.rebuildCategories`.
- `hr_renameTeam`: Rename the HR team employees send requests to. Write. Permission `hr.renameTeam`.
- `hr_retryDelivery`: Retry HR request delivery. Write. Permission `hr.retryDelivery`.
- `hr_saveCategories`: Save the HR request categories, their owners and the response target. Write. Permission `hr.saveCategories`.
- `hr_share`: Share this request with the selected HR responders. Write. Permission `hr.share`.
- [HR requests API reference](https://shuffl.ai/docs/api-reference/hr)
## Integrations
- `integrations_authorize`: Get the link that connects Slack, Google Drive or Notion to the workspace. Read only. Permission `integrations.authorize`.
- [Integrations API reference](https://shuffl.ai/docs/api-reference/integrations)
## Invitations
- `invitations_candidates`: List people in the directory who can be invited to the workspace. Read only. Permission `invitations.candidates`.
- `invitations_list`: List pending workspace invitations. Read only. Permission `invitations.list`.
- `invitations_cancel`: Cancel a pending workspace invitation. Write, destructive. Permission `invitations.cancel`.
- `invitations_create`: Invite this person with the selected team role. Write. Permission `invitations.create`.
- `invitations_createMany`: Invite these people with the selected team role. Write. Permission `invitations.createMany`.
- `invitations_inviteDirectory`: Invite everyone in the directory who is not invited yet. Write. Permission `invitations.inviteDirectory`.
- [Invitations API reference](https://shuffl.ai/docs/api-reference/invitations)
## Knowledge
- `knowledge_context`: Read nearby approved passages. Read only. Permission `knowledge.context`.
- `knowledge_acknowledgements_mine`: List the Knowledge pages you are asked to read and confirm. Read only. Permission `knowledge.acknowledgements.mine`.
- `knowledge_acknowledgements_status`: See who has confirmed a Knowledge page and who has not. Read only. Permission `knowledge.acknowledgements.status`.
- `knowledge_acknowledgements_close`: Stop asking people to confirm this page. Write, destructive. Permission `knowledge.acknowledgements.close`.
- `knowledge_acknowledgements_remind`: Message the people who have not confirmed this page yet. Write. Permission `knowledge.acknowledgements.remind`.
- `knowledge_acknowledgements_request`: Ask the people who can read this page to confirm they read it, and message them. Write. Permission `knowledge.acknowledgements.request`.
- `knowledge_connections_browse`: List documents a connected Knowledge source can see. Read only. Permission `knowledge.connections.browse`.
- `knowledge_connections_list`: List connected Knowledge providers. Read only. Permission `knowledge.connections.list`.
- `knowledge_connections_requests`: List requests to connect a Knowledge source. Read only. Permission `knowledge.connections.requests`.
- `knowledge_connections_connect`: Connect a Knowledge provider with a token. Write. Permission `knowledge.connections.connect`.
- `knowledge_connections_disconnect`: Disconnect a knowledge provider. Write, destructive. Permission `knowledge.connections.disconnect`.
- `knowledge_connections_request`: Ask an administrator to connect a Knowledge source. Write. Permission `knowledge.connections.request`.
- `knowledge_handbook_export`: Download the pages published to everyone as one handbook, in Markdown. Read only. Permission `knowledge.handbook.export`.
- `knowledge_policies_coverage`: Check which common HR policies Knowledge covers. Read only. Permission `knowledge.policies.coverage`.
- `knowledge_sources_get`: Read a Knowledge source. Read only. Permission `knowledge.sources.get`.
- `knowledge_sources_history`: List a Knowledge source's versions. Read only. Permission `knowledge.sources.history`.
- `knowledge_sources_list`: List Knowledge sources. Read only. Permission `knowledge.sources.list`.
- `knowledge_sources_search`: Search Knowledge sources by title. Read only. Permission `knowledge.sources.search`.
- `knowledge_sources_archive`: Archive an unpublished knowledge source. Write, destructive. Permission `knowledge.sources.archive`.
- `knowledge_sources_changeAudience`: Change who can read this knowledge source. Write. Permission `knowledge.sources.changeAudience`.
- `knowledge_sources_importConnected`: Import a document from a connected Knowledge source. Write. Permission `knowledge.sources.importConnected`.
- `knowledge_sources_importWebsite`: Import a website page into Knowledge for review. Write. Permission `knowledge.sources.importWebsite`.
- `knowledge_sources_publish`: Publish this knowledge version to its audience. Write. Permission `knowledge.sources.publish`.
- `knowledge_sources_refresh`: Refresh a Knowledge source from its connected provider. Write. Permission `knowledge.sources.refresh`.
- `knowledge_sources_restore`: Restore an archived knowledge source. Write. Permission `knowledge.sources.restore`.
- `knowledge_sources_save`: Save a Knowledge source draft. Write. Permission `knowledge.sources.save`.
- `knowledge_sources_withdraw`: Withdraw a published Knowledge source. Write, destructive. Permission `knowledge.sources.withdraw`.
- `knowledge_sources_write`: Write a Knowledge page with Mello from its title and a request; nothing is saved. Write. Permission `knowledge.sources.write`.
- `knowledge_templates_facts`: Read what Shuffl knows that policy templates ask for. Read only. Permission `knowledge.templates.facts`.
- `knowledge_templates_draft`: Draft a policy template with Mello, researching each value; nothing is saved. Write. Permission `knowledge.templates.draft`.
- `knowledge_uploads_get`: Read the progress of a Knowledge file upload. Read only. Permission `knowledge.uploads.get`.
- `knowledge_uploads_appendPart`: Upload the next part of a Knowledge file. Write. Permission `knowledge.uploads.appendPart`.
- `knowledge_uploads_complete`: Finish a Knowledge file upload and start reading it. Write. Permission `knowledge.uploads.complete`.
- `knowledge_uploads_create`: Start uploading a file to Knowledge. Write. Permission `knowledge.uploads.create`.
- `knowledge_uploads_retry`: Retry reading a Knowledge file that failed. Write. Permission `knowledge.uploads.retry`.
- [Knowledge API reference](https://shuffl.ai/docs/api-reference/knowledge)
## Linked accounts
- `identities_list`: List the Slack and web accounts linked to a person. Read only. Permission `identities.list`.
- `identities_slackAccounts`: List Slack accounts that can be linked to people. Read only. Permission `identities.slackAccounts`.
- `identities_webAccounts`: List web accounts that can be linked to people. Read only. Permission `identities.webAccounts`.
- `identities_linkSlack`: Link a verified Slack account. Write. Permission `identities.linkSlack`.
- `identities_linkWeb`: Link a verified web account. Write. Permission `identities.linkWeb`.
- `identities_unlink`: Revoke an employee identity link. Write, destructive. Permission `identities.unlink`.
- [Linked accounts API reference](https://shuffl.ai/docs/api-reference/identities)
## Manager context
- `manager_current`: Read your own manager context. Read only. Permission `manager.current`.
- [Manager context API reference](https://shuffl.ai/docs/api-reference/manager)
## Mello conversations
- `assistant_conversations`: List your conversations with Mello. Read only. Permission `assistant.conversations`.
- `assistant_history`: Read the messages in one of your conversations with Mello. Read only. Permission `assistant.history`.
- `assistant_delete`: Delete one of your conversations with Mello. Write, destructive. Permission `assistant.delete`.
- `assistant_send`: Ask Mello a question in a conversation. Write. Permission `assistant.send`.
- `assistant_stop`: Stop an answer Mello is still writing. Write, destructive. Permission `assistant.stop`.
- [Mello conversations API reference](https://shuffl.ai/docs/api-reference/assistant)
## Mentorship
- `mentorship_mine`: Your mentorship programs and pairings, with goals and check-ins. Read only. Permission `mentorship.mine`.
- `mentorship_join`: Join a mentorship program as a mentor or mentee, saying what you can help with or want to learn. Write. Permission `mentorship.join`.
- `mentorship_leave`: Leave a mentorship program as a mentor or mentee. Write. Permission `mentorship.leave`.
- `mentorship_checkIns_answer`: Answer whether you met your mentor or mentee, and whether it helped. Write. Permission `mentorship.checkIns.answer`.
- `mentorship_goals_remove`: Remove a goal from your mentorship, as the mentee. Write. Permission `mentorship.goals.remove`.
- `mentorship_goals_save`: Add, rename or check off a goal in your mentorship, as the mentee. Write. Permission `mentorship.goals.save`.
- `mentorship_members_setStatus`: Take someone off a mentorship program, or put them back. Write. Permission `mentorship.members.setStatus`.
- `mentorship_mentors_choose`: Choose your mentor from the mentors Shuffl suggests, in a program where mentees choose. Write. Permission `mentorship.mentors.choose`.
- `mentorship_pairs_decide`: Approve a suggested mentorship pair, which introduces them, or skip it. Write. Permission `mentorship.pairs.decide`.
- `mentorship_pairs_end`: End a mentorship pairing early. Write. Permission `mentorship.pairs.end`.
- `mentorship_pairs_setMine`: Pause, resume or end your own mentorship pairing. Write. Permission `mentorship.pairs.setMine`.
- `mentorship_pairs_suggest`: Suggest a mentor outside their reporting line for every mentee still waiting. Write. Permission `mentorship.pairs.suggest`.
- `mentorship_programs_get`: One mentorship program: who joined, the suggested pairs and whether pairs are meeting. Read only. Permission `mentorship.programs.get`.
- `mentorship_programs_list`: List mentorship programs, with how many mentors, mentees and pairs each has. Read only. Permission `mentorship.programs.list`.
- `mentorship_programs_save`: Create or change a mentorship program: who can join, how long pairings last and how often pairs check in. Write. Permission `mentorship.programs.save`.
- `mentorship_programs_setStatus`: Turn mentorship programs on, pause one, or archive one and end its pairs. Write. Permission `mentorship.programs.setStatus`.
- `mentorship_requests_answer`: Accept or pass on a mentee who chose you as their mentor. Write. Permission `mentorship.requests.answer`.
- `mentorship_sessions_remove`: Remove your notes from a mentorship meeting. Write. Permission `mentorship.sessions.remove`.
- `mentorship_sessions_save`: Add or change your notes from a mentorship meeting: what you talked about and one thing to try. Write. Permission `mentorship.sessions.save`.
- `mentorship_settings_get`: What a new mentorship program starts with: pairing length, check-in cadence and mentees per mentor. Read only. Permission `mentorship.settings.get`.
- `mentorship_settings_save`: Change what a new mentorship program starts with; existing programs keep their own terms. Write. Permission `mentorship.settings.save`.
- [Mentorship API reference](https://shuffl.ai/docs/api-reference/mentorship)
## Network
- `network_introductions`: Your Connections programs, when your next introduction goes out, and who you met. Read only. Permission `network.introductions`.
- `network_mine`: Who you know and who you should meet. Read only. Permission `network.mine`.
- `network_ofPerson`: People you and this person both know. Read only. Permission `network.ofPerson`.
- `network_orgChart`: Everyone in the team with their manager, for the org chart. Read only. Permission `network.orgChart`.
- `network_claim`: Say you know someone or would like to meet them. Write. Permission `network.claim`.
- `network_requestIntro`: Ask someone you both know to introduce you. Write. Permission `network.requestIntro`.
- [Network API reference](https://shuffl.ai/docs/api-reference/network)
## Notifications
- `notifications_preferences`: Read your notification preferences. Read only. Permission `notifications.preferences`.
- `notifications_save`: Save a notification preference. Write. Permission `notifications.save`.
- [Notifications API reference](https://shuffl.ai/docs/api-reference/notifications)
## Operations and audit
- `operations_activity`: Read the workspace's recent audit activity. Read only. Permission `operations.activity`.
- `operations_status`: Read the workspace delivery and provider health summary. Read only. Permission `operations.status`.
- `operations_dispatchInbox`: Resume already-admitted team provider events and support delivery. Write. Permission `operations.dispatchInbox`.
- `operations_reconcile`: Reconcile an externally verified delivery outcome. Write. Permission `operations.reconcile`.
- [Operations and audit API reference](https://shuffl.ai/docs/api-reference/operations)
## People
- `users_activity`: Read a person's recent activity in Shuffl. Read only. Permission `users.activity`.
- `users_blockedPairs`: List pairs of people who are never introduced. Read only. Permission `users.blockedPairs`.
- `users_details`: Read one person's People directory record. Read only. Permission `users.details`.
- `users_filterOptions`: List the teams, departments, managers and locations People can filter by. Read only. Permission `users.filterOptions`.
- `users_get`: Read a person. Read only. Permission `users.get`.
- `users_glance`: Headcount, growth, departments, tenure and time zones, and where you fit. Read only. Permission `users.glance`.
- `users_list`: List people. Read only. Permission `users.list`.
- `users_managerHistory`: Read a person's recorded manager history. Read only. Permission `users.managerHistory`.
- `users_managers`: List the managers in the People directory. Read only. Permission `users.managers`.
- `users_page`: List people in the People directory: search, or filter by team, department, manager, location, access or workspace role such as owner, admin or HR responder. Read only. Permission `users.page`.
- `users_participants`: List the people who take part in programs. Read only. Permission `users.participants`.
- `users_reportingLineProposal`: Read the reporting lines Mello proposed that wait for review. Read only. Permission `users.reportingLineProposal`.
- `users_assignManagers`: Set the manager of several people at once. Write. Permission `users.assignManagers`.
- `users_blockPair`: Stop two people from being introduced to each other. Write, destructive. Permission `users.blockPair`.
- `users_participation`: Opt a person in to or out of a program. Write. Permission `users.participation`.
- `users_profile`: Edit a person's profile as an administrator. Write. Permission `users.profile`.
- `users_proposeReportingLines`: Ask Mello to propose managers for people without one; nothing changes until reviewed. Write. Permission `users.proposeReportingLines`.
- `users_reviewReportingLines`: Approve chosen proposed reporting lines and close the proposal. Write. Permission `users.reviewReportingLines`.
- `users_save`: Change someone's People directory record as an administrator: name, job title, manager, team, department or start date. Write. Permission `users.save`.
- [People API reference](https://shuffl.ai/docs/api-reference/users)
## Playbooks
- `playbooks_buddyCandidates`: Suggested buddies for a new hire: outside their reporting line, volunteers first, with how many hires each is buddying. Read only. Permission `playbooks.buddyCandidates`.
- `playbooks_buddyFollowUps`: Your "did you meet?" questions about a new hire or buddy you were paired with. Read only. Permission `playbooks.buddyFollowUps`.
- `playbooks_buddyProgram`: Buddy volunteers and recent buddies, with how many of their hires said they met and how many never did. Read only. Permission `playbooks.buddyProgram`.
- `playbooks_buddySuggestions`: Suggest coworkers who could be your onboarding buddy. Read only. Permission `playbooks.buddySuggestions`.
- `playbooks_candidates`: List people who could be enrolled in onboarding. Read only. Permission `playbooks.candidates`.
- `playbooks_enrollmentPreview`: Preview enrolling a new hire in onboarding. Read only. Permission `playbooks.enrollmentPreview`.
- `playbooks_firstDaysCheckIns`: Your open 30, 60 or 90-day or one-year new hire check-in. Read only. Permission `playbooks.firstDaysCheckIns`.
- `playbooks_firstDaysResults`: What new hires said in their first 90 days check-ins, combined. Read only. Permission `playbooks.firstDaysResults`.
- `playbooks_mine`: Read your own onboarding plan and buddy asks. Read only. Permission `playbooks.mine`.
- `playbooks_person`: Read a new hire's onboarding plan. Read only. Permission `playbooks.person`.
- `playbooks_plans`: The 30/60/90 plans for new hires you manage, and your own once your manager shares it. Read only. Permission `playbooks.plans`.
- `playbooks_previewAs`: Which steps of a playbook one person would get, on which day, and why each skipped step is left out. Read only. Permission `playbooks.previewAs`.
- `playbooks_program`: Read the Onboarding program settings. Read only. Permission `playbooks.program`.
- `playbooks_run`: One of your playbooks (onboarding or another): day 0, buddy, manager, upcoming check-ins, your to-dos and resources, and the other playbooks you are on. Read only. Permission `playbooks.run`.
- `playbooks_answerBuddyAsk`: Say yes or not now to being a new hire’s onboarding buddy. Write. Permission `playbooks.answerBuddyAsk`.
- `playbooks_answerBuddyFollowUp`: Answer whether you met your buddy or new hire, and whether it helped. Write. Permission `playbooks.answerBuddyFollowUp`.
- `playbooks_answerCheckIn`: Answer your onboarding program’s help check-in: all good, or ask HR for help. Write. Permission `playbooks.answerCheckIn`.
- `playbooks_answerFirstDaysCheckIn`: Answer your new-hire check-in. Write. Permission `playbooks.answerFirstDaysCheckIn`.
- `playbooks_answerForm`: Answer a playbook’s Tell us about you form; the answers fill in your profile. Write. Permission `playbooks.answerForm`.
- `playbooks_approve`: Approve these exact playbook messages for sending. Write. Permission `playbooks.approve`.
- `playbooks_askBuddy`: Ask this coworker to be your onboarding buddy. Write. Permission `playbooks.askBuddy`.
- `playbooks_assignBuddy`: Assign an onboarding buddy to a new hire. Write. Permission `playbooks.assignBuddy`.
- `playbooks_completeTodo`: Check off (or reopen) one of your own playbook to-dos. Write. Permission `playbooks.completeTodo`.
- `playbooks_draftPlan`: Have Mello draft the 30/60/90 plan for a new hire you manage (not yet shared). Write. Permission `playbooks.draftPlan`.
- `playbooks_enroll`: Put this person on a playbook. Write. Permission `playbooks.enroll`.
- `playbooks_nudge`: Send someone one Slack nudge about a hire’s overdue playbook to-dos, at most once a day. Write. Permission `playbooks.nudge`.
- `playbooks_previewEnrollment`: Preview the onboarding steps for a new hire. Write. Permission `playbooks.previewEnrollment`.
- `playbooks_remove`: Remove a new hire from onboarding. Write. Permission `playbooks.remove`.
- `playbooks_respondBuddy`: Accept or decline being an onboarding buddy. Write. Permission `playbooks.respondBuddy`.
- `playbooks_retry`: Retry a failed onboarding step. Write. Permission `playbooks.retry`.
- `playbooks_savePlan`: Write the goals of the 30/60/90 plan for a new hire you manage. Write. Permission `playbooks.savePlan`.
- `playbooks_saveProgram`: Save a playbook: its day 0, steps and messages. Write. Permission `playbooks.saveProgram`.
- `playbooks_setBuddyVolunteer`: Put someone on the buddy volunteer list, take them off it, or clear it. Write. Permission `playbooks.setBuddyVolunteer`.
- `playbooks_setPlanGoal`: Tick a goal on a shared 30/60/90 plan done, or not done. Write. Permission `playbooks.setPlanGoal`.
- `playbooks_sharePlan`: Share the 30/60/90 plan with the new hire you manage. Write. Permission `playbooks.sharePlan`.
- `playbooks_update`: Change a new hire's onboarding start date or time zone. Write. Permission `playbooks.update`.
- `playbooks_volunteerAsBuddy`: Say you are happy to be an onboarding buddy, or stop. Write. Permission `playbooks.volunteerAsBuddy`.
- [Playbooks API reference](https://shuffl.ai/docs/api-reference/playbooks)
## Praise
- `praise_composer`: Read who you can praise, the praise channels and company values. Read only. Permission `praise.composer`.
- `praise_feed`: Read the Praise feed. Read only. Permission `praise.feed`.
- `praise_insights`: Read Praise totals by value (groups of seven or more). Read only. Permission `praise.insights`.
- `praise_mine`: Read praise you gave and received. Read only. Permission `praise.mine`.
- `praise_ofPerson`: Read the public praise one person received. Read only. Permission `praise.ofPerson`.
- `praise_settings`: Read the Praise settings. Read only. Permission `praise.settings`.
- `praise_addChannel`: Read praise from this Slack channel from now on. Write. Permission `praise.addChannel`.
- `praise_removeChannel`: Stop reading praise from a Slack channel. Write. Permission `praise.removeChannel`.
- `praise_saveSettings`: Save the Praise settings and company values. Write. Permission `praise.saveSettings`.
- `praise_send`: Praise coworkers in a praise channel. Write. Permission `praise.send`.
- `praise_setDigest`: Choose whether you get the daily Praise digest. Write. Permission `praise.setDigest`.
- `praise_setHidden`: Hide or show a praise you received. Write. Permission `praise.setHidden`.
- `praise_setRecognition`: Choose whether praise for you is posted publicly or sent to you privately. Write. Permission `praise.setRecognition`.
- [Praise API reference](https://shuffl.ai/docs/api-reference/praise)
## Profiles
- `profiles_get`: Read a person’s profile as this team sees it. Read only. Permission `profiles.get`.
- `profiles_whoKnows`: Find coworkers who know about a topic, place or skill from what they share on their profiles, with the words that matched. Read only. Permission `profiles.whoKnows`.
- `profiles_draft`: Draft the empty parts of your own profile with Mello; nothing is saved. Write. Permission `profiles.draft`.
- `profiles_employeeNumber`: Set a person’s employee number to an unused number. Write. Permission `profiles.employeeNumber`.
- `profiles_save`: Save your own profile: pronouns, location, phone, bio, interests, links and what you are working on. Write. Permission `profiles.save`.
- `profiles_settings`: Choose who sees the optional parts of your own profile. Write. Permission `profiles.settings`.
- `profiles_cover_delete`: Remove your profile cover picture. Write, destructive. Permission `profiles.cover.delete`.
- `profiles_photo_delete`: Remove your profile photo. Write, destructive. Permission `profiles.photo.delete`.
- `profiles_positions_delete`: Remove a past position from your profile. Write, destructive. Permission `profiles.positions.delete`.
- `profiles_positions_save`: Add or change a past position on your profile. Write. Permission `profiles.positions.save`.
- [Profiles API reference](https://shuffl.ai/docs/api-reference/profiles)
## Pulse
- `pulse_actions`: List Pulse actions: what is being done about each result, its owner, due date and before and after. Read only. Permission `pulse.actions`.
- `pulse_asked`: List the Pulse questions asked so far. Read only. Permission `pulse.asked`.
- `pulse_groupTrends`: Read each group's Pulse results over time, period by period, with the change since the start (published group totals only). Read only. Permission `pulse.groupTrends`.
- `pulse_insights`: Read Pulse totals and trends (groups of seven or more). Read only. Permission `pulse.insights`.
- `pulse_latestRead`: Read what stands out in a closed Pulse question’s result. Read only. Permission `pulse.latestRead`.
- `pulse_mine`: Read your own Pulse streak, how many took part, and what changed because of it. Read only. Permission `pulse.mine`.
- `pulse_program`: Read the Pulse settings. Read only. Permission `pulse.program`.
- `pulse_proposals`: List the Pulse questions Mello suggested that wait for approval. Read only. Permission `pulse.proposals`.
- `pulse_questionDetail`: Read one closed Pulse question: its answer spread, every time it was asked, and results by group (groups of seven or more). Read only. Permission `pulse.questionDetail`.
- `pulse_questions`: List the Pulse question library. Read only. Permission `pulse.questions`.
- `pulse_today`: Read today’s Pulse question. Read only. Permission `pulse.today`.
- `pulse_addQuestion`: Add a Pulse question to the library. Write. Permission `pulse.addQuestion`.
- `pulse_addTemplate`: Add a Pulse question set from a template. Write. Permission `pulse.addTemplate`.
- `pulse_answer`: Answer today’s Pulse question as yourself. Write. Permission `pulse.answer`.
- `pulse_createAction`: Plan an action about a closed Pulse question, with an owner and a due date. Write. Permission `pulse.createAction`.
- `pulse_decideProposal`: Approve a suggested Pulse question so it is asked next, or dismiss it. Write. Permission `pulse.decideProposal`.
- `pulse_editProposal`: Reword a suggested Pulse question before approving it. Write. Permission `pulse.editProposal`.
- `pulse_proposeQuestions`: Save drafted Pulse questions as suggestions for HR to approve (never asked until approved). Write. Permission `pulse.proposeQuestions`.
- `pulse_requestProposals`: Ask Mello to suggest Pulse questions from recent results, optionally about a topic. Write. Permission `pulse.requestProposals`.
- `pulse_saveProgram`: Save Pulse settings; enabling Pulse schedules questions to everyone. Write. Permission `pulse.saveProgram`.
- `pulse_setQuestionGroup`: Aim a Pulse question at one of the workspace’s groups, or at everyone. Write. Permission `pulse.setQuestionGroup`.
- `pulse_setQuestionStatus`: Retire or restore a Pulse question. Write. Permission `pulse.setQuestionStatus`.
- `pulse_skip`: Skip today’s Pulse question. Write. Permission `pulse.skip`.
- `pulse_updateAction`: Change a Pulse action’s wording, owner, due date or status. Write. Permission `pulse.updateAction`.
- [Pulse API reference](https://shuffl.ai/docs/api-reference/pulse)
## Reminders
- `reminders_mine`: Read your own Praise and Pulse reminder choices. Read only. Permission `reminders.mine`.
- `reminders_settings`: Read whether Praise and Pulse reminders are on, and their timing. Read only. Permission `reminders.settings`.
- `reminders_saveMine`: Change or turn off your own Praise or Pulse reminders. Write. Permission `reminders.saveMine`.
- `reminders_saveSetting`: Turn a Praise or Pulse reminder on or off, or change its timing. Write. Permission `reminders.saveSetting`.
- [Reminders API reference](https://shuffl.ai/docs/api-reference/reminders)
## Reports and insights
- `reports_answerFeedback`: Read feedback on Mello's answers. Read only. Permission `reports.answerFeedback`.
- `reports_celebrations`: Celebrations sent, people celebrated, birthdays and anniversaries, shared with the team, team cards and notes, share answers and missed messages over 30, 90 or 180 days against the period before, with a weekly series. Read only. Permission `reports.celebrations`.
- `reports_connections`: Read Connections insights. Read only. Permission `reports.connections`.
- `reports_knowledge`: Read Knowledge activity. Read only. Permission `reports.knowledge`.
- `reports_knowledgeSource`: Read activity for one Knowledge source. Read only. Permission `reports.knowledgeSource`.
- `reports_melloTrial`: What Mello handled during the trial, from day 25 of a trial until it ends. Read only. Permission `reports.melloTrial`.
- `reports_melloValue`: What Mello handled this week, this month and all time, with time saved once the team has set its minutes per question. Read only. Permission `reports.melloValue`.
- `reports_mentorship`: Mentorship over 30, 90 or 180 days against the period before: pairs started, ended early and completed, check-ins answered and met, pairs meeting and mentees waiting now; `programId` narrows it. Never goals. Read only. Permission `reports.mentorship`.
- `reports_needsYou`: Read HR request and Knowledge draft insights. Read only. Permission `reports.needsYou`.
- `reports_overview`: Read the workspace overview figures. Read only. Permission `reports.overview`.
- `reports_people`: Read People insights: headcount, teams and growth. Read only. Permission `reports.people`.
- `reports_playbooks`: Read Onboarding insights. Read only. Permission `reports.playbooks`.
- [Reports and insights API reference](https://shuffl.ai/docs/api-reference/reports)
## Requests Mello filed
- `actions_mine`: List the requests Mello filed for you and where each stands. Read only. Permission `actions.mine`.
- [Requests Mello filed API reference](https://shuffl.ai/docs/api-reference/actions)
## Shuffl support
- `support_get`: Read one Shuffl support conversation. Read only. Permission `support.get`.
- `support_list`: List the workspace's support conversations with Shuffl. Read only. Permission `support.list`.
- `support_assign`: Assign a Shuffl support conversation. Write. Permission `support.assign`.
- `support_close`: Close a Shuffl support conversation. Write, destructive. Permission `support.close`.
- `support_create`: Start a support conversation with Shuffl. Write. Permission `support.create`.
- `support_reply`: Reply in a Shuffl support conversation. Write. Permission `support.reply`.
- [Shuffl support API reference](https://shuffl.ai/docs/api-reference/support)
## Slack channels
- `channels_list`: List available Slack channels. Read only. Permission `channels.list`.
- [Slack channels API reference](https://shuffl.ai/docs/api-reference/channels)
## Time off
- `timeOff_balances`: Read your own time-off balances from the connected HR system. Read only. Permission `timeOff.balances`.
- [Time off API reference](https://shuffl.ai/docs/api-reference/time-off)
## Webhooks
- `webhooks_catalog`: List the webhook event types and which ones this key can subscribe to. Read only. Permission `webhooks.catalog`.
- `webhooks_get`: Read one webhook endpoint. Read only. Permission `webhooks.get`.
- `webhooks_list`: List webhook endpoints, their status and delivery success over 24 hours. Read only. Permission `webhooks.list`.
- `webhooks_create`: Add a webhook endpoint that receives the chosen events, and get its signing secret. Write. Permission `webhooks.create`.
- `webhooks_delete`: Delete a webhook endpoint and its delivery log. Write, destructive. Permission `webhooks.delete`.
- `webhooks_rotateSecret`: Roll a webhook endpoint’s signing secret, keeping the old one valid for a while. Write. Permission `webhooks.rotateSecret`.
- `webhooks_sendTest`: Send a webhook.test event to an endpoint now. Write. Permission `webhooks.sendTest`.
- `webhooks_update`: Change a webhook endpoint’s URL, description or events, or turn it on or off. Write. Permission `webhooks.update`.
- `webhooks_deliveries_get`: Read one webhook delivery: the request body and every attempt’s answer. Read only. Permission `webhooks.deliveries.get`.
- `webhooks_deliveries_list`: List an endpoint’s webhook deliveries, newest first. Read only. Permission `webhooks.deliveries.list`.
- `webhooks_deliveries_replay`: Resend one webhook delivery with the same event id. Write. Permission `webhooks.deliveries.replay`.
- `webhooks_deliveries_replayFailed`: Resend every failed webhook delivery of an endpoint since a time. Write. Permission `webhooks.deliveries.replayFailed`.
- [Webhooks API reference](https://shuffl.ai/docs/api-reference/webhooks)
## What Mello can do
- `capabilities_requests`: How many people asked HR to connect a system, per capability. Read only. Permission `capabilities.requests`.
- `capabilities_sheet`: What Mello can answer and do for you here, and what connecting a system would add. Read only. Permission `capabilities.sheet`.
- `capabilities_unlocks`: What people can ask and do once an HR system or document tool is connected. Read only. Permission `capabilities.unlocks`.
- `capabilities_dismissRequests`: Clear the asks to connect a system for one capability. Write. Permission `capabilities.dismissRequests`.
- `capabilities_requestConnection`: Ask HR to connect the system this needs. Write. Permission `capabilities.requestConnection`.
- [What Mello can do API reference](https://shuffl.ai/docs/api-reference/capabilities)
## Workspace
- `teams_connectionPermissions`: List connections whose permissions are behind what Shuffl asks for. Read only. Permission `teams.connectionPermissions`.
- `teams_setup`: Read the workspace's setup checklist. Read only. Permission `teams.setup`.
- `teams_slackChannels`: List community channels in the connected Slack and what each would become. Read only. Permission `teams.slackChannels`.
- `teams_slackConnection`: Read whether the workspace's Slack is connected, and why not. Read only. Permission `teams.slackConnection`.
- `teams_slackJoinAccess`: Read whether Slack members can join Shuffl on their own. Read only. Permission `teams.slackJoinAccess`.
- `teams_slackProfileLink`: Read the Shuffl profile link setting for Slack profiles. Read only. Permission `teams.slackProfileLink`.
- `teams_discardPairHistory`: Remove this staged past-intros report. Write. Permission `teams.discardPairHistory`.
- `teams_initialize`: Finish setting up a new workspace. Write. Permission `teams.initialize`.
- `teams_moveSlackChannels`: Set up each channel in Shuffl: paused intros, praise and celebrations. Write. Permission `teams.moveSlackChannels`.
- `teams_rename`: Rename the workspace. Write. Permission `teams.rename`.
- `teams_resendSlackWelcome`: Send the Slack install welcome to your own Slack DM again. Write. Permission `teams.resendSlackWelcome`.
- `teams_saveAgentSetup`: Choose the built-in assistant or an external agent for the workspace. Write. Permission `teams.saveAgentSetup`.
- `teams_saveSlackJoinAccess`: Choose whether Slack members can join Shuffl on their own. Write. Permission `teams.saveSlackJoinAccess`.
- `teams_saveSlackProfileLink`: Turn the Shuffl profile link on Slack profiles on or off. Write. Permission `teams.saveSlackProfileLink`.
- `teams_status`: Pause or resume the whole workspace. Write. Permission `teams.status`.
- `teams_syncSlackProfileLinks`: Write the Shuffl profile link to every Slack profile again. Write. Permission `teams.syncSlackProfileLinks`.
- `teams_uploadPairHistory`: Stage this past-intros report for the switch; nothing changes until it is applied. Write. Permission `teams.uploadPairHistory`.
- [Workspace API reference](https://shuffl.ai/docs/api-reference/teams)
## Workspace launch
- `team_launchPost`: Read the launch announcement for the workspace. Read only. Permission `team.launchPost`.
- `team_answerMinutes`: Set the team estimate of minutes per HR question, used for time saved. Write. Permission `team.answerMinutes`.
- `team_dismissLaunchPost`: Dismiss the Tell your team what they can ask post on Today for everyone. Write. Permission `team.dismissLaunchPost`.
- [Workspace launch API reference](https://shuffl.ai/docs/api-reference/team)
## Related guides
- [Connect an MCP client](https://shuffl.ai/docs/mcp)
- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)
- [REST API reference](https://shuffl.ai/docs/api-reference)
Agent documentation index: https://shuffl.ai/llms.txt
---
# SDK and CLI changelog
> What changed in each version of @shuffl/sdk, @shuffl/cli and @shuffl/api-contracts, and how versions and breaking changes work.
Audience: Developers who use the SDK, CLI or API contracts
Kind: Reference
Canonical: https://shuffl.ai/docs/sdk-changelog
## Versions and breaking changes
The SDK, the CLI and the API contracts share one version number and are released together. Upgrade the SDK and CLI at the same time, and pin an exact version in your project.
While the major version is 0, a minor release such as 0.2.0 to 0.3.0 can rename or remove operations and fields. A patch release such as 0.2.0 to 0.2.1 never does. Each version below lists breaking changes first, under Breaking. Read them before you upgrade.
The hosted API always runs the newest contract. An older SDK or CLI keeps working for every operation that hasn’t changed, but a call to an operation or field that was renamed or removed fails until you upgrade.
Release candidates, such as 0.4.0-rc.1, are published under the next tag. Install one with @shuffl/sdk@next. shuffl --version prints the version you have.
```sh
npm install @shuffl/sdk@0.7.6 @shuffl/cli@0.7.6
shuffl --version
```
## 0.7.6 (2026-10-18)
### Added
- Mentees choose their mentor: `mentorship.programs.save` takes `menteesChoose`. In such a program `mentorship.mine` returns each waiting mentee's `choices` (up to three mentors with `topics` and `reasons`) and the mentor they `requested`; `mentorship.mentors.choose` (`mentorship.chooseMentor`, `programId`, `mentorId`) asks that mentor. Mentors see `requests` in `mentorship.mine` and answer with `mentorship.requests.answer` (`mentorship.answerRequest`, `decision` accept or pass). Program summaries return `menteesChoose` and `requested`; pairs can be `requested`.
- Session notes: `mentorship.sessions.save` (`mentorship.saveSession`, `pairId`, `heldOn`, `notes`, `nextStep`, optional `sessionId`) and `mentorship.sessions.remove` (`mentorship.removeSession`). Each pair in `mentorship.mine` returns its `sessions`, a `prep` (the newest `nextStep`, `openGoals`, `questions` and `stage`) and its `nextMeeting`. Only the two people in the pair read notes. Keys with `self:write`.
- Calendar targets take `mentorship_pair` (a pair id) for Pick a time between a mentor and mentee.
## 0.7.5 (2026-10-18)
### Changed
- `reports.playbooks` and `praise.insights` return `previous`: the same counts for the window before the one asked for (`null` when there is nothing to compare), so a client can show the change since then without a second call.
## 0.7.4 (2026-10-18)
### Added
- Requests Mello filed outside Shuffl: `actions.mine` (`self:read`) lists what Mello filed for the asking person in a connected HR system and where each one stands (`status` `submitted`, `approved`, `declined`, `cancelled`, `failed` or `unknown`, with `statusLabel`, `provider`, `providerName`, `details` such as the time-off policy and dates, `vendorUrl`, `submittedAt`, `settledAt` and `cancellable`). Only the person's own; a key with `self:read`.
- `sync.setWrites` (`integrations:write`) turns a People Sync connection's write switch on or off: off, Mello files nothing there and sends the person's request to HR instead; reads carry on. `sync.current` connections now return `writes` (`offered`, `enabled`).
## 0.7.3 (2026-10-18)
### Changed
- Mello's read as figures: `pulse.latestRead` also returns `delta`, the change since the question was last asked (`change`, `direction` `up`/`down`/`flat`/`new`, `tone` `good`/`bad`/`neutral`/`watch`, `text` such as `↓ 6 pts`; moves under 5 points read neutral), and `gap`, the lowest and highest published group with the `points` between them, or null when the gap is under 15 points. Both are null when the result is withheld.
## 0.7.2 (2026-10-18)
### Added
- What Mello can do: `capabilities.sheet` returns the rows Mello can answer (`kind: 'ask'`) and do (`kind: 'do'`) for the key's person in this workspace, each with `say` (what to ask), `result`, `system` (Shuffl or the connected system's name) and `status` (`available`, `needs_connection`, `needs_setup` or `coming`), plus `need` when it doesn't work yet. `capabilities.unlocks` lists what an HR system or document tool adds once connected. `capabilities.requestConnection` (`self:write`) asks HR to connect what a `needs_connection` row needs; administrator keys read the open asks per capability with `capabilities.requests` (`integrations:read`) and clear them with `capabilities.dismissRequests` (`integrations:write`). Asks carry counts, never names.
## 0.7.1 (2026-10-18)
### Added
- Celebrations insights: `reports.celebrations` (`reporting.celebrationInsights`) returns, for the last 30, 90 or 180 days (`days`, default 90) and the same period before, celebrations sent (`sent.current.total`, with `people`, `birthdays`, `anniversaries` and `shared` with a channel or team), team cards delivered and the notes on them (`cards`), share answers (`consent.share`, `consent.private`, `consent.waiting`), messages that failed or were skipped (`missed`) and a `weekly` series of birthdays and anniversaries. Counts only. Administrator keys with `reports:read`.
## 0.7.0 (2026-10-18)
### Changed
- The CLI reads a workspace key from `SHUFFL_API_KEY` instead of `SHUFFL_TOKEN` (breaking), matching the SDK's `apiKey` option. `SHUFFL_COMPANY_KEY` and `SHUFFL_BASE_URL` are unchanged. The README, guides, cookbook and API reference use the new name.
## 0.6.5 (2026-10-18)
### Changed
- Playbook steps before day 1 go by email. `playbooks.enrollmentPreview` steps return `byEmail`: true when the step goes to a hire whose Slack isn't ready yet, so it goes by email to their work email until it is. Meet steps and check-ins never go by email.
## 0.6.4 (2026-10-18)
### Added
- Mentorship insights: `reports.mentorship` (`reporting.mentorshipInsights`, `days` 30, 90 or 180, optional `programId`) returns `current` and `previous` periods with `pairs` (`started`, `endedEarly`, `completed`) and `checkIns` (`answered`, `met`, `asked`, `finals`, `helped`), `now` (`meeting`, `paused`, `suggested`, `waiting`) and `weekly` `pairs` and `checkIns`. Counts only, never goals. Administrator keys with `reports:read`.
- Mentorship settings: `mentorship.settings.get` returns the `settings` a new program starts with (`pairingWeeks`, `checkInWeeks`, `mentorCapacity`), Shuffl's `defaults` and `updatedAt`; `mentorship.settings.save` changes them (`mentorship:write`) and returns `changed` and `custom`.
### Changed
- `mentorship.programs.save` takes `pairingWeeks`, `checkInWeeks` and `mentorCapacity` as optional: a new program left without them starts with the workspace's mentorship settings, and an existing one keeps what it has.
## 0.6.3 (2026-10-18)
### Added
- Automation insights: `groups.automationInsights` counts group automation runs finished in the last `days` (30, 90 or 180) against the period before: `current` and `previous` with `done`, `skipped`, `failed` and `people` reached, `weekly`, `byKind`, the top five `reasons` a run was skipped or failed (`code`, `why`, `outcome`, `n`), runs still `scheduled` and `automations` on of total. `groupId` narrows it. Administrator keys with `users:read`.
## 0.6.2 (2026-10-18)
### Changed
- The READMEs list what the SDK client covers, resource by resource, and say how the packages are licensed. Operation descriptions and release notes no longer cite internal tracker numbers.
## 0.6.1 (2026-10-18)
### Added
- The SDK and CLI name their release on every request in an `x-shuffl-client` header (`shuffl-sdk/0.6.1`, and for the CLI `shuffl-cli/0.6.1 shuffl-sdk/0.6.1`), so Shuffl can count requests by client and release. `new Shuffl()` takes an optional `client`, such as `billing-sync/1.2.0`, which goes in front; Shuffl never stores that part. No operation changed.
## 0.6.0 (2026-10-18)
### Changed
- One client for every key (breaking): `new Shuffl({ apiKey })` replaces `createShuffl` and `createShufflCompany`, which are removed. A workspace key (`shuffl_api_`) calls the workspace methods at the top level (`shuffl.users.list()`); a company key (`shuffl_company_`) calls the company methods under `shuffl.company` (`shuffl.company.members.list()`). The client reads the key's prefix and refuses the other kind's methods with `UNAUTHORIZED` before sending a request. `token` is now `apiKey` (a string or a function that returns one), and `baseUrl` is optional, defaulting to production. The CLI and HTTP API are unchanged.
## 0.5.12 (2026-10-18)
### Added
- Automation runs, a page at a time: `groups.automationRuns` lists every group automation run in the workspace newest first, 50 at a time, each with `personId`, `name`, `groupId`, `groupName`, `kind`, `trigger`, `outcome`, `why`, `at` and `dueAt`. `next` is the cursor for the next page (null on the last); `counts` gives every run by outcome (`scheduled`, `done`, `skipped`, `failed`). `outcome` and `groupId` narrow it. Administrator keys with `users:read`.
## 0.5.11 (2026-10-18)
### Changed
- Leaving playbooks start on their own: `groups.setPlaybookAutoStart` now takes a playbook counted from each person's last day (`dayZero: 'last_day'`) as well as one counted from each start date, and `playbooks.savePlaybookProgram` accepts `autoStart` on one. When People Sync or People gives someone a last day ahead, they start it within ten minutes, with steps waiting for approval; someone removed is not added back for that last day. `groups.allAutomations` `playbookStarts` return `dayZero` (`start_date` or `last_day`).
## 0.5.10 (2026-10-18)
### Added
- Pulse group results over time: `pulse.groupTrends` (`pulse:read`, `days` 30, 90 or 180) returns each group's published, frozen totals period by period (`unit` `week`, `fortnight` or `month`, with `periods`), for `everyone` and every `dimensions` row (department, role, tenure, group). Each row's `series` has one entry per `metric` (`favourable`, `enps` or a driver) with `points` (`value`, null when withheld; `seen`), `latest` and `change` since the first published point. eNPS points follow `enpsPeriods`, the last eight eNPS questions.
## 0.5.9 (2026-10-18)
### Added
- Playbook form steps: a written step in `playbooks.saveProgram` can be `kind: 'form'`, going to the hire (`recipient: 'hire'`, no to-dos) with `formFields`, any of `preferredName`, `pronouns`, `bio`, `birthday` and `photo`. The hire answers with `playbooks.answerForm` (`stepId`, plus `preferredName`, `pronouns`, `bio` and `birthday` `{ month, day }` or `null`); answers write to their profile and Celebrations birthday under their own privacy settings, and the step records only when it was answered. `playbooks.mine` steps return `form` (`fields`, `answeredAt`) and the run returns `formValues`. Profiles take and return `preferredName`.
## 0.5.8 (2026-10-18)
### Added
- Slack channel automations: `groups.setAutomation` takes `kind` `slack_invite` (add each person to a channel) and `slack_post` (post that they joined, with an optional `config.note`; joins only). `config.channelId` must be a channel Shuffl is in: the API reads it back from Slack and saves `config.channelName` itself. Automations return the channel as `target` (`#name`). The Slack call runs from a queue after the run is written; a refusal turns the run `failed` with Slack's reason as `code`, such as `not_in_channel`, and someone with no linked Slack account is `skipped` with `no_slack`.
## 0.5.7 (2026-10-18)
### Added
- Mentorship programs. Administrators (`mentorship:read`, `mentorship:write`): `mentorship.programs.list` and `mentorship.programs.get` (`programId`: the program with `members`, each with `role` `mentor` or `mentee`, `topics`, `status` and open `pairs`, and `pairs` with `mentor`, `mentee`, `reasons`, `status`, dates, `checkIns` counts and `final` answers; never goals). `mentorship.programs.save` (`name`, `description`, `groupId` or null for everyone, `pairingWeeks` 4 to 52, `checkInWeeks` 1 to 8, `mentorCapacity` 1 to 5) and `mentorship.programs.setStatus` (`active`, `paused` or `archived`, which ends open pairs). `mentorship.pairs.suggest` suggests one mentor for every waiting mentee, never in their reporting line; `mentorship.pairs.decide` (`pairId`, `decision` `approve` or `skip`) starts a pair and introduces both people; `mentorship.pairs.end` ends one early; `mentorship.members.setStatus` takes someone off a program (`removed`) or puts them back. Everyone (`self:read`, `self:write`): `mentorship.mine` lists the programs open to the key's person and their pairings with `goals` and `checkIns`; `mentorship.join` (`programId`, `role`, `topics`) and `mentorship.leave`; `mentorship.pairs.setMine` (`pairId`, `status` `active`, `paused` or `ended`); `mentorship.goals.save` and `mentorship.goals.remove` for the mentee's goals (up to 5); `mentorship.checkIns.answer` (`checkInId`, `answer` `helped`, `met` or `not_yet`). Notification kind `mentorship`. `badges.list` includes the automatic `Mentor` badge for finishing a pairing as the mentor.
### Changed
- `home.places` can return `mentorship` when a mentorship program is running or a check-in waits for the person.
## 0.5.6 (2026-10-18)
### Added
- More group automations: `groups.setAutomation` takes `kind` `ask_pulse` (`config.questionId`), `give_badge` (`config.badgeId`), `add_to_group` and `remove_from_group` (`config.targetGroupId`, a Shuffl list) and `tell_person` (`config.personId`, optional `config.note`), and `delayDays` (0 to 365) to run that many days after the join or leave. Automations return `delayDays`, `when` and `target` for the new kinds; runs can be `scheduled` with a `dueAt`, and `groups.allAutomations` totals add `scheduled`. A run that comes due after the person moved back is `skipped` with code `moved_back`. `groups.automationChoices` lists the Pulse `questions` (`id`, `text`, `retired`), `badges` and `groups` an automation can use. Pulse questions an automation asks gather in a send of its own that stays open four weeks and closes a week later, under the reporting floor.
## 0.5.5 (2026-10-18)
### Added
- Playbook meet steps: a written step in `playbooks.saveProgram` can be `kind: 'meet'`, going to the hire (`recipient: 'hire'`, no to-dos) with `meet` set to `manager`, `skip_level` (their manager's manager), `person` (with `personId`) or `teammates` (with `meetCount`, 1 to 5: people with the same manager, longest here first). Who they meet is resolved from People when the steps are reviewed and approved: `playbooks.enrollmentPreview` and `playbooks.previewAs` steps return `meets` (names; empty when People has nobody, which skips the step at approval). The step sends one Slack group message with a card for each person and Pick a time. Calendar targets take `kind: 'playbook_meet'` with `id` `.`, and bookings return `from` (`person`, `group`, `playbook` or `playbook_meet`). `playbooks.mine` returns `met`, the people meet steps introduced the hire to.
## 0.5.4 (2026-10-17)
### Added
- Playbook tracks: written steps in `playbooks.saveProgram` take `onlyFor` and `notFor` (up to 5 group ids each, from `groups.list`; empty is everyone). A step only for groups goes to people in any of them, and a step not for a group never goes to its people. Groups are checked against People when the steps are reviewed and at approval: `playbooks.enrollmentPreview` steps return `track` (why this person doesn't get it, such as `Only for Engineering`, or null), a People change before approval fails `playbooks.approve` until the steps are reviewed again, and approved steps a track leaves out are skipped with no to-dos. `playbooks.program` returns `tracks` (each group the steps name, with `id`, `name`, `kind`, `department`, `rules` in words or null, `only` and `not` step counts and `hires` on the playbook now in it). `playbooks.previewAs` (`programId`, `personId`) returns the steps one person would get, without enrolling them: `dayZero`, `person`, `steps` (each with `ref`, `title`, `kind`, `offsetDays`, `dueAt`, `recipient`, `track` and `skipped`, why they wouldn't get it), `skipped` and `tracked`.
## 0.5.3 (2026-10-17)
### Added
- Connections for employees: `network.introductions` returns the key's own `programs` (each Connections program that introduces them, with `id`, `name`, `nextAt`, null while paused, and `breakUntil`), `past` (their latest introductions, each with `id`, `at`, `program` and `with`: the other people, `id`, `name`, `title`, `photoUrl` and `slackUserId`) and `total`. Nothing about other people's introductions or matches not yet sent. `home.places` can include `connections`.
## 0.5.2 (2026-10-17)
### Added
- One list of join and leave rules: `groups.allAutomations` also returns `playbookStarts` (each playbook that starts on each new hire's start date: `playbook` with `id`, `name` and `status`, `group` or null for everyone, `state` `active` or `paused`, `runs`, `runs30` and `lastRunAt`) and `programRosters` (each Connections program whose people are a group: `program`, `group` and `state`). `groups.setPlaybookAutoStart` (`programId`, `state` `active`, `paused` or `off`, optional `groupId`, null for everyone) turns a playbook's start-date rule on, pauses it keeping its group, or removes it. Playbooks return `playbook.autoStartPaused`; a paused playbook starts nobody until it is turned back on.
## 0.5.1 (2026-10-17)
### Added
- Playbook Hires view: `playbooks.program` returns `hires` (`active`, `onTime` percent of to-dos done by a day after their day or null, `overdue`, `askedForHelp`) and each active row's `progress` (`day` from day 0, `done`, `total`, `next` step `title` and `at`, `overdue` to-dos grouped by owner with `ownerId`, `ownerName`, `role` `hire`, `manager`, `buddy` or `other`, `count`, `since` and `nudgedAt`, `unconfirmed` read-and-confirm pages and `help`). `playbooks.nudge` (`enrollmentId`, `ownerPersonId`) sends that person one Slack reminder with their overdue to-dos for the hire and returns `status` `sent`, `recent` (already nudged today), `nothing_overdue`, `off`, `no_slack` or `failed`.
## 0.5.0 (2026-10-17)
- `playbooks`: `answerBuddyAsk`, `answerBuddyFollowUp`, `answerCheckIn`, `answerFirstDaysCheckIn`, `approve`, `askBuddy`, `assignBuddy`, `buddyCandidates`, `buddyFollowUps`, `buddyProgram`, `buddySuggestions`, `candidates`, `completeTodo`, `draftPlan`, `enroll`, `enrollmentPreview`, `firstDaysCheckIns`, `firstDaysResults`, `mine`, `person`, `plans`, `previewEnrollment`, `program`, `remove`, `respondBuddy`, `retry`, `run`, `savePlan`, `saveProgram`, `setBuddyVolunteer`, `setPlanGoal`, `sharePlan`, `update`, `volunteerAsBuddy` - `onboarding`: `answerBuddyAsk`, `answerCheckIn`, `approve`, `askBuddy`, `assignBuddy`, `buddySuggestions`, `candidates`, `completeTodo`, `mine`, `person`, `remove`, `respondBuddy`, `retry`, `update` (removed)
### Breaking
- Playbooks everywhere. The `onboarding.*` operations are now `playbooks.*`, with the same inputs and outputs. `onboarding.journey`, a person's run through a playbook, is `playbooks.run`, and `reports.onboarding` is `reports.playbooks`. The `onboarding:read` and `onboarding:write` scopes are `playbooks:read` and `playbooks:write`; existing keys and connections keep their access under the new names. Webhook event types `onboarding.*` are `playbooks.*` (such as `playbooks.enrolled` and `playbooks.step.sent`), and subscribed endpoints were moved over. Values that said onboarding or journey say playbook: program and draft `kind` `playbook`, the `playbook` config on `playbooks.saveProgram`, `playbooks.program` and `programs.*`, group automation and Culture nudge kind `start_playbook`, reminder kind `playbook_todo`, notification kind `playbook`, citation kind `playbook`, person activity kinds `playbook_started` and `playbook_completed`, `playbookMessagesSent`, and the `playbooks` list on `playbooks.run`.
- Departments are groups. Every department is now a group (same id) marked `department` in `groups.*`, and a person is in one department at most. `units.save` and `units.archive` are gone: create a department with `groups.save` (`kind` `list`, `department` true, people in `personIds`), rename it with `groups.save` and remove it with `groups.remove`; departments are no longer archived. `units.list` takes no `archived` and returns `id`, `name` and `members` for each department. `groups.list`, `groups.get` and the other group reads return `department`. A department group is never `onProfile` or the HR team and can't be a rules group. `users.save` still sets a person's department with `departmentId` (a department group's id), and `users.page`'s `departmentId` filter reads department groups. Program `unitIds`, knowledge audience `units` and group rules on `department` keep working with the same ids. `exports.team` no longer returns `organizationUnits` or `unitMemberships`: departments are in `peopleGroups` and `peopleGroupMembers` with `department` true, and an older export that carries them still imports. The `directory.unit.created`, `directory.unit.updated` and `directory.unit.archived` webhook events are gone, since nothing sends them; read departments with `units.list` or `groups.list`. An endpoint subscribed to them keeps its other events, and saving it drops them.
- Teams are groups. Every team is now a group (same id) in `groups.*`, and `units.*` covers departments only: `units.list` and `units.save` no longer return `kind`, `hrTeam` or `slackUserGroupId`, and `units.save` takes no `kind`. Groups return `source` (`shuffl`, `slack` or `directory`: synced groups have read-only members), `onProfile` (shown on profiles and the org chart, as teams were) and `hrTeam` (the group that answers HR requests); `groups.save` takes `onProfile`, and refuses member or rule changes on a synced group. `users.details` returns `department` and `groups` instead of `units`, and `users.save` takes `groupIds` instead of `teamIds`. `users.page` filters by `groupId` instead of `directoryTeamId`; `users.filterOptions` and `programs.options` return `units` of kind `department` or `group`. `profiles.get` and `network.orgChart` return `groups` instead of `teams`. Pulse results no longer split by team: `pulse.insights` and `pulse.questionDetail` drop the `team` dimension, and former team results are under `group`. `digest.culture` returns `focus.kind` `department` or `group`. A group rule `team is X` becomes `segment` (In group). `exports.team` returns `peopleGroups` and `peopleGroupMembers`.
- Pulse questions go to a group, not an audience. `pulse.addQuestion` takes `groupId` (one of the workspace's groups, or null for everyone) instead of `audience`, and `pulse.setQuestionGroup` (`questionId`, `groupId`) replaces `pulse.setQuestionAudience`. `pulse.audienceOptions` is gone: pick from `groups.list`. `pulse.questions`, `pulse.questionDetail`, `pulse.actions`, `pulse.action` and `pulse.insights` return `groupId` and `groupLabel` where they returned `audience` and `audienceLabel`. eNPS still goes to everyone.
### Added
- `users.page` rows return `directory`: `jobTitle` from the directory for every key, and `startDate` (a calendar date) for administrator keys only, null for everyone else.
- New hire 30/60/90 plans: `playbooks.plans` lists the plans for the new hires the key's person manages (`asManager`: each new hire playbook episode with `hire`, `startDate`, `programName` and `plan` or null) and their own plan once shared (`asHire`). `playbooks.draftPlan` has Mello draft three goals per stage (`draftedBy` `ai`, or `rule` without a model); `playbooks.savePlan` (`enrollmentId`, `expectedRevision`, `goals` with `stage` 30, 60 or 90 and `text`, at most 5 per stage) edits them; `playbooks.sharePlan` shows the plan to the hire; `playbooks.setPlanGoal` (`goalId`, `done`) ticks a goal off, for the manager or the hire. Only the hire and their manager in People change a plan. `playbooks.program` rows return `plan` (`state` `none`, `draft` or `shared`, `done`, `total`, and `goals` with `stage`, `text` and `done` for HR to read) on new hire playbooks. Mello now drafts each new hire's plan by itself when they join a playbook counted from their start date, and plans return `autoDrafted`.
- Buddy program health: `playbooks.buddyCandidates` (`personId`) suggests up to five buddies for a new hire, never anyone in their reporting line, volunteers first, each with `reasons`, `volunteer` and `load` (`active`, `total`). `playbooks.volunteerAsBuddy` (`volunteer`) puts the key's person on the buddy volunteer list or takes them off; `playbooks.setBuddyVolunteer` (`personId`, `status` `volunteer`, `removed` or `none`) is HR's version, and only HR undoes `removed`. `playbooks.buddyProgram` lists volunteers and recent buddies with `status`, `load`, `hiresAnswered`, `hiresMet`, `hiresHelped` and `neverMet`. `playbooks.buddyFollowUps` and `playbooks.answerBuddyFollowUp` (`feedbackId`, `answer` `helped`, `met` or `never`) are the "did you meet?" question sent to the hire and buddy on the playbook's `buddyFollowUpOffsetDays` (default 30). Onboarding playbooks also take `buddyTopics`, the list sent to the buddy with the invitation.
- Add people by department or community: `playbooks.previewEnrollment` and `playbooks.enroll` take `departmentId` (everyone in a department) or `communityId` (everyone who shows a community on their profile) beside `groupId`; one at a time, and people already on the playbook are left out.
- Playbooks that start automatically: `playbooks.saveProgram` takes, and `playbooks.program` and `programs.*` return, `playbook.autoStart` (default `false`) and `playbook.autoStartGroupId` (a group, or null for everyone). Only a playbook whose `dayZero` is `start_date` can start automatically. Once it is on, everyone People gives a start date ahead (People Sync or an edit) starts it within ten minutes, with steps waiting for approval as `playbooks.enroll` leaves them. Each person starts it once per start date: someone removed is not added back, and a new start date is a new episode.
- Every group automation in one list: `groups.allAutomations` returns each automation of the workspace with its `group` (`id`, `name`, `kind`, `members`) beside the fields `groups.automations` returns, `totals` (`active`, `paused`, `groups`, and `done30`, `skipped30`, `failed30` runs in the last 30 days) and the latest 20 `runs` across groups with `groupName`. `targetId` keeps only the automations that start that playbook or program or invite to that community. `groups.list` and `groups.get` return `automations`, how many of the group's automations are on.
- Read and confirm in playbooks: a playbook step can be `kind` `acknowledge` in `playbooks.saveProgram`, naming one published Knowledge page in `resources` and going to the `hire`. Once it goes out, the person confirms the page in the app as for a policy confirmation; `playbooks.program` returns each such step's `answeredAt` and `acknowledgedVersionId`, and `playbook.journey` returns `page` and `confirmedAt` on its steps.
- Praise in the network and badges: `network.mine` suggestions carry `praised` (true when the two people thanked each other, or one thanked the other, in public praise in the last year) and list the reason first (`Praised you`, `You praised them` or `You praised each other`); it stays a suggestion until both say they know each other. `badges.list` includes three automatic badges for being thanked in public praise: `First thanks`, `Thanked across teams` (from three departments) and `Lives our values` (five thanks for one value).
- Connections from communities: `programs.create` and `programs.update` take `communityIds` (1 to 20 of the workspace's communities) so a program's people come from those communities instead of everyone in the Slack channel or a group; a program uses one of the three, and choosing a group or communities in an update replaces the other. Only members who show the community on their profile take part, read again before each round; introductions are still posted in the program's channel. `match.unitKind` takes `community`, so `cross-unit` mixes people from different communities and `within-unit` keeps each group inside one (within a program's own communities when it has them). `programs.get` and `programs.list` return `communityNames`, `programs.options` returns `communities` (`id`, `name`, `memberCount` of members who show it) and `programs.communities` lists the same.
- How people like to be thanked: `praise.setRecognition` (`recognition`: `public` or `private`) sets the key's own choice; choosing private hides praise they already received from their profile and the feed, and returns how many were `hidden`. `praise.mine` returns `recognition` and `notes` (`received` and `given` private notes, each with `id`, `giver`, `recipient`, `text`, `values` and `sentAt`). `praise.send` takes `privately` (send each person a private note instead of posting) and sends a private note to anyone who prefers one; it returns `posted`, `privateNotes`, `notSent` (names Slack refused a note to) and a `praiseId` that is null when nothing was posted. `praise.insights` returns `teams` and `locations` beside `departments`, each row with `low` when under `coverageLow` percent were recognized, and counts private notes as recognition. `praise.settings` and `praise.saveSettings` carry `managerNudges`.
- SCIM groups: a group's `source` can be `scim`, a synced group whose members follow the identity provider. `sync.groups` and `sync.setGroup` take a SCIM connection's id too (from `sync.current`, `provider` `scim`, `connection.source` `scim`) when called by a signed-in company administrator: `imported` brings the group into every workspace of the company, `onProfile` applies to this workspace, and `syncing` is always false because members arrive at once; like other synced groups, its members are read-only in `groups.save` and `users.save`.
- Outgoing webhooks: `webhooks.list`, `webhooks.get`, `webhooks.catalog`, `webhooks.create`, `webhooks.update`, `webhooks.delete`, `webhooks.rotateSecret`, `webhooks.sendTest`, `webhooks.deliveries.list`, `webhooks.deliveries.get`, `webhooks.deliveries.replay` and `webhooks.deliveries.replayFailed`, under the new `webhooks:read` and `webhooks:write` scopes. `create` takes a public `https://` `url`, an optional `description` and `events` (catalog types; each group needs its read scope, such as `knowledge:read` for `knowledge.*` and `hr:read` for `hr.*`), and returns the `endpoint`, its signing `secret` (`whsec_…`, shown only here and from `rotateSecret`) and the `testDeliveryId` of the `webhook.test` it queues. `rotateSecret` takes `keepOldFor` (`now`, `1h`, `24h` or `7d`); both secrets sign until then. Deliveries follow Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) with retries for a little over a day. The SDK exports `verifyWebhook({ body, headers, secret })`, `signWebhook`, `webhookEventCatalog`, `webhookEventTypes` and the `WebhookEvent` type from `@shuffl/sdk`, and the catalog from `@shuffl/api-contracts/webhooks`.
- Warm introductions: `network.requestIntro` (`personId`, `viaId`) asks someone you and that person both know to introduce you. Shuffl sends them a Slack DM with Introduce and Not this time; Introduce starts a group DM with the three of you. It returns `id`, `created` (false when the same request was already waiting) and `state` (`asked`). The person asked must have a tie to both of you that you can see, and you can have 3 requests waiting at once. `network.mine` returns, on each suggestion, `introVia` (the first person in common Shuffl can ask, or null) and `intro` (your latest request about them: `state` `asked`, `introduced` or `not_this_time`, with `viaId`). A decline only ever reads as `not_this_time`. `reminders.settings`, `reminders.saveSetting`, `reminders.mine` and `reminders.saveMine` cover a new kind, `network` ("Do you know this person?", choices `once_a_week` and `once_a_month`, off by default).
- Choosing synced groups: `sync.groups` (`directory.providerGroups`, `connectionId`) lists every group a People sync connection or the Slack workspace (its connection id is the Slack team id) offers, each with `id`, `name`, `memberCount` (people in it at the source), `imported`, `groupId` (the group in Shuffl, when brought in), `onProfile`, `listed` (seen by the latest sync) and `seenAt`, plus the `connection` (`id`, `label`, `provider`, `source`). `sync.setGroup` (`directory.setProviderGroup`: `connectionId`, `id`, `imported` and/or `onProfile`) brings a group in, takes it out or shows it on profiles, and returns `groupId`, `imported` and `syncing` (a sync started so its members arrive). New groups from a source no longer become groups by themselves: a sync lists them and only the ones brought in follow the source. Taken out, a group stays a Shuffl list with its members. `sync.current` connections return `groups` (`listed`, `imported`).
- Group stats: `groups.glance` (`id`) returns a group at a glance in the same shape as `users.glance`, counted over the group's current members: `headcount`, `enough` (5 people or more; below that the splits are empty), `hiredThisYear`, `averageTenureYears`, `tenure`, `departments`, `timezones`, `me` (where the key's person sits by start date, when they are in it) and `topics` (what its people are asked about). `leftThisYear` is always null. Any key reads groups shown on profiles; an owner or administrator key reads any group. A group the key can't see is `NOT_FOUND`.
- `digest.culture` returns the morning Culture page's figures: `week` (people `thanked`, `introductions` and playbooks `finished` in the last seven days), `playbooks` (the four busiest active playbooks, each with `id`, `name`, `leaving`, `active` and up to four `people` with `enrollmentId`, `name`, `photoUrl`, `day`, `progressPct`, `flag`: `help`, `no_buddy` or `late`, and `late`), `help` (new hires who asked for help at a check-in in the last 14 days), `wins` (`finished` playbooks this week and shared work `anniversaries` in the next seven days), `focus.company.previous` (the company's `thankedPct`, `metPct` and `pulse` over the 90 days before) and each outcome's short `step`.
- Groups for everyone: `groups.directory` lists the groups shown on profiles to any key in the workspace, the key's own groups first, each with `id`, `name`, `description`, `source`, `hrTeam`, `memberCount`, `mine` and up to five `faces` (`id`, `name`, `title`, `photoUrl`). `groups.directoryGroup` (`id`) reads one with every `member` the same way; a group not shown on profiles is `NOT_FOUND`. People whose employment ended are left out of both.
- `users.glance` returns `undated`, how many people in the headcount have no start date, and `leftThisYear`, how many were marked as left in the last year: a number for an owner or administrator key, null for anyone else.
- `celebrations`: `thisWeek` lists who was celebrated in a channel in the last seven days (`days`, and `people`, each with `personId`, `name`, `eventType`: `birthday` or `anniversary`, `years` and `sentAt`). Celebrations sent privately or to a person's own team are left out.
- Automations on a group: `groups.setAutomation` adds or changes what happens when someone joins or leaves a group (`groupId`, `trigger`: `entered` or `left`, `kind`: `send_message`, `start_onboarding`, `invite_community`, `add_to_program`, `tell_hr` or `tell_manager`, and a `config` for the kind: the message's `subject`, `body`, `action` and `channel`; a `programId`; a `communityId`; or a `note`). A new automation starts paused; `groups.setAutomationState` (`id`, `state`: `paused` or `active`) turns it on or off, `groups.removeAutomation` (`id`) drops it with its runs, and `groups.automations` (`groupId`) lists a group's automations with each one's `summary`, `state`, `runs` and `lastRunAt`, and its last 50 runs (`personId`, `name`, `trigger`, `outcome`: `done`, `skipped` or `failed`, and `why` a run did nothing). Runs happen from the groups refresh, once per person and entry; `personActivity.personActivity` returns them as `group_automation` events.
- Message a group: `groups.prepareMessage` writes a draft to everyone in a group (`groupId`, `subject`, `body` as paragraphs, optional `action` with `label` and a `path` starting with `/app`, and `channel`: `preferred`, `slack` or `email`) and returns it with `preview` (how it reads to its first recipient, with `{{first_name}}`, `{{manager}}` and `{{company}}` filled in) and `reach` (`recipients`, `reachable`, `alreadyToday`, `unreachable`). `groups.sendMessage` (`id`, `requestKey`) queues it once per request key on each person's chosen channel, leaving out anyone HR already messaged that day, and returns `queued` and `skipped`; the same key replays the result. `groups.messages` (`groupId`) lists a group's drafts and sends, `groups.message` (`id`) reads one with its preview and reach, `groups.discardMessage` (`id`) drops a draft, and `groups.export` (`id`) returns the members as `csv` with a `filename`. People get the message under the new `hr_message` notification kind in `notifications.preferences`, which offers Slack and email and cannot be fully turned off; a Slack thread reply to one becomes an HR request.
- A Connections program's people can come from a group: `programs.create` and `programs.update` take `groupId` (null or omitted keeps the Slack channel roster), `programs.get` and `programs.list` return `groupId` and `groupName`, `programs.options` returns `groups` to pick from, and `programs.syncRoster` reads the group's members when one is set. Joining or leaving the channel no longer changes who takes part in such a program; the channel stays where introductions are posted.
- `playbooks.previewEnrollment` and `playbooks.enroll` take `groupId`: everyone in that group who is not on the journey yet is added after `rows`, which may now be empty. The preview returns the expanded rows and its fingerprint covers them.
- `groups`: `list`, `get`, `members`, `options`, `searchPeople`, `suggestions`, `preview`, `save`, `refresh`, `remove`. A group is a live set of people in the workspace, kept by rules on People attributes (re-evaluated every ten minutes and on save) or a list picked by name; `suggestions` lists the starter groups not made yet and `preview` counts who a set of rules would hold today.
- `knowledge.templates`: `draft` has Mello research a policy template and write the whole page. Send the template id, `title`, `body` (the template text, prefilled or not), its `checks`, and optional `notes` and `website`. It returns `title`, `body`, `choices` (each value Mello chose, with its `topic`, `value`, `basis`: `company`, `law` or `typical`, and the `source` link the web search returned, if any), `sources`, `placeholders` (how many are left) and `researched` (whether the web search ran). Nothing is saved.
- `knowledge.templates`: `facts` returns what Shuffl knows that policy templates ask for: `companyName`, `hrContact` (who answers HR requests), `hrRequests` (whether people can send one), `countries` (from the directory's time zones, most people first) and `holidaysTitle` (the published holidays page). The app fills a new template's placeholders with them.
- `knowledge.handbook`: `export` returns the pages published to everyone as one handbook: `teamName`, `generatedAt`, `pages` (each with `title`, `effectiveAt`, `version` and its Markdown `body`), `leftOut` (how many published pages are for particular groups or admins only) and the whole handbook as `markdown`. Each call is recorded as a download.
- `knowledge.acknowledgements`: `status`, `request`, `remind`, `close`, `mine`. HR asks the people who can read a published page to confirm they read it: `request` asks the page's audience to confirm its published version (and messages them unless `notify` is false), `remind` messages the people who haven't confirmed, `close` stops asking, and `status` lists who is asked and who confirmed which version. `mine` lists the pages the key's person is asked to confirm. Confirming itself happens only in the app.
- Notification preferences cover a new kind, `policy_acknowledgement`: the message asking someone to read and confirm a Knowledge page.
- `digest`: `culture` lists the Culture page's recommendations in Mello's order, each with its `area` (`praise`, `connections`, `onboarding` or `pulse`) and `rank`, and `outcomes`: what happened after each recommendation acted on in the last 60 days. It also returns `focus`: each department (or team, in a smaller company) of 7 or more people with its share thanked, share introduced to another team, new hires without a buddy and Pulse score beside the company's, the areas where it is behind, and introductions between each pair of groups. Each group also carries its weakest Pulse driver (`weakDriver`), `responsePct`, `joined`, `left`, `needHelp`, `missedCheckIns` and `previous` figures for the 90 days before, and `focus.praise` counts praise between groups.
### Changed
- Badge offers when a project or event channel goes quiet: `badges.settings` returns and `badges.saveSettings` takes `channelOffers` (default `true`). Once a day Shuffl looks at the channels it is in whose names mark a project, launch or event and offers the channel's maker a badge for everyone who posted, once per channel; such offers have `source` `channel`.
- Celebration send days: `celebrations.save` and `celebrations.preview` take `sendDays` (ISO weekdays, 1 = Monday; Monday to Friday when left out) and `offDayShift` (`before` or `after`: where a birthday or anniversary on another day goes), and `celebrations.program` returns both for each celebration. `celebrations.preview` returns the sample's `sendDate` and `shifted`, and `celebrations.review` rows carry `sendDate`, the local day each one goes out.
- Journeys are now called playbooks. Operation descriptions, error messages and the app's links say playbook and point at `/app/playbooks` and `/app/playbooks/all`; the old `/journeys` addresses redirect there. Operation names and fields followed in a later release.
- Slack user groups become synced groups with `source` `slack`, kept in step with Slack's members. The Slack import also fills `jobTitle`, `timezone`, `startDate` and `managerId` in `directory.directoryPerson` from Slack profiles for people no HR system manages.
- Pulse results HR can share: `pulse.program` returns and `pulse.saveProgram` takes `shareResults` (default `false`). When it is on, `pulse.asked` returns `result` on each closed question asked to everyone whose reporting floor was met (`unit`: `favourable` or `eNPS`, `value`, `respondents`); otherwise `result` is null.
- Journeys: onboarding is the first kind of journey. `playbooks.saveProgram` takes, and `playbooks.program` and `programs.*` return, `playbook.dayZero` (`start_date`, `joined` or `date`: what each person's days count from), `playbook.dayZeroDate` (the one date when `dayZero` is `date`), `playbook.buddy` and `playbook.helpCheckIn` (whether the buddy messages and the help check-in are part of the journey; both default to true). A `joined` journey has no steps before day 0. `playbooks.enroll` and `playbooks.previewEnrollment` fill a missing `startDate` from the journey's day 0. `playbook.journey` takes an optional `enrollmentId` and returns `enrollmentId`, `dayZero`, `buddyOn` and `journeys` (each journey the person is on, with `current`). `playbook.personOnboarding` returns `buddyOn` per enrollment.
- Catch-up for people who join a journey after day 0: `playbooks.saveProgram` takes, and `playbooks.program` and `programs.*` return, `playbook.catchUp` (`skip`, the default, `bundle` or `shift`). `playbooks.enroll` takes an optional `catchUp` for that batch and returns `catchUp` and `late`, how many were added after day 0. `playbooks.previewEnrollment` returns `missed` per row and `catchUp` (`default`, `late` and `sample`, one person's steps under each choice). `playbooks.enrollmentPreview` returns `joinedOn` and `catchUp` per step (`planned`, `today`, `skipped` or `bundled`). Steps can have the status `skipped` and the kind `catch_up`, the one What you missed message.
- Check-ins on any day with a journey's own questions: a journey step of kind `checkpoint` can have `checkpoint: 'custom'` with `questions` (1 to 6, each with an `id`, `text` and `kind`: `scale` with a `scale` of `agree_5`, `rating_5` or `yes_no`, or `open`), on any day and as often as the journey likes, in `playbooks.saveProgram`, `playbooks.program` and `programs.*`. `playbooks.firstDaysCheckIns` returns them with `checkpoint` set to `step::`, plus `intro`, `note` and `journey` on every check-in; `playbooks.answerFirstDaysCheckIn` takes that `checkpoint` and answers the step's questions. `playbooks.firstDaysResults` returns `journeys`: each journey's own check-ins (`programId`, `journey`, `stepKey`, `title`, `offsetDays`, `dayZero`, `sent`, `answered`, `published` and `questions`), combined only within that step and shown above the reporting floor like the built-in ones. `playbook.journey` returns `kind` per checkpoint (`day_30`, `day_60`, `day_90`, `day_365` or `custom`) and `checkpoint` as the check-in's subject.
- Leaving: `directory.saveDirectoryPerson` takes, and `directory.directoryPerson` returns, `lastDay` (the person's last day; null clears it, left out keeps it) and `lastDayAnnounced` (default false). Shuffl never takes or stores a reason. Until a last day is announced, `directory.directoryPerson` returns `lastDay` as null to anyone but owners, admins and the person's manager. A journey's `playbook.dayZero` can be `last_day`: each person's days count from their last day in People, with steps up to 60 days before and after, and no buddy. Until the leaving is announced only steps to the manager and HR go; the others wait with status `waiting` and `errorCode` `until_announced`. A changed last day sends the run's unsent steps back for approval at the new dates, and a cleared one ends the run with `removalReason` `leaving_cancelled`. `playbooks.previewEnrollment` reports `missing_last_day` for someone without one. Ending someone's employment or access no longer ends their leaving journey; only the steps to them stop.
- `praise.feed` returns `values`: on the first page, the five values praised most in the last 30 days (`value`, `count`), counted from the praise the key's person can read. Later pages return an empty list.
- Pulse results by people group: `pulse.insights` and `pulse.questionDetail` return a fifth split, `groups.dimensions.group` (`questionDetail`: `groups.group`), one row per group with the same `label`, `respondents`, `favourablePct`, `enps` and `drivers` as departments and teams. `pulse.insights` also lists every current group with `seen: false` until a question closes after it was made. A group's figures are withheld under the reporting floor, when the people outside it are under the floor, and when it and any other published total would give fewer than the floor away by subtraction.
- Praise in private Slack channels: `praise.feed` and `praise.ofPerson` include praise from private praise channels the key's person is in now, and `praise.mine` leaves out private channels they have left. `praise.composer` returns `private` per channel and offers private channels only to their members; `praise.send` refuses a private channel for someone who isn't in it. `praise.settings` returns `membersFresh` and `membersError` per channel.
- Charts on the employee People page: `users.glance` returns `monthly`, the last twelve months of headcount and people who joined (empty below five people).
- Onboarding to-do reminders: `reminders.settings`, `reminders.saveSetting`, `reminders.mine` and `reminders.saveMine` cover a third kind, `onboarding_todo`, with the choices `one_day_late` and `three_days_late`. It is on (`one_day_late`) unless a team turns it off.
- Mello answers from the asker's onboarding journey: a citation's `kind` can be `onboarding` in `assistant.history`, linking to Your onboarding. `knowledge.search`, `knowledge.context` and `manager.current` share the citation shape but never return it.
- `reports.onboarding` returns `hires.withBuddy`, the hires in onboarding now who have a buddy. `digest.actOnNudge` and `digest.dismissNudge` accept `from: 'culture'` for nudges acted on from the Culture page. Culture nudges have six more kinds: `praise_low`, `pulse_low`, `start_praise`, `start_pulse`, `start_onboarding` and `start_cross_team`.
## 0.4.0 (2026-10-12)
The company API joins the SDK, the CLI and OpenAPI. It takes a company key (`shuffl_company_`) from Company settings → API keys, never a workspace key, so it has its own client and commands.
### Breaking
- `GET /api/v1/company/members.list` is paginated: it takes `limit` (1 to 100, 25 by default) and `cursor`, and returns `{ items, nextCursor }` instead of an array of every member. Scripts that call it over HTTP read `items` and follow `nextCursor`.
- The first 90 days' check-ins are onboarding journey steps (`kind: 'checkpoint'` with `checkpoint` of `day_30`, `day_60`, `day_90` or `day_365`). `reminders.settings`, `reminders.saveSetting`, `reminders.mine` and `reminders.saveMine` now cover only `praise` and `pulse`: the `manager_check_in` and `new_hire_check_in` kinds and their choices are gone. `onboarding.firstDaysResults` no longer returns `manager`, and `onboarding.journey` no longer returns `managerCheckIns`.
### Added
9 operations, by resource:
- `company`: `current`, `details`, `rename`
- `company.emailDomains`: `list`
- `company.members`: `list`, `remove`
- `company.slack`: `list`
- `company.workspaces`: `list`, `setDefault`
- `onboarding`: `completeTodo` checks off (or reopens) one of your own onboarding to-dos.
### SDK, CLI and OpenAPI
- SDK: `createShufflCompany({ baseUrl, token })` returns a typed client for these operations, such as `company.members.list({ limit: 100 })`. It calls the REST paths under `/api/v1/company` and throws `ORPCError` like `createShuffl`.
- CLI: `shuffl company` commands, with `shuffl login --company --token-stdin` and `shuffl logout --company`, or `SHUFFL_COMPANY_KEY` in the environment. The company key is saved in `company.json`, apart from the workspace key.
- OpenAPI: the operations are under `/company`, with the `companyKey` security scheme and `x-shuffl-credential: company`.
### Changed
- Company API responses return exactly the published fields: `company.details` no longer includes `internal`, and `company.slack.list` sends `revokedAt` as an ISO time.
- Company API errors include `status` and `defined: false`, like workspace API errors.
- Onboarding journeys: `onboarding.saveProgram`, `onboarding.program` and `programs.*` carry `onboarding.steps`, the steps HR writes (message, to-do or check-in, day offset, recipient, Knowledge, link and community resources, to-dos). `onboarding.enrollmentPreview` returns each step's `ref`, `title`, recipient and to-dos; `onboarding.program` returns `stepKey` and `title` per step; `onboarding.journey` returns `todos`, `gettingReady` and `resources`.
- `reports.people` returns `history`: headcount, joins and people marked as left for each of the last 12 months, plus today's departments and tenure.
- `exports.team` and `reports.overview` return each program's `onboarding.steps` too; `credentials.api.create`, `credentials.api.list` and `permissions.list` include the `onboarding.completeTodo` permission.
- `reports.onboarding` returns `messages.weekly` (sent and on time per week); `praise.insights` returns `givers` and `recognized` per week.
## 0.3.0 (2026-10-12)
Breaking: two fields were removed and one object was reshaped, so this is a minor release. Upgrade the SDK and CLI together.
### Breaking
- `teams.setup`: `slack.connected` and `slack.status` are replaced by `slack.state`, `slack.live` and `slack.reason`.
- `celebrations.preview` no longer returns `fingerprint`, and `celebrations.save` no longer takes `previewFingerprint`.
### Added
7 operations, by resource:
- `celebrations`: `saveAnniversaryDate`, `startDates`
- `home`: `places`
- `hr`: `mine`
- `onboarding`: `journey`
- `teams`: `slackConnection`
- `users`: `glance`
### Changed
- Schedules take `days` (1 to 7, Monday first) to pick days of the week: program schedules in `programs.*` and `reports.overview`, `reminders.saveSetting` and `reminders.settings`. `pulse.program` and `pulse.saveProgram` add `sendEvery`, `sendUnit`, `sendStart` and `sendMonthWeek`.
- Notification kinds add `check_in` and `getting_started` (`notifications.preferences`, `notifications.save`).
- `users.save` takes `originalStartDate`; `exports.team` returns it, and `celebrations.preferences` returns `startDate`.
- `communities.members` returns `joinedAt`; `praise.settings` returns `slack`; `sync.current` returns `slack` per connection; `digest.preview` returns `trend` and a `ratio` per section; `operations.activity` always returns `summary`.
- `profiles.whoKnows` takes `from`; `support.create` takes `guides`; `praise.send` accepts more `from` values.
- `credentials.api.create`, `credentials.api.list` and `permissions.list` include the new operations' permissions.
## 0.2.1 (2026-10-03)
No operation changes. `shuffl --help` and the OpenAPI summaries now describe all 303 operations in words. In 0.2.0, 133 of them showed only their operation id, such as `access.get`.
## 0.2.0 (2026-10-03)
Breaking: while the major version is 0, a minor release may rename or remove operations. Upgrade the SDK and CLI together.
### Renamed
- `workspaces.*` is now `teams.*`: `current`, `setup`, `status`, `initialize`, `saveAgentSetup`, `resendSlackWelcome`, `slackJoinAccess`, `saveSlackJoinAccess`, `slackProfileLink`, `saveSlackProfileLink`, `syncSlackProfileLinks`. `GET /api/v1/workspace` is now `GET /api/v1/team`, and the `/manage/workspaces/...` paths are now `/manage/teams/...`.
- `exports.workspace` is now `exports.team`.
### Removed
- `billing.*`: company billing moved to Company settings, and a team key never gains company scope.
- `provisioning.current` and `provisioning.configure`: SCIM connections are created in the browser, because creating one issues the identity provider's secret.
### Added
97 operations, by resource:
- `badges`: `generatePicture`, `holders`, `saveSettings`, `settings`, `uploadPicture`
- `celebrations`: `card`, `cards`, `removeCardNote`, `signCard`
- `communities`: `channelSuggestions`, `createCapabilities`, `createSlackChannel`, `fromChannels`, `generateCover`, `invite`, `revokeInvitation`, `uploadCover`
- `digest`: `actOnNudge`, `dismissNudge`, `nudge`, `nudges`, `preview`, `saveSettings`, `settings`
- `exports`: `team`
- `getStarted`: `celebrate`, `celebration`, `dismiss`, `draftIntro`, `get`, `intro`, `wizard`
- `home`: `preferences`, `react`, `story`
- `hr`: `categories`, `rebuildCategories`, `saveCategories`
- `invitations`: `candidates`, `createMany`, `inviteDirectory`
- `knowledge`: `sources.write`
- `onboarding`: `answerBuddyAsk`, `answerFirstDaysCheckIn`, `firstDaysCheckIns`, `firstDaysResults`
- `praise`: `composer`, `send`
- `profiles`: `whoKnows`
- `pulse`: `actions`, `answer`, `audienceOptions`, `createAction`, `decideProposal`, `editProposal`, `latestRead`, `mine`, `proposals`, `proposeQuestions`, `questionDetail`, `requestProposals`, `setQuestionAudience`, `skip`, `updateAction`
- `reminders`: `mine`, `saveMine`, `saveSetting`, `settings`
- `reports`: `melloTrial`, `melloValue`
- `runs`: `history.get`, `history.list`, `stopKnownFailures`
- `team`: `answerMinutes`, `dismissLaunchPost`, `launchPost`
- `teams`: `connectionPermissions`, `current`, `discardPairHistory`, `initialize`, `moveSlackChannels`, `rename`, `resendSlackWelcome`, `saveAgentSetup`, `saveSlackJoinAccess`, `saveSlackProfileLink`, `setup`, `slackChannels`, `slackJoinAccess`, `slackProfileLink`, `status`, `syncSlackProfileLinks`, `uploadPairHistory`
- `users`: `assignManagers`, `proposeReportingLines`, `reportingLineProposal`, `reviewReportingLines`
## Related guides
- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)
- [Use the Shuffl CLI](https://shuffl.ai/docs/cli)
- [REST API reference](https://shuffl.ai/docs/api-reference)
Agent documentation index: https://shuffl.ai/llms.txt
---
# Run an engagement check without survey fatigue
> How to pick a survey rhythm you can keep, use eNPS sensibly and show people what changed, so they keep answering.
Audience: HR leads at startups and mid-size companies
Canonical: https://shuffl.ai/playbooks/engagement-check-in
People rarely stop answering surveys because they’re asked too often. They stop because nothing seems to happen. In Gallup’s research, 36% of employees said they get surveys three or more times a year, and only 8% strongly agreed that their employer acts on the results.[^gallup-2018-botch]
This playbook sets a rhythm you can keep: a short, frequent pulse, a few repeated questions you can trend, eNPS a few times a year, and one visible change after each round.
## Why fatigue is really about follow-up
In Gallup’s US survey from May 2025, 28% of employees strongly agreed that their opinions count at work.[^gallup-2025-engagement] Surveys are meant to fix that, but Gallup warns that asking for feedback and then doing nothing can backfire: engagement is likely to fall and turnover to rise.[^gallup-surveys-guide]
Acting on results shows up in the next round. In a 2006 Gallup analysis of workgroups surveyed twice, groups in the top quartile on “Action plans from the last survey have had a positive impact on my workplace” raised engagement scores by an average of 10%. Bottom-quartile groups fell by 3%.[^gallup-2006-action] Given its age, treat it as a rough guide.
Length matters too. In a web survey experiment, the longer people were told a questionnaire would take, the fewer started and finished it, and answers near the end were faster, shorter and more uniform.[^galesic-bosnjak-2009] Short and frequent beats long and rare.
**Asked often, heard rarely**
- 8% of employees strongly agree their employer takes action on survey results[^gallup-2018-botch]
- 28% of US employees strongly agree their opinions count at work[^gallup-2025-engagement]
- 36% of employees get surveys three or more times a year[^gallup-2018-botch]
## Pick a rhythm you can keep
Gallup suggests a deeper engagement survey twice a year, with monthly or quarterly pulse surveys in between, and says the right cadence depends on your capacity to act on results.[^gallup-surveys-guide] For a small HR team, that capacity is the real limit.
eNPS borrows the Net Promoter question: how likely are you to recommend working here to a friend, from 0 to 10? Answers of 9 or 10 are promoters, 7 or 8 passives and 0 to 6 detractors. The score is the promoter share minus the detractor share.[^bain-nps] It’s a useful headline to trend, but it won’t say what to fix, so pair it with specific questions.
- Under about 50 people: a pulse of one question once or twice a week is enough. Skip the big annual survey.
- From 50 to a few hundred: keep the weekly pulse and add a longer survey once or twice a year if you have time to act on it.
- Repeat two or three core questions, such as workload and clarity, every few weeks so you can see a trend.
- Ask eNPS once a quarter. Monthly is too often to see real movement.
## The plan
- Decide who sees what before the first question. Set a minimum group size, such as 7, below which results stay hidden, and write it in the invite.
- Pick three to five topics that matter this year, such as workload, clarity, growth and manager support. Ask one question per send.
- Share each result with the people who answered within two weeks.
- Choose one action per result worth acting on, with an owner and a due date.
- Ask the same question again after the action is done, and report what moved.
- Say what you can’t change yet, and why. People accept a clear no better than silence.
## An example
A 120-person software company asks one question every Tuesday and Thursday, and eNPS once a quarter. In the first month, 70% of people answer.
A workload question comes back at 45% favourable in the support team, down from 65% the quarter before. HR and the support lead agree on one change: a second on-call person on Mondays, owned by the lead, due in four weeks. HR posts a short note to everyone who was asked: what they said, what is changing and when.
Six weeks later the same question is asked again and lands at 60%. The note about that goes out too. Response stays near 70%, and the next eNPS is 10 points higher than the last.
## Common mistakes
- Sending a 60-question survey once a year and sharing the results six months later.
- Asking more often than you can act, so every round ends in silence.
- Treating the eNPS score as the finding instead of a prompt to ask why.
- Showing results for tiny groups, so people can guess who said what.
- Promising change on everything and delivering on nothing.
## A “you said, we did” note
```text
Thanks to the 84 of you who answered last week’s question.
We asked: “My workload is manageable most weeks.”
You said: 45% agreed in Support, down from 65% last quarter.
What we’re doing: from March 3, a second person joins Monday on-call. Priya owns it.
What we can’t do yet: hire another full-time agent before July, because the budget is set until then.
We’ll ask the same question again in six weeks and share what moved.
```
## Do this in Shuffl
1. Open Pulse from the HR workspace and choose Start pulse. Under Repeats, pick a pace you can act on, such as every Tuesday and Thursday at 10:00, and set Open for (48 hours by default).
2. Check the reporting floor. It starts at 7 people and can only go up.
3. Open Questions, preview a question set such as Workload or Clarity, and choose Add N questions to put it in the rotation.
4. Under eNPS in Pulse settings, keep every quarter or choose every month or twice a year.
5. When a question closes, open it on Insights and choose Plan an action. Pick an owner and a due date, and leave Ask this question again on.
6. Choose Tell people to send one “You said, we did” message to a Slack channel and to everyone who was asked.
Guide: [Ask one confidential question at a time with Pulse](https://shuffl.ai/docs/markdown/pulse)
- [For administrators](https://shuffl.ai/docs/pulse#administrators)
- [Start from a question set](https://shuffl.ai/docs/pulse#question-sets)
- [eNPS](https://shuffl.ai/docs/pulse#enps)
- [Acting on results](https://shuffl.ai/docs/pulse#actions)
## Common questions
### How often should we check in on engagement?
Ask one or two short questions a week, or every two weeks, and ask eNPS once a quarter. Go only as fast as you can share results and act on them. If you can’t follow up monthly, a monthly pulse is too frequent.
### Is eNPS enough on its own?
No. eNPS tells you whether the mood is moving, not why. Pair it with a few repeated questions about workload, clarity and managers so you know where to look.
### Should our surveys be anonymous?
Confidential is usually more honest to promise than anonymous. Say plainly who sees what: totals only, for groups above a minimum size, never an individual answer. Then keep that promise every time.
### What if the results are bad?
Share them anyway, with what you’ll do next. A bad result you acknowledge builds more trust than a good one you keep quiet about.
## Glossary
- [Pulse survey](https://shuffl.ai/glossary/pulse-survey)
- [Employee Net Promoter Score](https://shuffl.ai/glossary/employee-net-promoter-score)
- [Employee engagement](https://shuffl.ai/glossary/employee-engagement)
- [Psychological safety](https://shuffl.ai/glossary/psychological-safety)
- [Stay interview](https://shuffl.ai/glossary/stay-interview)
## Related playbooks
- [Build a recognition habit that lasts](https://shuffl.ai/playbooks/markdown/recognition-habit)
- [Plan a new hire’s first 90 days](https://shuffl.ai/playbooks/markdown/first-90-days)
- [Run a coffee chat program people show up to](https://shuffl.ai/playbooks/markdown/coffee-chat-program)
## Sources
[^gallup-2018-botch]: Gallup, “10 Ways to Botch Employee Surveys”, August 2018. https://www.gallup.com/workplace/241253/ways-botch-employee-surveys.aspx Article by Ryan Pendell drawing on Gallup workplace research. The page gives no sample size or fieldwork dates for the 36% and 8% figures.
[^gallup-2025-engagement]: Gallup, “Anemic Employee Engagement Points to Leadership Challenges”, August 2025. https://www.gallup.com/workplace/692954/anemic-employee-engagement-points-leadership-challenges.aspx Web survey of 17,660 US adults working full or part time, from the Gallup Panel, May 7 to 16, 2025 (±1.1 points).
[^gallup-surveys-guide]: Gallup, “Employee Surveys: Types, Tools and Best Practices”, Undated. https://www.gallup.com/workplace/692474/workplace-employee-surveys.aspx Gallup’s practitioner guide to survey types and cadence. Guidance, not a survey.
[^gallup-2006-action]: Gallup, “What to Do With Employee Survey Results”, August 2006. https://www.gallup.com/workplace/238001/employee-survey-results.aspx Workgroups with Q12 data trended across two consecutive survey administrations, sorted into quartiles on the item “Action plans from the last survey have had a positive impact on my workplace.”
[^galesic-bosnjak-2009]: Public Opinion Quarterly, “Effects of Questionnaire Length on Participation and Indicators of Response Quality in a Web Survey”, Summer 2009. https://academic.oup.com/poq/article/73/2/349/1910851 Mirta Galesic and Michael Bosnjak. Web survey experiment in which respondents were told the questionnaire would take 10, 20 or 30 minutes. Peer reviewed.
[^bain-nps]: Bain & Company, “Measuring Your Net Promoter Score”, Undated. https://www.netpromotersystem.com/about/measuring-your-net-promoter-score/ Bain & Company’s explanation of how the Net Promoter Score is calculated, written for customers. eNPS applies the same scoring to employees.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Build a recognition habit that lasts
> How to make thanks specific, frequent and spread across every team, using what research says about recognition and retention.
Audience: HR leads and managers at growing companies
Canonical: https://shuffl.ai/playbooks/recognition-habit
Only 22% of US employees say they get the right amount of recognition, and that hasn’t moved since 2022.[^gallup-2024-retention] Most companies don’t need a bigger program to fix this. They need a habit: specific thanks, given often, by managers and peers alike.
This playbook covers what makes thanks land, how often to give it, and how to keep it going after the launch week.
## Why it matters
Gallup followed nearly 3,500 employees from 2022 to 2024. Well-recognized employees were 45% less likely to have changed organizations two years later.[^gallup-2024-retention]
Frequency matters. Among employees who got feedback and recognition from their manager at least once a week, 61% were engaged, against 38% for those who got weekly feedback but recognition less often.[^gallup-2024-feedback]
Thanks also changes what people do next. In a field study of 41 university fundraisers on fixed salaries, the half thanked in person by their director made more than 50% more calls that week. The others made about the same number as before.[^harvard-gazette-thanks]
**Recognition and staying**
- 45% less likely to have changed employers two years later, for well-recognized employees[^gallup-2024-retention]
- 61% engaged, among those recognized by their manager at least weekly[^gallup-2024-feedback]
- 22% of employees say they get the right amount of recognition[^gallup-2024-retention]
## Make thanks specific
Gallup describes the most effective recognition as honest, authentic and individualized to how each person wants to be recognized.[^gallup-recognition-2016] In practice, that means specific. Compare “thanks for your help” with “thanks for staying on the call with the Leeds customer until their payroll ran, you saved the account.”
When people recalled their most memorable recognition, 28% named their manager and 24% a senior leader or CEO. Peers came to 9%.[^gallup-recognition-2016] Peer thanks fills the gaps between those moments. It doesn’t replace them, so managers need the habit too.
- Name the person.
- Say what they did, concretely: the bug, the call, the doc.
- Say what it made possible: the customer kept, the hour saved, the launch on time.
- Tie it to a value when it fits naturally, not every time.
## Build the habit
Gallup recommends feedback every seven days.[^gallup-recognition-2016] Not everyone wants that much from their manager, though: only 27% say they’d like manager feedback at least weekly.[^gallup-2024-feedback] Ask people how they like to be thanked, and make the default frequent and light.
- Pick one public channel for thanks and say what belongs there. Don’t split it across tools.
- Write down your company values where people can find them, so thanks can point at them.
- Ask each manager to recognize every report by name at least every two weeks, in one-on-ones or in the channel.
- Open one team meeting a week with a minute of thanks.
- Send a gentle private reminder to people who haven’t thanked anyone in a while.
- Each month, look at who gives and gets thanks by department, not by person, and nudge the quiet teams.
## An example
An 80-person company opens a #kudos channel. In the first month there are 120 posts, then 40 in the third. Half the company hasn’t been thanked at all, mostly in finance and operations.
HR asks managers to thank each report by name every two weeks and turns on monthly reminders for people who haven’t posted in a while. Team leads open Monday meetings with a minute of thanks.
By month six the channel holds steady at about 70 posts a month, and the share of people thanked at least once a quarter goes from half to about four in five. Finance shows up for the first time after the year-end close.
## Common mistakes
- Launching a kudos channel with fanfare and never mentioning it again.
- Thanks so generic it could be about anyone: “great job, team!”
- Leaderboards that turn recognition into a contest.
- Leaving recognition entirely to peers, so managers stay quiet.
- Never checking which teams nobody thanks.
## A specific thank you
```text
Thanks @name for [what you did, concretely].
Because of it, [what it made possible].
[Optional: That’s [value] in action.]
Example: Thanks @Ana for rewriting the expenses guide on Friday. Three new hires filed their first claims this week without asking anyone. That’s “Make it easy” in action.
```
## Do this in Shuffl
1. Open Praise → Settings and turn on Read praise channels.
2. Under Company values, pick the Knowledge page that holds your values, or choose Create a company values page.
3. Add the channel where people already thank each other, such as #kudos. For a public channel, choose Add Shuffl to it.
4. Under Reminders, turn on Send praise reminders and choose how often. See the message shows what people get.
5. Each month, check Insights for who is recognized and who gives praise by department. It shows totals for groups of 7 or more and has no leaderboards.
6. For something bigger than a thank you, such as finishing a mentoring program, choose New badge under Praise.
Guide: [Praise and badges](https://shuffl.ai/docs/markdown/praise)
- [For administrators](https://shuffl.ai/docs/praise#administrators)
- [Giving praise](https://shuffl.ai/docs/praise#giving)
- [Reminders to thank people](https://shuffl.ai/docs/praise#reminders)
- [Who sees what](https://shuffl.ai/docs/praise#who-sees-what)
## Common questions
### How often should people be recognized?
Aim for everyone being thanked by someone at least every couple of weeks, and managers recognizing each report regularly. Gallup found engagement was highest where people got feedback and recognition from their manager at least weekly.
### Peer recognition or manager recognition?
Both. Peer thanks spreads recognition across the team and notices work a manager can’t see. Managers’ recognition is the kind people tend to remember most, so it shouldn’t be left to peers.
### Do we need points or rewards?
Not to start. Thanks that is specific and public does most of the work. If you add rewards later, keep them small and avoid anything that turns thanks into a contest.
## Glossary
- [Employee recognition](https://shuffl.ai/glossary/employee-recognition)
- [Employee engagement](https://shuffl.ai/glossary/employee-engagement)
- [Employee retention rate](https://shuffl.ai/glossary/employee-retention-rate)
- [One-on-one meeting](https://shuffl.ai/glossary/one-on-one-meeting)
- [Belonging](https://shuffl.ai/glossary/belonging)
## Related playbooks
- [Run an engagement check without survey fatigue](https://shuffl.ai/playbooks/markdown/engagement-check-in)
- [Celebrate milestones without it feeling automated](https://shuffl.ai/playbooks/markdown/celebrate-milestones)
- [Run a coffee chat program people show up to](https://shuffl.ai/playbooks/markdown/coffee-chat-program)
## Sources
[^gallup-2024-retention]: Gallup, “Employee Retention Depends on Getting Recognition Right”, September 2024. https://www.gallup.com/workplace/650174/employee-retention-depends-getting-recognition-right.aspx Rachael Yi. Joint research with a recognition company; Gallup tracked the careers of nearly 3,500 employees from 2022 to 2024.
[^gallup-2024-feedback]: Gallup, “Organizations Redefine Feedback, Including Recognition”, October 2024. https://www.gallup.com/workplace/651812/organizations-redefine-feedback-including-recognition.aspx Andy Kemp. Preference figures from a Gallup web survey of 4,439 US employees, run with a recognition company, April 16 to 30, 2024 (±2.3 points). Engagement figures from Gallup’s Q3 2024 web survey of 20,721 working adults, August 13 to 27, 2024 (±1.2 points).
[^gallup-recognition-2016]: Gallup, “Employee Recognition: Low Cost, High Impact”, June 2016, updated January 2024. https://www.gallup.com/workplace/236441/employee-recognition-low-cost-high-impact.aspx Employees were asked to recall who gave them their most meaningful and memorable recognition. The page gives no sample size or dates for that survey.
[^harvard-gazette-thanks]: Harvard Gazette, “The power of ‘thanks’”, March 2013. https://news.harvard.edu/gazette/?p=133210 News article by Chuck Leddy on Francesca Gino’s research. The fundraiser field study had 41 participants on fixed salaries; their director thanked half of them in person.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Celebrate milestones without it feeling automated
> How to mark work anniversaries and birthdays with consent, a manager’s own note and a card the team signs, so the day feels noticed, not scheduled.
Audience: HR leads and managers at growing companies
Canonical: https://shuffl.ai/playbooks/celebrate-milestones
A message from a bot that says “Happy 3rd work anniversary!” tells someone a database noticed. Recognition people remember tends to come from people: when Gallup asked employees who gave them their most memorable recognition, 28% named their manager and 24% a senior leader or CEO.[^gallup-recognition-2016]
So let a tool handle the dates and the reminders, and let people write the words. This playbook covers consent, which milestones to mark and how, and how to make managers’ notes easy to write.
## Why it matters
Median tenure with a US employer was 4.1 years in January 2026, and 20.6% of wage and salary workers had been with their employer a year or less.[^bls-tenure-2026] Many people won’t reach a fifth anniversary with you, which makes the first one count.
Only 22% of US employees say they get the right amount of recognition.[^gallup-2024-retention] A milestone is a moment you already know is coming. It’s an easy one to get right.
**Milestones come sooner than you think**
- 4.1 median years with their current employer, US wage and salary workers, January 2026[^bls-tenure-2026]
- 20.6% had been with their employer a year or less[^bls-tenure-2026]
- 28% named their manager as the source of their most memorable recognition[^gallup-recognition-2016]
## Ask first, and keep the details small
This isn’t legal advice. Birthdays are personal data, and a birth year reveals age. In the US, for example, the Age Discrimination in Employment Act protects people aged 40 or older from age discrimination,[^eeoc-age] which is one more reason not to collect the year at all. Check the rules where you employ people.
- Ask before you share anything beyond a private note, and ask separately for birthdays and anniversaries.
- Make no the easy answer. Nobody should have to explain it.
- Collect a birthday’s month and day only. Never import it from payroll and never ask for the year.
- Keep ages and exact dates out of public posts. Years of service are usually fine.
- Let people change their mind any time, and cancel anything still scheduled when they do.
## The plan
- Fix start dates first. Rehires, acquisitions and contractors who converted often have the wrong one. Decide whether anniversaries count from the latest start or the first hire.
- Decide what each milestone gets. Every year: a private note and a manager message. First year and every fifth: a team card or a post in a channel, if the person agreed.
- Give managers a heads-up a week before, with the date and a prompt for what to write.
- Ask teammates to sign a shared card in the week before. Keep it a surprise until the day.
- Send on the day, in the person’s own time zone, during their working hours.
- Never post as the manager. The note only counts if they wrote it.
## An example
A 150-person company turns on anniversaries and birthdays. About 60% of people agree to share their anniversary in #general, and about 40% their birthday. Everyone else gets a private note only.
Before launch, HR finds 12 people from an acquisition whose start dates all read the same day, and fixes them. Each week about three anniversaries come up. Managers get a heads-up a week ahead with a prompt; most write two or three lines about something the person did that year.
For a fifth anniversary, eight teammates sign a card. The person opens it on the day and replies in the thread to thank each of them by name.
## Common mistakes
- Posting birthdays in a public channel without asking first.
- Storing birth years, or showing ages, when the day is all you need.
- Celebrating from a wrong start date after a migration or acquisition.
- A templated message with no human note from the manager.
- Treating a fifth anniversary the same as a second.
## A manager’s anniversary note
```text
Happy [N] years, [name].
One thing from this year I keep thinking about: [a specific piece of work and what it changed].
Something I’ve seen you get better at: [a skill or habit].
What I’m looking forward to with you next year: [a project or goal].
Thank you for [one line in your own words].
```
## Do this in Shuffl
1. Open Celebrations from the HR workspace and pick a starter, such as Private anniversary notes. It fills in the settings; nothing is turned on yet.
2. Under Start dates, choose whether anniversaries count from the latest start date or the first hire date, and fix the dates listed as looking wrong.
3. On each card, choose who hears about it: a private note to the person only, also a post in a Slack channel, or also a message to each of their teammates. Shared posts go out only for people who chose Share it.
4. Write the message with {name} and {years}, or {name} for birthdays, and choose the send time.
5. Check Preview, then choose Turn on. Managers get a Slack heads-up a week before each shared day, and teammates are asked to sign a card.
6. Use Upcoming to see the next 60 days and whether each person’s day is shared or private.
Guide: [Celebrate work anniversaries and birthdays](https://shuffl.ai/docs/markdown/celebrations)
- [For administrators](https://shuffl.ai/docs/celebrations#administrators)
- [Start dates](https://shuffl.ai/docs/celebrations#start-dates)
- [Who sees what](https://shuffl.ai/docs/celebrations#who-sees-what)
- [For managers](https://shuffl.ai/docs/celebrations#managers)
## Common questions
### Should we celebrate birthdays at all?
Ask. Some people love a channel post and some would rather nobody knew. Make sharing a birthday opt-in, ask separately about anniversaries, and keep a private note for everyone who says no.
### Which anniversaries deserve more?
Usually the first year and every fifth. Every year can get a short private note and a message from the manager; the bigger years get a team card or a channel post.
### Is it fine to store employees’ birthdays?
Not legal advice, but a good default is to collect only the month and day, never the year, and only from people who choose to share it. Check data protection rules where you employ people.
## Glossary
- [Work anniversary](https://shuffl.ai/glossary/work-anniversary)
- [Employee recognition](https://shuffl.ai/glossary/employee-recognition)
- [Employee experience](https://shuffl.ai/glossary/employee-experience)
- [Belonging](https://shuffl.ai/glossary/belonging)
## Related playbooks
- [Build a recognition habit that lasts](https://shuffl.ai/playbooks/markdown/recognition-habit)
- [Plan a new hire’s first 90 days](https://shuffl.ai/playbooks/markdown/first-90-days)
- [Handle a leaver well](https://shuffl.ai/playbooks/markdown/when-someone-leaves-well)
## Sources
[^gallup-recognition-2016]: Gallup, “Employee Recognition: Low Cost, High Impact”, June 2016, updated January 2024. https://www.gallup.com/workplace/236441/employee-recognition-low-cost-high-impact.aspx Employees were asked to recall who gave them their most meaningful and memorable recognition. The page gives no sample size or dates for that survey.
[^bls-tenure-2026]: US Bureau of Labor Statistics, “Employee Tenure Summary”, September 24, 2026. https://www.bls.gov/news.release/tenure.nr0.htm January 2026 supplement to the Current Population Survey, sponsored by the US Department of Labor’s Chief Evaluation Office. Wage and salary workers.
[^gallup-2024-retention]: Gallup, “Employee Retention Depends on Getting Recognition Right”, September 2024. https://www.gallup.com/workplace/650174/employee-retention-depends-getting-recognition-right.aspx Rachael Yi. Joint research with a recognition company; Gallup tracked the careers of nearly 3,500 employees from 2022 to 2024.
[^eeoc-age]: US Equal Employment Opportunity Commission, “Age Discrimination”, Undated. https://www.eeoc.gov/age-discrimination Regulator’s summary of the Age Discrimination in Employment Act.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Plan a new hire’s first 90 days
> A week-by-week plan for a new hire’s first 90 days: preboarding, a buddy who actually meets them, weekly manager check-ins and 30, 60 and 90-day goals.
Audience: HR leads and hiring managers at growing companies
Canonical: https://shuffl.ai/playbooks/first-90-days
A new hire works out a lot in their first three months: whether they chose well, who they can ask, and whether anyone notices how they’re doing. Most companies leave that to chance. Only 12% of U.S. employees say their company does a good job of onboarding[^gallup-onboarding-tips].
This plan covers the stretch from a signed offer to day 90: what to send before day one, how to pair a buddy, when the manager checks in, and which goals to set at 30, 60 and 90 days.
## Why the first 90 days matter
Only 29% of new hires say they feel fully prepared and supported to excel in their role. When managers take an active part in onboarding, employees are 3.4 times as likely to feel it was successful[^gallup-onboarding-tips].
Buddies help too, if they actually meet. In Microsoft’s buddy program, 56% of new hires who met their buddy at least once in their first 90 days said the buddy helped them become productive. That rose to 86% for four to eight meetings and 97% for more than eight[^shrm-buddies].
So the plan has two jobs: get the manager in the room every week, and make sure the buddy meetings happen more than once.
**What a planned first 90 days changes**
- 12% of U.S. employees say their company does a good job of onboarding[^gallup-onboarding-tips]
- 29% of new hires feel fully prepared and supported to excel in their role[^gallup-onboarding-tips]
- 3.4x as likely to feel onboarding was successful when the manager takes an active role[^gallup-onboarding-tips]
- 97% of Microsoft new hires who met their buddy more than eight times said it made them more productive[^shrm-buddies]
## Before day one
Preboarding is the time between the signed offer and the first day. It’s mostly logistics, and it’s where a new hire first sees whether you’re organised.
- Send a welcome note from the manager within a few days of the signed offer.
- Share the first-week schedule: who they meet, when, and where to go or which link to open.
- Order equipment and create accounts so they work on day one.
- Choose the buddy and tell them the start date, so they can block time.
- Book the manager’s weekly check-ins for the first 12 weeks before day one.
## The plan, week by week
The schedule matters more than the content. Put every meeting in the calendar up front, so nothing depends on someone remembering.
- Week 1: the buddy and hire meet on day one or two. The manager walks through the 30-day goals.
- Weeks 1 to 12: the manager holds a 15-minute check-in each week. Ask what’s unclear, what’s slow and what they’d change.
- Weeks 1 to 6: the buddy meets the hire every week. After that, every other week until day 90.
- Day 30, 60 and 90: ask the hire a short set of the same questions each time, so you can compare answers across hires.
- Day 90: ask one open question about what to fix before the next person starts, then fix it.
**The rhythm of a first 90 days**
1. Before day one: Welcome note, schedule, equipment, buddy named.
2. Days 1 to 30: Learn the people, the product and how work gets done.
3. Days 31 to 60: Take on real work with help close by.
4. Days 61 to 90: Own something end to end and say what to fix.
## Set 30, 60 and 90-day goals
Write the 30, 60 and 90-day goals before the hire starts and share them in week one. Keep each one observable, so the hire and manager can both tell whether it happened. Adjust them in the weekly check-in instead of waiting for day 90.
- By day 30: knows their team and key partners by name, has shipped or finished one small piece of work, and knows where to ask questions.
- By day 60: works on a real project with a named outcome, and has had one piece of written feedback from their manager.
- By day 90: owns one area or project end to end, and has agreed goals for the next quarter with their manager.
## An example
A 150-person software company hires 8 people in a quarter. HR writes one onboarding plan, and each hiring manager fills in the 30, 60 and 90-day goals for their own hire before the start date.
Each hire gets a buddy from a different team who has been there at least six months. Buddies meet weekly for six weeks, then every other week, which comes to about nine meetings by day 90. Managers hold 12 weekly 15-minute check-ins, three hours over the quarter.
At day 30, two of the 8 hires say they still don’t know who to ask about expenses. HR adds the answer to the welcome note for the next group. At day 90, three hires say their laptop arrived late, so IT starts ordering equipment on the day the offer is signed.
## Common mistakes
- Going quiet between the signed offer and day one.
- Treating onboarding as the first week of paperwork and logins.
- Naming a buddy and never checking that they actually met.
- Leaving manager check-ins to whenever the calendar allows.
- Asking how onboarding went and never changing anything for the next hire.
## Day 30, 60 and 90 check-in questions
```text
Ask the same questions at day 30, 60 and 90 so you can compare.
1. I know what’s expected of me in my role. (Agree / Not sure / Disagree)
2. I know who to ask when I’m stuck. (Agree / Not sure / Disagree)
3. I have the tools and access I need to do my work. (Agree / Not sure / Disagree)
4. My manager checks in with me regularly. (Agree / Not sure / Disagree)
5. What has been harder than it needed to be?
Day 90 only:
6. What should we fix before the next person starts?
```
## Do this in Shuffl
1. Open Playbooks from the HR workspace and choose New playbook. Start from a template such as New hire onboarding or Remote new hires, or choose Review and start on the playbook Mello suggests.
2. Name the playbook, choose the accountable HR responder and the send time, and edit the buddy invitation, introduction and help check-in with {{hire}} and {{buddy}}. Choose Start playbook.
3. Choose Add people and pick hires from People, add everyone in a group, or upload a CSV with their emails, start dates, time zones and buddies.
4. Choose Review and approve messages, read each message with its date, and approve. Messages go out in Slack in each hire’s own time zone.
5. Start from the First 90 days template, or keep the day 30, 60 and 90 check-ins every starter playbook has, and add the manager’s one-to-ones as playbook steps through week 12.
6. Read What new hires said once enough hires have answered, and act on the day 90 question about what to fix.
Guide: [Playbooks and onboarding](https://shuffl.ai/docs/markdown/playbooks)
- [Create a playbook](https://shuffl.ai/docs/playbooks#program)
- [Add people and approve their messages](https://shuffl.ai/docs/playbooks#enroll)
- [Checklists, buddies and check-ins](https://shuffl.ai/docs/playbooks#buddy)
- [The first 90 days](https://shuffl.ai/docs/playbooks#first-90-days)
## Common questions
### When should onboarding start?
At offer acceptance. The weeks between the signature and day one are when a new hire is most likely to hear nothing. A welcome note, a first-week schedule and the name of their buddy cost little and answer most of their questions.
### How long should onboarding last?
Plan the first 90 days in detail and check in again at one year. Gallup’s experience is that new employees take around 12 months to reach their peak performance[^gallup-onboarding-tips], so the 90-day plan is a start, not the finish.
### Who makes a good onboarding buddy?
A peer who has been around long enough to know how things really work, who isn’t the hire’s manager and who has time to meet often. In Microsoft’s program, new hires who met their buddy more often were more likely to say it made them productive[^shrm-buddies].
### Should HR or the manager own onboarding?
Both, with different jobs. HR owns the system: the schedule, the messages and the check-ins. The manager owns the week-to-week conversation and the goals. Gallup finds that when managers take an active role, new hires are 3.4 times as likely to feel their onboarding was successful[^gallup-onboarding-tips].
## Glossary
- [Onboarding](https://shuffl.ai/glossary/onboarding)
- [Preboarding](https://shuffl.ai/glossary/preboarding)
- [Onboarding buddy](https://shuffl.ai/glossary/onboarding-buddy)
- [One-on-one meeting](https://shuffl.ai/glossary/one-on-one-meeting)
- [Objectives and key results](https://shuffl.ai/glossary/okrs)
- [Employee experience](https://shuffl.ai/glossary/employee-experience)
- [Employee retention rate](https://shuffl.ai/glossary/employee-retention-rate)
## Related playbooks
- [Run a coffee chat program people show up to](https://shuffl.ai/playbooks/markdown/coffee-chat-program)
- [Run an engagement check without survey fatigue](https://shuffl.ai/playbooks/markdown/engagement-check-in)
- [Answer benefits and policy questions at scale](https://shuffl.ai/playbooks/markdown/answer-hr-questions-at-scale)
- [Your first 30 days as a solo HR person](https://shuffl.ai/playbooks/markdown/first-30-days-solo-hr)
## Sources
[^gallup-onboarding-tips]: Gallup, “8 Practical Tips for Leaders for a Better Onboarding Process”, August 2021. https://www.gallup.com/workplace/353096/practical-tips-leaders-better-onboarding-process.aspx Gallup article by Emily Wetherell and Bailey Nelson drawing on Gallup’s research and client experience with U.S. employees. The article does not give a sample size for each figure.
[^shrm-buddies]: SHRM, “Work Buddies Can Help New Employees Transition into Job, Organizational Culture”, August 2022. https://www.shrm.org/topics-tools/news/organizational-employee-development/work-buddies-can-help-new-employees-transition-job-organizational-culture SHRM article by Kathy Gurchiek reporting Microsoft’s buddy program research. Figures are self-reported answers from Microsoft new hires about meetings with their buddy in their first 90 days.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Run a coffee chat program people show up to
> How to run an opt-in coffee chat program across teams: who it’s for, group size, cadence, the match message and what to measure.
Audience: HR and people teams at companies with remote or growing teams
Canonical: https://shuffl.ai/playbooks/coffee-chat-program
Coffee chat programs pair coworkers who wouldn’t otherwise meet for a short, unstructured conversation. Most fade within a few months because nobody decided who they were for, how often they run or what to say when the match arrives.
This playbook covers why cross-team connection is worth the time, how to choose group size and cadence, how to run it opt-in, and what to measure.
## Why it matters
People don’t meet across teams by accident as often as they used to. When Microsoft moved to firm-wide remote work, the share of collaboration time spent with cross-group connections fell by about 25% of its earlier level, and groups became more siloed[^microsoft-remote-collaboration].
Close ties at work are rare. In the U.S., just two in 10 employees report having a best friend at work, and Gallup found the link between that and outcomes such as intent to leave grew stronger after the pandemic began[^gallup-best-friend].
Structured small-group chats can help newcomers. In a field experiment with 1,370 remote interns, those randomly given weekly 30-minute video sessions with a senior manager and three or four other interns were 4.7 percentage points likelier to get a full-time offer than interns given a Q&A forum. Against interns given nothing extra, the gap was about 2 points and not statistically significant[^worldbank-water-coolers].
**Why cross-team chats need a nudge**
- About 25% drop in the share of collaboration time spent with cross-group connections after Microsoft went fully remote[^microsoft-remote-collaboration]
- 2 in 10 U.S. employees report having a best friend at work[^gallup-best-friend]
- About 4 the upper limit on people in a spontaneous conversation[^dunbar-conversation]
## The plan
Ask a senior leader to join in the first round and say so in the launch message. It tells people the time is allowed.
- Decide who it’s for: everyone, new hires, or people across two teams that need to work together.
- Make it opt-in. Use a channel people join, and say how to pause.
- Keep groups small: two to four people. Pairs are easiest to schedule; threes survive one person being busy.
- Pick a cadence: every two weeks or monthly. Run it for a full quarter before changing it.
- Match across teams, and avoid matching someone with their own manager or direct reports.
- Send a match message that names who books the time and gives one question to start with.
## Running it
Most of the work is in the first two rounds. After that, the program runs itself as long as people can pause and come back.
- Launch: one message in a company channel saying what it is, how often, how long a chat is and how to join.
- Each round: a group message that introduces everyone with a line about each person and suggests who books the time.
- Midway through the quarter: a reminder to people who joined but haven’t met anyone yet.
- End of quarter: share the numbers (people taking part, chats made, cross-team matches) and ask for one change.
## An example
A 300-person company with offices in two cities and a third of staff remote launches a coffee chat channel. 90 people join in the first two weeks.
HR sets groups of three, every two weeks, matched across departments. Each round makes 30 groups. Over a quarter that is six rounds and 180 introductions, and each person meets 12 coworkers they might not have met.
After the first month, 10 people pause during a product launch and come back the month after. At the end of the quarter HR shares the numbers in the launch channel and asks whether to move to monthly. Most say keep it every two weeks.
## Common mistakes
- Enrolling everyone by default instead of asking people to opt in.
- Running weekly matches for a large company and watching people mute them.
- Matching people with their own teammates, who already talk every day.
- Sending a match with no prompt, so nobody knows who should message first.
- Never telling people they can pause, so they leave for good instead.
## Launch message for a coffee chat program
```text
We’re starting coffee chats across teams.
Every two weeks you’ll be put in a small group of three with people from other teams. Meet for 20 minutes, on a call or in person, whenever suits you.
The first person named books the time. Not sure what to talk about? Start with: what are you working on that most of the company doesn’t know about?
Join #coffee-chats to take part. You can pause any time and come back when you’re ready. Leaving the channel takes you out.
```
## Do this in Shuffl
1. Connect the Shuffl app in Slack, then open Connections from the HR workspace and choose New program. Start from the Cross-team coffee template, or choose Review and start on the program Mello suggests.
2. Pick the Slack channel whose members take part. Joining the channel is how people opt in.
3. Under Who should meet whom?, choose People from different groups, departments or communities, set the group size, and under Keep coworkers apart avoid groups of managers and their direct reports.
4. Under Repeats, choose every 2 weeks or every month, set Starts and At, and write the introduction. The preview shows the Slack message.
5. Choose Start program, or use Run now to preview the groups before a round goes out.
6. Check Insights for who is taking part, first-time pairs and introductions across teams. People can take a break from the Home tab of the Shuffl app in Slack.
Guide: [Introduce coworkers with Connections](https://shuffl.ai/docs/markdown/connections)
- [Create an introduction program](https://shuffl.ai/docs/connections#program)
- [Choose who gets matched](https://shuffl.ai/docs/connections#matching)
- [Set the schedule and review rounds](https://shuffl.ai/docs/connections#schedule)
- [What employees see](https://shuffl.ai/docs/connections#employees)
## Common questions
### How many people should be in each coffee chat?
Small. Research on spontaneous conversation finds an upper limit of about four people talking together[^dunbar-conversation]. Pairs are the easiest to schedule; groups of three or four keep going when one person can’t make it.
### How often should coffee chats run?
Every two weeks or once a month suits most companies. Weekly works for a small, keen group but tends to wear people out. Pick one, run it for a quarter, and let people take a break without leaving.
### Should coffee chats be mandatory?
No. Make it opt-in, with an easy way to pause. People who chose to join turn up. People who were enrolled without asking cancel, and the person matched with them has a worse time than if there had been no match.
### How do I know the program is working?
Track who takes part, how many first-time pairs you made and how many matches crossed teams. A short question every quarter, such as whether people know someone outside their team they could ask for help, tells you whether it’s working.
## Glossary
- [Belonging](https://shuffl.ai/glossary/belonging)
- [Employee engagement](https://shuffl.ai/glossary/employee-engagement)
- [Employee experience](https://shuffl.ai/glossary/employee-experience)
- [Employee resource group](https://shuffl.ai/glossary/employee-resource-group)
- [Onboarding](https://shuffl.ai/glossary/onboarding)
- [Psychological safety](https://shuffl.ai/glossary/psychological-safety)
## Related playbooks
- [Plan a new hire’s first 90 days](https://shuffl.ai/playbooks/markdown/first-90-days)
- [Run an engagement check without survey fatigue](https://shuffl.ai/playbooks/markdown/engagement-check-in)
- [Build a recognition habit that lasts](https://shuffl.ai/playbooks/markdown/recognition-habit)
- [Celebrate milestones without it feeling automated](https://shuffl.ai/playbooks/markdown/celebrate-milestones)
## Sources
[^microsoft-remote-collaboration]: Nature Human Behaviour (via Microsoft Research), “The effects of remote work on collaboration among information workers”, September 2021. https://www.microsoft.com/en-us/research/publication/the-effects-of-remote-work-on-collaboration-among-information-workers/ Peer-reviewed study by Longqi Yang and colleagues using data on Microsoft employees’ work patterns before and after the firm-wide work-from-home mandate in March 2020. The 25% is a relative decline, not percentage points.
[^gallup-best-friend]: Gallup, “The Increasing Importance of a Best Friend at Work”, August 2022, updated January 2024. https://www.gallup.com/workplace/397058/increasing-importance-best-friend-work.aspx Gallup article by Alok Patel and Stephanie Plowman. 2022 poll of 16,586 U.S. adults who work for an employer, margin of error ±1 point at the 95% confidence level.
[^worldbank-water-coolers]: World Bank, Development Impact blog, “Onboarding summer interns in a virtual work environment: an experiment highlights the pros and cons of “virtual water coolers””, June 2021. https://blogs.worldbank.org/en/impactevaluations/onboarding-summer-interns-virtual-work-environment-experiment-highlights-pros-and David McKenzie’s summary of a randomized field experiment by Choudhury, Lane and Bojinov (HBS working paper 21-125) with the North American cohort of 1,370 remote summer interns at one global firm in 2020. 91.5% of interns received an offer overall.
[^dunbar-conversation]: Human Nature (via Northumbria University research portal), “Size and structure of freely forming conversational groups”, March 1995. https://researchportal.northumbria.ac.uk/en/publications/size-and-structure-of-freely-forming-conversational-groups/ Peer-reviewed paper by R.I.M. Dunbar, N.D.C. Duncan and D. Nettle, Human Nature 6(1), 67 to 78, using observations of conversations in various settings.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Handle a leaver well
> How to handle a leaver well: a checklist with owners, a real handover, access removed on the last day, an exit interview you act on and a door left open.
Audience: HR leads and people managers at startups and mid-size companies
Canonical: https://shuffl.ai/playbooks/when-someone-leaves-well
How someone leaves shapes what they say about you afterwards, whether they’d come back, and whether a former login turns into a security problem. Fewer than half of people who left a job by choice were satisfied with how their employer handled the exit[^gallup-exit-experience].
This playbook covers the checklist, the handover, the exit interview, removing access and keeping in touch. It isn’t legal advice; final pay, benefits and notice rules depend on where the person works.
## Why it matters
Gallup surveyed 716 U.S. adults who left an employer by choice in the past year. Only 22% were extremely satisfied and 21% satisfied with how the exit was handled. Just 17% said their manager actively supported them, and those leavers were 6.2 times as likely to be satisfied. Extremely satisfied leavers were far likelier to take a future offer: 24%, against 4% of everyone else[^gallup-exit-experience].
Many departures could have gone another way. 42% of voluntary leavers say their manager or organization could have done something to keep them, and 45% say no manager or leader talked with them about their satisfaction or future in the three months before they left[^gallup-preventable-turnover]. That’s what an exit interview is for: finding the next one before it happens.
Then there’s access. The SEI CERT guide, based on more than 3,000 insider threat cases, describes former staff using accounts that were never revoked, shared passwords that were never changed and equipment that was never returned[^sei-insider-guide].
**What a good exit is worth**
- 6.2x as likely to be satisfied with the exit when the manager reacted with support rather than negativity[^gallup-exit-experience]
- 42% of voluntary leavers say their manager or organization could have prevented them leaving[^gallup-preventable-turnover]
- 24% of leavers extremely satisfied with their exit would be extremely likely to accept a future offer, against 4% of the rest[^gallup-exit-experience]
- 10% of Fortune 500 CHROs say their company handles departures highly effectively[^gallup-exit-experience]
## The plan, from resignation to alumni
The SEI CERT guide recommends that a termination checklist lists each task, who does it, who verifies it and when it must be done, and goes back to HR before the person leaves[^sei-insider-guide]. Start from that and add your own systems.
- The day they tell you: the manager thanks them, agrees the last day and tells HR the same day.
- Within two days: HR opens the checklist and shares it with the manager, IT and payroll. Each task has an owner, a date and someone who checks it.
- First half of the notice period: the manager lists their projects, documents and relationships and names who takes each one.
- Second half: the leaver walks their successor through each item and writes down what isn’t written anywhere.
- Last day: equipment back, every account closed, shared passwords changed, final pay and benefits explained.
- A week later: the exit interview, then an invitation to stay in touch.
## Remove access, all of it
Access removal goes wrong at the edges: the tool one team bought on a card, the shared login for a supplier portal, the admin role nobody remembers granting. These items come from the SEI CERT termination checklist[^sei-insider-guide].
- Every system with a login: email, single sign-on, VPN, cloud services, specialised apps and company social media accounts.
- Shared accounts, service accounts and vendor portals. Change the passwords.
- Company equipment, badges, keys, access cards and two-factor tokens.
- Distribution lists, automated alerts and calendar invitations.
- Roles they held in HR tools: approvals, request queues, policy ownership and channel admin rights.
## The exit interview and keeping in touch
Read exit interviews in batches. One complaint about a manager is a story; four from the same team is a pattern. In a case Harvard Business Review describes, a department of 17 had only eight left a year after a new manager arrived, and the exit interviews pointed at the same cause[^hbr-exit-interviews].
Then keep the door open. A short note after they leave, an alumni channel or list, and a real welcome if they apply again.
- What made you start looking, or say yes to the other offer?
- What would have needed to be different for you to stay?
- How well did your manager support your growth?
- What should we keep doing?
- Would you consider coming back one day?
## An example
An account manager at an 80-person company resigns with four weeks’ notice. Her manager thanks her and agrees the last day. HR opens the checklist that afternoon with 22 tasks across HR, IT, payroll and her manager.
In week one, her manager lists 14 client accounts and names who takes each. In weeks two and three she introduces each new owner on a call. IT runs a report of every app she has signed into in the last 90 days and finds two supplier portals that aren’t on the list.
On her last afternoon she returns her laptop, and IT closes every account by 5 p.m. HR sends the exit interview a week later. Her answers match two other leavers from the same team, so HR raises workload with the team’s director. She joins the alumni list, and 18 months later she comes back as a team lead.
## Common mistakes
- Reacting badly when someone resigns, then expecting a warm exit.
- Running offboarding from memory instead of a checklist with owners and dates.
- Removing email and single sign-on but forgetting shared passwords and vendor portals.
- Leaving the handover to the last two days of the notice period.
- Collecting exit interviews and never reading them for patterns.
## Offboarding checklist
```text
For each task: owner, due date, checked by.
HR
[ ] Confirm the last day in writing
[ ] Share this checklist with the manager, IT and payroll
[ ] Explain final pay, unused leave and when benefits end
[ ] Send the exit interview a week after the last day
[ ] Record that their employment ended in your HR tools
Manager
[ ] List projects, documents, clients and recurring meetings
[ ] Name who takes each one
[ ] Tell the team the last day and who picks up their work
[ ] Reassign their direct reports, if any
IT
[ ] List every app they signed into in the last 90 days
[ ] Close every account at the end of the last day
[ ] Change shared and service account passwords
[ ] Collect laptop, phone, badge, keys and tokens
[ ] Remove them from distribution lists and alerts
Payroll
[ ] Process final pay by the local deadline
[ ] Collect company cards
```
## Do this in Shuffl
1. Open People, choose the person and expand Employment and access. Set Employment to Employment ended, write the last day under Reason for change, and choose Save access.
2. Reassign their reports: open People, then Org chart, and choose Set managers.
3. For HR requests they owned, another responder opens each one from the Inbox and chooses Take ownership. In Request settings, give each category they owned a new owner.
4. If they owned a community, an owner or moderator opens it, chooses Manage under Members and removes them, after making someone else an owner.
5. If they belonged to the company, open Settings → Company → Members and choose Remove from company, and revoke any company API keys they created.
6. With Sync from your HR system, Shuffl sets Employment ended when the provider reports them terminated. Handing on their roles, requests and communities is still yours to do.
Guide: [When someone leaves](https://shuffl.ai/docs/markdown/when-someone-leaves)
- [Record that someone has left](https://shuffl.ai/docs/when-someone-leaves#end-employment)
- [What stops at once](https://shuffl.ai/docs/when-someone-leaves#what-stops)
- [Hand on what they looked after](https://shuffl.ai/docs/when-someone-leaves#hand-over)
- [Remove them from the company](https://shuffl.ai/docs/when-someone-leaves#company)
- [When your HR system or identity provider says they left](https://shuffl.ai/docs/when-someone-leaves#automatic)
## Common questions
### When should access be removed?
On their last working day, at the end of the day, for every system. For a privileged user or a dismissal, earlier. The SEI CERT guide also says to change shared account passwords when a privileged user leaves[^sei-insider-guide].
### Who should run the exit interview, and when?
Someone other than their manager, ideally HR, about a week after they leave, when they’re likely to be more candid. Read the answers in batches for patterns rather than reacting to each one.
### When is the final paycheck due?
It depends on the state or country, and this playbook is not legal advice. Federal law in the U.S. doesn’t require the final paycheck immediately, but some states do[^dol-last-paycheck]. Check the local rule before the last day.
### What do we tell the team?
Say that they’re leaving, their last day and who picks up their work. You don’t need to say why. Once they’ve gone, the SEI CERT guide suggests a plain note that the person no longer works for the organization[^sei-insider-guide].
## Glossary
- [Offboarding](https://shuffl.ai/glossary/offboarding)
- [Exit interview](https://shuffl.ai/glossary/exit-interview)
- [Stay interview](https://shuffl.ai/glossary/stay-interview)
- [Employee turnover rate](https://shuffl.ai/glossary/employee-turnover-rate)
- [Attrition rate](https://shuffl.ai/glossary/attrition-rate)
- [Human resources information system](https://shuffl.ai/glossary/hris)
## Related playbooks
- [Run an engagement check without survey fatigue](https://shuffl.ai/playbooks/markdown/engagement-check-in)
- [Write HR policies people actually read](https://shuffl.ai/playbooks/markdown/hr-policies-people-read)
- [Your first 30 days as a solo HR person](https://shuffl.ai/playbooks/markdown/first-30-days-solo-hr)
- [Answer benefits and policy questions at scale](https://shuffl.ai/playbooks/markdown/answer-hr-questions-at-scale)
## Sources
[^gallup-exit-experience]: Gallup, “Enhancing the Employee Exit Experience Is Worth It”, July 2024. https://www.gallup.com/workplace/646937/enhancing-employee-exit-experience-worth.aspx Gallup article by Corey Tatel and Ben Wigert. Main study: web survey of 716 U.S. adults who voluntarily left an employer in the past year, fielded November 8 to 20, 2023, margin of error ±5 points. CHRO figure from 150 Fortune 500 CHROs, February to March 2024, margin of error ±12 points.
[^gallup-preventable-turnover]: Gallup, “42% of Employee Turnover Is Preventable but Often Ignored”, July 2024, updated February 2026. https://www.gallup.com/workplace/646538/employee-turnover-preventable-often-ignored.aspx Gallup article by Corey Tatel and Ben Wigert. Web survey of 717 U.S. adults who voluntarily left an employer in the past year, fielded November 8 to 20, 2023, from Gallup’s probability-based panel, margin of error ±5 points.
[^sei-insider-guide]: Software Engineering Institute, Carnegie Mellon University, “Common Sense Guide to Mitigating Insider Threats, Seventh Edition”, September 2022. https://www.sei.cmu.edu/library/common-sense-guide-to-mitigating-insider-threats-seventh-edition/ Software Engineering Institute (Carnegie Mellon University) guide with 22 best practices, based on the CERT Insider Threat Incident Repository of more than 3,000 cases. Best Practice 20 covers termination procedures and a termination checklist.
[^hbr-exit-interviews]: Harvard Business Review, “Making Exit Interviews Count”, April 2016. https://hbr.org/2016/04/making-exit-interviews-count Article by Everett Spain and Boris Groysberg. The figures cited are from one case the article describes, not a survey.
[^dol-last-paycheck]: US Department of Labor, “Last Paycheck”, Current guidance. https://www.dol.gov/general/topic/wages/lastpaycheck Federal regulator guidance on final pay.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Answer benefits and policy questions at scale
> Turn the HR questions you answer every week into a knowledge base people use, with a clear, private route to a person when the answer isn’t there.
Audience: HR teams of one to five people at growing companies
Canonical: https://shuffl.ai/playbooks/answer-hr-questions-at-scale
Most HR inboxes hold the same questions on repeat: how much leave is left, when open enrollment closes, how to claim an expense. Each one takes a few minutes. Together they take the week, and the person asking waits for an answer they could have read.
Self-service fixes this only when people find the answer. In a Gartner survey of 5,728 customers, just 14% of service issues were fully resolved in self-service, and in 43% of cases people couldn’t find content relevant to their issue[^gartner-self-service-2024]. So the work is mostly writing the right answers and keeping a person one step away.
## Why it matters
People already struggle to find what they need at work. In Gartner’s 2022 survey of 4,861 employees, 47% said they struggle to find the information or data they need to do their jobs well[^gartner-digital-worker-2023].
Handing them a portal doesn’t fix that on its own. Even for issues customers called very simple, only 36% were fully resolved in self-service[^gartner-self-service-2024]. That research covers customer service, but the lesson carries over to HR: the content has to exist, match how people phrase the question, and hand off to a person when it runs out.
**Self-service fails when people can’t find the answer**
- 47% of digital workers struggle to find the information they need to do their jobs[^gartner-digital-worker-2023]
- 14% of service issues are fully resolved in self-service[^gartner-self-service-2024]
- 43% of self-service attempts fail because people can’t find relevant content[^gartner-self-service-2024]
## The plan
Treat this as a small, steady practice rather than a project. The first pass takes a couple of weeks; after that it’s an hour or two a month.
- Count before you write. Export eight weeks of HR emails, direct messages and tickets, tag each with one topic, and rank the topics by volume.
- Write one page per topic, in employees’ words. Title it with the question (“How much time off do I get?”), put the answer in the first two lines, then the details.
- Put answers where people already ask. If questions arrive in Slack, the answer should be reachable from Slack, not three clicks deep in an intranet.
- Decide what always goes to a person and say so on every page, with how to reach HR and how fast you reply.
- Close the loop. When a question reaches HR, either link the page that answers it or write the missing page from your reply.
- Review monthly. Read the questions nobody could answer and the answers people flagged as wrong, then fix the source.
## What should always reach a person
Self-service is for the questions where the answer is the same for everyone in a group. The rest needs a person, and the route there should be one step, private and clearly owned. Set a first-reply target, such as one business day, and keep sensitive topics visible only to the people who handle them.
- Anything about one person’s pay, tax or a payroll error.
- Medical leave, accommodations and anything health related.
- Complaints, harassment and concerns about a manager.
- Exceptions to a policy, which need someone with authority to decide.
- Anything the person says is urgent or upsetting.
## A worked example
A 300-person company has two people in HR. Over eight weeks they log 400 questions. Ten topics account for about 260 of them: time off balances, sick leave, payroll dates, expense claims, benefits enrollment, parental leave, holidays, remote work, letters for landlords and banks, and updating bank details.
They write ten pages over two weeks, each titled with the question and owned by one of them, with a review date tied to the benefits renewal or the new year. Each page ends with “Still need help?” and a link to a private HR request. Pay errors, medical leave and complaints go straight to a named person.
A month in, they read the questions the pages didn’t cover. Three come up again and again: how to change a pension contribution, the policy on working abroad, and the notice needed for unpaid leave. They write those next, and drop a holidays page nobody opened because the calendar already answers it.
## Common mistakes
- Building the knowledge base from the policy manual instead of from the questions people ask.
- Hiding the route to a person to push self-service numbers up.
- Publishing answers with no owner or review date, so old benefits details linger.
- Counting deflected tickets and never reading the questions nobody could answer.
- Handling personal or sensitive cases in a public channel.
## Question log for your first audit
```text
One row per question, eight weeks back.
Date | Channel (email, Slack, in person) | Topic | Same answer for everyone? (yes/no) | Needed a person? (yes/no) | Page that answers it (or “missing”)
Topics to start with: time off, sick leave, payroll dates, pay errors, expenses, benefits, open enrollment, parental leave, holidays, remote work, letters, personal details, other.
When you’re done: sort by topic, count, and write pages for the top ten where the answer is the same for everyone.
```
## Do this in Shuffl
1. In Knowledge, choose Add source → Start from a template for topics such as paid time off, benefits and expenses, or Import a file for your handbook. A long handbook is split by its headings into one draft per section.
2. Set Who can read this after publishing? to Everyone in this workspace, set Effective date and Review by, then choose Review and publish and confirm with Publish source.
3. Ask Mello your ten most common questions in Chat, in the words employees use, and open Supporting sources on each answer. Where Mello found nothing or cited the wrong policy, fix the source.
4. Turn on HR responder in People for each person who answers requests. In Requests → Settings, give each category an owner, set the response target and turn on Only named people can open these requests for sensitive topics.
5. When you close a request, choose Mark resolved and pick the article that answers it, or Needs an article to start a Knowledge draft from your reply.
6. Once a month, open Knowledge → Insights and work through Missing guidance and Questions to test Mello on.
Guide: [Review and publish knowledge](https://shuffl.ai/docs/markdown/knowledge)
- [Add a source](https://shuffl.ai/docs/knowledge#add)
- [Publish deliberately](https://shuffl.ai/docs/knowledge#publish)
- [Verify what Mello proposes](https://shuffl.ai/docs/knowledge#verify)
- [See what Knowledge is doing](https://shuffl.ai/docs/knowledge#insights)
## Common questions
### How many articles do we need before we launch?
Fewer than you think. Tag two months of questions and write the topics that come up most first. For most teams that’s 5 to 10 pages: time off, sick leave, benefits, expenses, payroll dates, parental leave and holidays.
### Will people stop messaging HR directly?
Some people will keep messaging you directly, and that’s fine. Answer briefly with a link to the page, so next time they know where it lives. Never refuse to help someone because an article exists.
### What if the answer depends on who’s asking?
Write the rule and the cases it varies by, such as location or employment type, in a table. Anything that turns on one person’s situation, like a pay error or a medical leave, goes to a person.
### Should managers answer HR questions for their team?
Managers should know where the answers live and point people there. They shouldn’t become a second, unofficial help desk with their own versions of the policy.
## Glossary
- [HR knowledge base](https://shuffl.ai/glossary/hr-knowledge-base)
- [HR help desk](https://shuffl.ai/glossary/hr-help-desk)
- [Employee handbook](https://shuffl.ai/glossary/employee-handbook)
- [Employee benefits](https://shuffl.ai/glossary/employee-benefits)
- [Open enrollment](https://shuffl.ai/glossary/open-enrollment)
- [Paid time off](https://shuffl.ai/glossary/paid-time-off)
- [Employee experience](https://shuffl.ai/glossary/employee-experience)
## Related playbooks
- [Write HR policies people actually read](https://shuffl.ai/playbooks/markdown/hr-policies-people-read)
- [Your first 30 days as a solo HR person](https://shuffl.ai/playbooks/markdown/first-30-days-solo-hr)
## Sources
[^gartner-digital-worker-2023]: Gartner, “Gartner Survey Reveals 47% of Digital Workers Struggle to Find the Information Needed to Effectively Perform Their Jobs”, May 2023. https://www.gartner.com/en/newsroom/press-releases/2023-05-10-gartner-survey-reveals-47-percent-of-digital-workers-struggle-to-find-the-information-needed-to-effectively-perform-their-jobs Gartner Digital Worker Experience Survey, September to November 2022, 4,861 full-time employees who use digital technology for work at organizations with 100 or more employees in the US, UK, India and China.
[^gartner-self-service-2024]: Gartner, “Gartner Survey Finds Only 14% of Customer Service Issues Are Fully Resolved in Self-Service”, August 2024. https://www.gartner.com/en/newsroom/press-releases/2024-08-19-gartner-survey-finds-only-14-percent-of-customer-service-issues-are-fully-resolved-in-self-service Gartner survey of 5,728 customers conducted in December 2023 about customer service and support issues.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Write HR policies people actually read
> Write HR policies people can scan and act on: one topic per page, the answer first, plain language and a review date.
Audience: HR and people operations leads who own the handbook
Canonical: https://shuffl.ai/playbooks/hr-policies-people-read
Most policies are written to be complete. Few are written to be read. Yet people don’t read pages word by word: in Nielsen Norman Group’s research, 79% of test users always scanned a new page and only 16% read word by word[^nngroup-how-users-read].
A policy that can be scanned gets used. One that can’t turns into a question in your inbox. This playbook covers the structure, the wording and the upkeep that make the difference.
## Why it matters
The same Nielsen Norman Group study tested five versions of one site. Concise text scored 58% better on usability than a promotional control, a scannable layout 47% better, and a version that was concise, scannable and objective 124% better[^nngroup-how-users-read].
Reading skill varies more than most writers assume. The share of US adults scoring at Level 1 or below in literacy rose from 19% in 2017 to 28% in 2023[^nces-piaac-2024]. A policy pitched at a law graduate leaves many of your readers behind.
People also agree to things they haven’t read. In a study of 500 adults aged 50 and over, 77.6% accepted a privacy policy without opening it[^yorku-fine-print-2022]. An acknowledgement signature tells you someone clicked, not that they understood.
**People scan, and plain writing pays off**
- 79% of test users always scanned a new web page[^nngroup-how-users-read]
- 124% better usability when text was concise, scannable and objective[^nngroup-how-users-read]
- 28% of US adults scored at the lowest literacy levels in 2023[^nces-piaac-2024]
## One topic per page, in the same order
Use one page per topic. A reader searching for parental leave should land on parental leave, not page 31 of a handbook. Each page follows the same order, so people learn where to look.
- Title it with the question people ask: “Taking time off”, not “Leave of absence policy (rev. 4)”.
- Answer in the first two lines: how much, who qualifies, how to request it.
- Then who it applies to, and how it varies by location, employment type or tenure, in a table.
- Then the steps, numbered, with who approves and how long it takes.
- One or two short examples for the cases people get wrong.
- Who to ask, and what always goes to a person.
- The owner, effective date and next review date at the bottom.
## Write it plainly
Plain language doesn’t mean vague. Keep every condition the policy needs, and write it so someone reading on a phone between meetings can follow it. Have your usual reviewer check that the plain version still says what you mean. This playbook isn’t legal advice.
- Write to the reader: “you” for the employee, “we” for the company.
- Keep most sentences under 20 words, and one idea per sentence.
- Use the active voice: “Your manager approves the request”, not “Requests will be approved”.
- Say “must” for requirements. Drop “shall”, “hereinafter” and “pursuant to”.
- Use numerals for numbers and dates, and name the time zone or calendar that applies.
- Define a term the first time you use it, then use the same word every time.
## A worked example
A 150-person company has a 40-page handbook in a PDF. HR gets about 30 time off questions a month, most of them answered on page 12.
They split the handbook into 15 pages, one per topic, and rewrite the time off page first: the answer in two lines, a table for the two countries they employ in, three steps to request leave, and a note on who to ask. Each page names an owner and a review date in January.
They keep the old PDF for the record, mark it as replaced, and link every old reference to the new pages.
**The same time off rule, rewritten**
Before:
- Eligible employees shall accrue paid time off in accordance with the schedule set forth in Appendix C, subject to managerial approval, which shall not be unreasonably withheld.
- Unused entitlement may, at the discretion of the Company, be carried forward subject to the limits hereinafter described.
After:
- You get 25 days of paid time off a year, plus public holidays.
- Ask your manager at least 2 weeks ahead for anything over 3 days.
- Up to 5 unused days carry over to next year. Use them by 31 March.
## Common mistakes
- Opening with purpose and scope statements instead of the answer people came for.
- Putting several topics on one long page, so search lands people in the wrong place.
- Writing for a lawyer reading at a desk, not an employee reading on a phone.
- Leaving out who to ask, so every unclear case becomes a guess.
- Publishing without an owner or a review date.
## Policy page outline
```text
Title: the question people ask (for example, “Taking time off”)
The short answer: two lines. How much, who qualifies, how to ask.
Who this applies to: a table if it differs by location, employment type or tenure.
How to do it:
1. …
2. …
3. …
Examples: one or two cases people get wrong.
Who to ask: the team or person, and what always goes to them.
Owner: … Effective: … Next review: …
```
## Do this in Shuffl
1. In Knowledge, choose Add source → Import a file for your handbook. A long handbook is split by its headings into one draft per section, so you start with one page per topic.
2. Or choose Write an article and use Write with Mello to draft a page from its title and a short request. Nothing is saved until you save it.
3. For each draft, read the extracted text, rewrite it in plain language, set Who can read this after publishing? and choose Save draft.
4. Set Effective date and Review by. On the review date the source stops being used in answers until someone reviews it.
5. Choose Review and publish, check the summary and confirm with Publish source. Version history keeps every published version.
6. To change a live policy, choose Edit draft. Employees keep the last published version until you review and publish the new one.
Guide: [Review and publish knowledge](https://shuffl.ai/docs/markdown/knowledge)
- [Add a source](https://shuffl.ai/docs/knowledge#add)
- [Start with a draft](https://shuffl.ai/docs/knowledge#draft)
- [Publish deliberately](https://shuffl.ai/docs/knowledge#publish)
- [Keep sources current](https://shuffl.ai/docs/knowledge#maintain)
## Common questions
### Does plain language make a policy less legally precise?
No. Plain language changes the wording, not the rule. Keep the precise terms where they matter, define them once, and have whoever reviews your policies for legal meaning read the plain version too. This playbook isn’t legal advice.
### Should we still have a single handbook document?
Keep one source of truth and link to it. If the handbook PDF and the intranet page say different things, people will find the wrong one. Split a long handbook into one page per topic and retire the copies.
### How often should we review policies?
At least once a year, and whenever the law, a benefits plan or the way you actually work changes. Put the review date on the page so readers can see it’s current.
## Glossary
- [Employee handbook](https://shuffl.ai/glossary/employee-handbook)
- [HR knowledge base](https://shuffl.ai/glossary/hr-knowledge-base)
- [Paid time off](https://shuffl.ai/glossary/paid-time-off)
- [Employee benefits](https://shuffl.ai/glossary/employee-benefits)
- [People operations](https://shuffl.ai/glossary/people-operations)
## Related playbooks
- [Answer benefits and policy questions at scale](https://shuffl.ai/playbooks/markdown/answer-hr-questions-at-scale)
- [Your first 30 days as a solo HR person](https://shuffl.ai/playbooks/markdown/first-30-days-solo-hr)
## Sources
[^nngroup-how-users-read]: Nielsen Norman Group, “How Users Read on the Web”, September 1997. https://www.nngroup.com/articles/how-users-read-on-the-web/ Jakob Nielsen’s usability research with test users, including a test of five versions of the same site with the same tasks.
[^nces-piaac-2024]: National Center for Education Statistics, Institute of Education Sciences, “U.S. Adults Score on Par With International Average in Literacy Skills, Below International Average in Numeracy and Problem-Solving Skills in Survey of Adult Skills”, December 2024. https://ies.ed.gov/learn/press-release/u-s-adults-score-par-international-average-literacy-skills-below-international-average-numeracy-and NCES press release on the 2023 US results of the Programme for the International Assessment of Adult Competencies (PIAAC).
[^yorku-fine-print-2022]: York University (YFile), “York researcher warns online consumers to read fine print”, December 2022. https://www.yorku.ca/yfile/?p=325935 York University news story on Jonathan Obar’s study of 500 adults aged 50 and over using a fictitious social network.
Agent documentation index: https://shuffl.ai/llms.txt
---
# Your first 30 days as a solo HR person
> A week-by-week plan for a startup’s first HR hire: listen, audit the basics, write the policies people need and share a plan.
Audience: The first HR hire at a startup or small company
Canonical: https://shuffl.ai/playbooks/first-30-days-solo-hr
You’re the first person whose job is HR. Founders have been doing it on the side, there’s a folder of contracts somewhere, and everyone has a list of things you should fix. The first month decides whether you become the person who answers questions or the person who builds how the company works.
This plan spends the first two weeks listening and checking what’s legally required, then turns that into a short list of policies, an onboarding routine and a plan you can share. It’s a general guide, not legal advice: rules differ by country, state and company size.
## Why it matters
Some HR work has a clock on it from day one. In the US, employers must complete Section 2 of Form I-9 within 3 business days of the date of hire[^uscis-i9-section-2]. In the UK, employers must give the principal statement of employment particulars on the first day, and the wider written statement within 2 months[^govuk-written-statement]. Check the rules where your people work.
The rest is about how people experience the company. Only 12% of employees strongly agree their organization does a great job onboarding new employees[^gallup-onboarding-2018]. At a startup that is hiring every month, onboarding is one of the first things you can fix that everyone notices.
**What the first HR hire inherits**
- 12% of employees strongly agree their organization does a great job onboarding new employees[^gallup-onboarding-2018]
- 3 business days to complete Section 2 of Form I-9 after a US hire’s start date[^uscis-i9-section-2]
- Day one when UK employers must give the principal written statement[^govuk-written-statement]
## The plan, week by week
Resist fixing things as you find them, except anything with a legal deadline or someone’s pay at stake. You’ll make better choices once you’ve seen the whole picture.
- Week 1, listen. Meet each founder and manager, and as many employees as you can, for 30 minutes each. Ask the same questions every time and write down what you hear.
- Week 2, audit. Go through records, contracts, payroll, benefits, time off and access with the checklist below. Mark each item fine, fix now or fix later.
- Week 3, write. Publish the 5 to 10 policies people ask about most, starting with time off, sick leave, expenses and benefits. Fix anything marked fix now.
- Week 4, build and share. Write a simple onboarding checklist for the next hire, choose where people will find answers, and share a one-page plan for the next 90 days with the leadership team.
## What to audit
This is a list of what to look at, not a complete compliance review. Requirements depend on where people work and how many you employ, so confirm anything uncertain with an employment lawyer or the regulator for that location.
- A complete file for everyone: signed contract or offer letter, right-to-work paperwork where it applies, tax forms and emergency contact.
- Payroll: pay dates, overtime eligibility and how each role is classified (employee or contractor, exempt or non-exempt where that applies).
- Benefits: what’s offered, who administers it, eligibility rules and the next renewal or enrollment date.
- Required workplace notices and posters for each location, including remote workers.
- Time off: the actual policy, where balances are tracked and how requests are approved.
- Access: who can see personnel files and salaries, and how leavers lose access to systems.
- Open issues: complaints, investigations or leave cases that someone was handling informally.
## A worked example
A 60-person startup hires its first HR manager. In week one she meets the 3 founders, 8 managers and 20 employees. The same three themes come up: nobody knows the time off rules, new hires spend their first day waiting for a laptop, and pay questions go to the CEO.
Her audit in week two finds 4 contractors working full time on core roles and 2 new hires with incomplete right-to-work paperwork. She fixes the paperwork that week and takes the contractor question to an employment lawyer.
In week three she publishes 6 policies and tells everyone where to find them. In week four she writes a two-page onboarding checklist with IT, starts a monthly one-question check-in, and shares a 90-day plan: choose an HRIS, settle the contractor roles and run the first benefits renewal.
## Common mistakes
- Rewriting everything in week one before you know what’s broken.
- Treating compliance as a later project when some deadlines start on a new hire’s first day.
- Buying an HRIS before you know your payroll, benefits and headcount plan.
- Listening only to founders and skipping employees and managers.
- Keeping your plan in your head instead of sharing it with the leadership team.
## Listening session questions
```text
Use the same questions with everyone, 30 minutes each.
1. What’s working well here that we should protect?
2. What HR question did you last have, and how did you get the answer?
3. What was your first week like? What would have helped?
4. Is there anything about pay, time off or benefits you’re unsure of?
5. If you could fix one thing about how we work, what would it be?
6. Who else should I talk to?
For managers, add:
7. What do you spend time on that HR should own?
8. Which people decisions do you feel least sure about?
```
## Do this in Shuffl
1. Open Settings → Setup from the HR workspace and choose Connect Slack. Everyone appears in People waiting for access. Leave them waiting until launch, because turning access on sends each person a welcome message.
2. Add the 5 to 10 policies people ask about most, from a template or your own file. Check the text, set the audience to Everyone in this workspace and publish each one.
3. Take the ten questions you heard most in your listening sessions and ask each in Chat, in the words people used. Open Supporting sources and fix any source Mello missed or got wrong.
4. On launch day, use Copy post on the Tell your team what they can ask card in Today, send the post, then turn on access in People with Enable access for N people in the same hour.
5. Turn on programs one at a time, about a week apart: Pulse with Start pulse first, then Onboarding before your next hire starts.
6. At the end of the first week, open Knowledge → Insights for Missing guidance and set up the HR digest under Settings → Notifications.
Guide: [Roll out Shuffl to your company](https://shuffl.ai/docs/markdown/rollout)
- [Before launch: get Mello ready](https://shuffl.ai/docs/rollout#before-launch)
- [Ask Mello what your team will ask](https://shuffl.ai/docs/rollout#test-mello)
- [Launch: tell your team](https://shuffl.ai/docs/rollout#launch)
- [Turn on programs in order](https://shuffl.ai/docs/rollout#programs)
- [The first week: where to look and what to fix](https://shuffl.ai/docs/rollout#first-week)
## Common questions
### What should I fix first?
Whatever has a legal deadline or puts someone’s pay at risk. Check that new hires’ paperwork is complete, payroll and classification are right, and required notices are in place. Everything else can wait a week.
### Do I need an HRIS right away?
Probably not in month one. Start from what you have, even a spreadsheet, and write down what you need it to do. Choose a system once you know your headcount plan, payroll setup and where people already work.
### Is this legal advice?
No. It’s a general checklist of what to look at. Employment rules differ by country, state and company size, so confirm anything you’re unsure of with an employment lawyer or the relevant regulator.
## Glossary
- [People operations](https://shuffl.ai/glossary/people-operations)
- [Human resources information system](https://shuffl.ai/glossary/hris)
- [Employee handbook](https://shuffl.ai/glossary/employee-handbook)
- [Onboarding](https://shuffl.ai/glossary/onboarding)
- [Preboarding](https://shuffl.ai/glossary/preboarding)
- [Exempt employee](https://shuffl.ai/glossary/exempt-employee)
- [Employee benefits](https://shuffl.ai/glossary/employee-benefits)
- [One-on-one meeting](https://shuffl.ai/glossary/one-on-one-meeting)
- [Pulse survey](https://shuffl.ai/glossary/pulse-survey)
## Related playbooks
- [Plan a new hire’s first 90 days](https://shuffl.ai/playbooks/markdown/first-90-days)
- [Write HR policies people actually read](https://shuffl.ai/playbooks/markdown/hr-policies-people-read)
- [Answer benefits and policy questions at scale](https://shuffl.ai/playbooks/markdown/answer-hr-questions-at-scale)
- [Run an engagement check without survey fatigue](https://shuffl.ai/playbooks/markdown/engagement-check-in)
## Sources
[^gallup-onboarding-2018]: Gallup, “Why the Onboarding Experience Is Key for Retention”, May 2018. https://www.gallup.com/workplace/235121/why-onboarding-experience-key-retention.aspx Gallup workplace article drawing on Gallup’s research on onboarding.
[^uscis-i9-section-2]: US Citizenship and Immigration Services, “Completing Section 2, Employer Review and Attestation”, Current guidance. https://www.uscis.gov/i-9-central/completing-form-i-9/completing-section-2-employer-review-and-attestation Federal agency guidance for employers completing Form I-9. Page last reviewed September 2026.
[^govuk-written-statement]: GOV.UK, “Employment contracts and conditions: Written statement of employment particulars”, Current guidance. https://www.gov.uk/employment-contracts-and-conditions/written-statement-of-employment-particulars UK government guidance on the written statement of employment particulars.
Agent documentation index: https://shuffl.ai/llms.txt
---