smileback

SmileBack API Patterns

Overview

SmileBack collects customer feedback for MSPs: a one-click CSAT reaction on each closed PSA ticket, NPS campaigns, and project surveys. The Conduit connector reads that data through SmileBack's Data Replication API v3. The API itself is read-only (OAuth scopes read and read_recent), so every tool is a GET. Nothing can create, change or delete data in SmileBack. Follow-up actions happen in the PSA.

Connection

Claude Code reaches SmileBack through Conduit's unified endpoint (https://conduit.wyre.ai/v1/mcp, via wyre-gateway). Conduit stores five values when you connect SmileBack in the Conduit web UI (/connect/smileback) and maps them to these headers on every call. Nothing is set on the client, and Conduit drops any X-SmileBack-* header a client sends:

Conduit field	Header	Required
Client ID	X-SmileBack-Client-Id	Yes
Client Secret	X-SmileBack-Client-Secret	Yes
Username (email)	X-SmileBack-Username	Yes
Password	X-SmileBack-Password	Yes
Region	X-SmileBack-Region	No (us or eu, default us)

• Client ID and Client Secret come from the SmileBack Account menu > API Credentials (one pair per account).
• Username and password are the email and native SmileBack password of the user Conduit signs in as. Native credentials work even when ConnectWise SSO is on. They also sign in to the SmileBack web app, so use a dedicated user for API access.
• Region: us is app.smileback.io. Pick eu only if the account lives on app.smileback.eu. There is no base-URL field; the server only ever calls one of those two hosts.

The server runs the OAuth2 password grant itself, caches the access token, and on a 401 fetches one fresh token and retries once. Refresh tokens are not used.

Conduit Access Tiers

All 12 tools are classified read in Conduit. None is admin-gated and none is a write, so any Conduit role that can read the SmileBack connector sees the whole surface. Two consequences the tier does not show:

• One credential set reads the MSP's entire SmileBack dataset across every client. SmileBack has no per-client scoping.
• Reviews, NPS responses, contacts and project responses contain end customers' personal data: names, emails, titles, locations, free-text comments and marketing-permission flags. Share output only with people allowed to see it, and strip emails from anything client-facing.

Conduit does not cache SmileBack results, so every call reaches SmileBack.

Tool Surface

Tool	Endpoint	Parameters	Paged
smileback_reviews_list	GET /reviews/	modified_since, include_unrated, limit, offset	Yes
smileback_reviews_list_recent	GET /reviews/recent/	limit, offset	Yes
smileback_reviews_get	GET /reviews/{review_id}/	review_id (required)	No
smileback_nps_responses_list	GET /nps-responses/	created_since, campaign_name, score_gt, score_lt, score_exact, limit, offset	Yes
smileback_nps_responses_get	GET /nps-responses/{response_id}/	response_id (required)	No
smileback_nps_campaigns_list	GET /nps-campaigns/	none	No
smileback_csat_companies_list	GET /csat-companies/	none	No
smileback_csat_contacts_list	GET /csat-contacts/	none	No
smileback_csat_agents_list	GET /csat-agents/	none	No
smileback_csat_boards_list	GET /csat-boards/	none	No
smileback_project_surveys_list	GET /prj-surveys/	none	No
smileback_project_responses_list	GET /prj-responses/	created_since	No

What the records hold:

• Review (CSAT): rating, comment, ticket (id, title, segment = the PSA board, agents, closed_on), contact, company (id, name, territory, market), status, tags, rated_on, permalink, last_modified.
• NPS response: score (0-10), comment, has_marketing_permission, contact (name, email, company, title, location), contact_remote_id, campaign_name, created_at.
• CSAT company: the MSP's end clients, with territory, market and PSA remote IDs.
• CSAT agent: the MSP's active technicians. CSAT board: PSA service boards (a review's ticket.segment).

SmileBack's CSAT reaction is a three-point scale (positive, neutral, negative). Read the rating values on the first page you fetch before computing anything, rather than assuming how they are encoded.

Filtering Happens Client-Side

The API has no per-company filter, no aggregate endpoint and no date upper bound. To get a client's CSAT for a quarter:

1. Call smileback_reviews_list with modified_since set to the start of the window and page to the end.
2. Keep reviews whose company.id matches and whose rated_on falls inside the window.

modified_since filters on last_modified, not rated_on. A review rated last year but edited this week comes back, so the rated_on filter in step 2 is required. Every review rated inside the window has last_modified at or after rated_on, so nothing is missed. When you also need a response rate (include_unrated: true), place rated and unrated reviews by ticket.closed_on instead, as smileback-csat-qbr-summary does, so both come from the same cohort.

NPS responses are grouped by contact.company, which is a name, not the CSAT company ID. Match names carefully and report any responses whose company you could not match.

Dates are ISO 8601 dates or date-times (2026-10-01 or 2026-10-01T00:00:00Z). NPS score filters are integers 0-10; detractors are score_lt: 7.

Pagination

smileback_reviews_list, smileback_reviews_list_recent and smileback_nps_responses_list use limit/offset and return {count, next, previous, results} as SmileBack sent it.

• limit defaults to 50 and is capped at 100.
• The server never pages for you. Keep calling with a larger offset until next is null, and compare the rows you collected with count before calling a set complete.
• The other lists are not paginated. smileback_project_responses_list returns everything since created_since, so always pass it.

Truncated Responses

Output is capped at about 60,000 characters. When a page is larger, items are dropped from the end of results and the response adds truncated: true, returned_items, total_items_in_page and a truncation_hint. count, next and previous are kept unchanged.

On a truncated page, the next offset is the current offset plus returned_items. The next URL assumes the whole page arrived, so following it skips the dropped rows. Lower limit (25 works well for reviews with long comments) and continue. If even the first item is too large, results is empty and first_item_truncated holds the start of it; fetch that record on its own with smileback_reviews_get or smileback_nps_responses_get.

Errors

Vendor errors come back as tool errors with the HTTP status, the OAuth error code from the token endpoint, and SmileBack's message.

Error	Meaning	Fix
invalid_client	Client ID or Client Secret wrong, or the wrong region	Copy both again from Account > API Credentials; confirm us or eu
invalid_grant	Username or password wrong, or the wrong region	Use the user's email and native SmileBack password; confirm the region
HTTP 401 with no SmileBack status	A required field is missing from the Conduit connection	Reconnect SmileBack in Conduit with all four required fields
404	Unknown review or response ID	Re-list; IDs are integers
Argument error	Bad date, score outside 0-10, empty campaign name	Fixed client-side; never reached SmileBack

Rate Limits

SmileBack publishes no rate limit but asks integrators to keep bandwidth low. The server retries only a 401. On a 429 or a 5xx, wait before retrying and do not loop. Use modified_since and created_since to read only what changed rather than re-pulling full history, and pull a quarter once, then compute every client from that one pull.

Related Skills

• smileback-csat-qbr-summary builds a per-client CSAT/NPS review.
• smileback-detractor-follow-up triages negative reviews and NPS detractors.
• smileback-technician-csat reports CSAT by technician and board.

SmileBack CSAT and NPS QBR Summary

Overview

A QBR satisfaction slide answers three questions for one client: how satisfied were they with ticket support this quarter, is that better or worse than last quarter, and what are they telling us in their own words. SmileBack holds the raw feedback; it has no per-client score endpoint, so the numbers are computed here from the individual reviews and responses. All tools used below are Conduit read tier; none is admin-gated.

Anti-triggers

• Acting on a bad review (calling the contact back, opening a follow-up ticket): use smileback-detractor-follow-up.
• Ranking or coaching technicians: use smileback-technician-csat. A client QBR reports the service, not individual techs.
• Crewhu survey data: use crewhu-surveys. This skill reads SmileBack only.

Workflow

1. Resolve the client

Call smileback_csat_companies_list and find the client by name. Note its id (for reviews) and exact name (for NPS, which groups by contact company name). If two companies match, ask which one; do not merge them silently.

2. Pull two quarters of reviews in one pass

Take the quarter from the request (default: the last full quarter); the comparison quarter is the one before it. Call smileback_reviews_list with modified_since set to the start of the comparison quarter and include_unrated: true, paging until next is null (see smileback-api-patterns for truncated pages). One pull covers both quarters for every client, so reuse it if you are preparing several QBRs.

Keep rows where company.id is the client. Assign every review, rated or not, to a quarter by ticket.closed_on (when the survey went out), and use rated_on only when closed_on is missing. Using the same date for rated and unrated reviews keeps the response rate on one cohort.

modified_since returns anything edited since that date, so drop rows whose cohort date is before the comparison quarter or after the requested quarter.

3. Compute CSAT

For each quarter:

Metric	Formula
Surveys sent	rated + unrated reviews
Response rate	rated / surveys sent
Positive share	positive / rated
Negative share	negative / rated
Net satisfaction	positive share minus negative share

Check the rating values on the first page before counting. If SmileBack's own dashboard shows a different headline number, say which formula you used rather than adjusting yours to match.

Break the quarter down by ticket.segment (the PSA board) when the client has tickets on more than one board; a dip is often one board.

4. Compute NPS

Call smileback_nps_campaigns_list to see which campaigns ran, then smileback_nps_responses_list with created_since at the start of the comparison quarter (add campaign_name if the MSP runs more than one), paging until next is null and handling truncated pages as for reviews. Keep responses whose contact.company matches the client name, and place each in a quarter by created_at. created_since has no upper bound, so drop responses created after the requested quarter.

NPS = % promoters (9-10) minus % detractors (0-6), from -100 to +100. Report the response count next to the score. List any responses whose company you could not match to a CSAT company instead of dropping them.

5. Project surveys, if any

If the client had a project this quarter, call smileback_project_surveys_list and smileback_project_responses_list with created_since at the quarter start, and drop responses created after the quarter if it is a past one. Filter to the client using the contact or company on each response if present; if the responses do not identify the client, say so instead of guessing.

6. Choose comments

Pick two or three comments that represent the quarter: the most common positive theme, and any negative theme that appears more than once. Quote the comment text and the ticket title. Leave out contact emails; use first names only if the QBR audience is the client's own staff. For NPS promoters, only reuse a comment outside the QBR (case study, website) when has_marketing_permission is true.

Output

Customer satisfaction - <Client>, <Quarter>

CSAT (ticket feedback)            This quarter   Last quarter
  Surveys sent                    142            128
  Response rate                   38%            41%
  Positive / neutral / negative   49 / 3 / 2     46 / 4 / 3
  Net satisfaction                +87            +81

NPS (<campaign>)                  +45 (n=11)     +30 (n=10)

By board: Service Desk +90 (n=44), Projects +70 (n=10)

What they said
  + "Fixed before I finished my coffee" - Printer offline at reception
  - "Took three days to hear back" - VPN drops in the afternoon (2 similar)

Gotchas

• Small samples. Under about 20 rated reviews, one negative moves net satisfaction by several points. Show n next to every score and describe a change between small samples as a direction, not a trend. NPS with fewer than 10 responses is anecdotal; say so.
• Response rate matters as much as the score. A falling response rate with a rising score usually means fewer unhappy people are bothering to answer.
• One credential, every client. The pull returns every client's feedback. Make sure nothing from other clients reaches this client's deck.
• Departed contacts and techs still appear on old reviews. That is expected; report the service, not the people.

SmileBack Detractor Follow-Up

Overview

A negative reaction on a closed ticket is the cheapest churn signal an MSP gets, and it goes stale in days. This workflow finds the recent negative and neutral CSAT reviews and NPS detractors, gives the service manager enough context to call the customer, and flags patterns that point at a client relationship rather than a single ticket.

SmileBack's API is read-only. Every tool here is Conduit read tier, none is admin-gated, and none can mark a review as handled. The follow-up itself (call, ticket, note) is recorded in the PSA.

Anti-triggers

• Quarterly satisfaction numbers for a client: use smileback-csat-qbr-summary.
• A technician's overall CSAT record: use smileback-technician-csat. This skill is about the customer, not the tech's scorecard.

Workflow

1. Collect recent negatives

• Daily or weekly sweep: smileback_reviews_list_recent, paged to the end.
• A specific window: smileback_reviews_list with modified_since at the window start, paged to the end, then keep reviews whose rated_on is inside the window.

Keep negative reviews. Include neutral ones as a second tier: a neutral with a comment is often a complaint in polite form. Check the rating values on the first page to see how the three reactions are encoded.

2. Collect NPS detractors

smileback_nps_responses_list with score_lt: 7 and created_since at the window start, paging until next is null and handling truncated pages as smileback-api-patterns describes, so no detractor is left on a later page. created_since has no upper bound, so for a past window keep only responses whose created_at is inside it. A detractor with a comment goes in the main list; a bare 5 or 6 with no comment goes in the second tier.

3. Enrich each case

For each review, smileback_reviews_get gives the full record:

• ticket (id, title, segment, agents, closed_on): which ticket, which board, who worked it, and how long ago it closed.
• comment: the customer's words. A negative with no comment needs a call more than one with a clear explanation.
• status and tags: what SmileBack already records about follow-up. If they show the review was already handled, do not open a second follow-up.
• permalink: the link the service manager opens in SmileBack.

For an NPS detractor, smileback_nps_responses_get gives the contact's title and company. A detractor who is the client's owner or IT contact matters more than one who is a seasonal user.

4. Look for patterns

Group the cases before reporting:

• Repeat contact: the same contact negative more than once in 90 days. Pull 90 days with smileback_reviews_list if the window was shorter.
• Client cluster: three or more negatives, or a negative plus an NPS detractor, from one company in the window. That is a relationship conversation for the account manager, not a ticket call-back.
• Board cluster: negatives concentrated on one ticket.segment point at a process problem on that board.

5. Hand off to the PSA

SmileBack cannot record the follow-up. For each case, give the service manager what they need to open or update the PSA ticket: the PSA ticket ID from ticket.id, the contact, the comment, and the suggested owner. If a PSA plugin is connected, offer to add a note to the original ticket, and wait for the operator to confirm before writing anything.

Output

Detractor follow-up - <window>

Call today (3)
  Acme Dental - Jane (Office Manager) - negative, 2 days ago
    Ticket 48812 "Email not syncing on phone" - Service Desk - worked by Sam
    "Third time this month. Nobody called me back."
    Repeat contact (2 negatives in 30 days) - open in SmileBack: <permalink>

Watch (2)
  Brightline Law - NPS 5, no comment - Partner

Patterns
  Acme Dental: 3 negatives + 1 NPS detractor this month -> account manager
  Projects board: 4 of 6 negatives this week

Leave contact emails out of anything posted to a shared channel; the permalink is enough to reach the full record.

Gotchas

• Speed matters more than completeness. Report the call-today list first, then patterns.
• Neutral is not positive. Do not fold neutrals into "fine" when counting at-risk clients.
• Multiple agents. ticket.agents can list several technicians. Name all of them; do not blame the last one.
• Old tickets resurfacing. A review edited today on a ticket closed months ago shows up in a modified_since pull. Filter on rated_on.

SmileBack Technician and Board CSAT

Overview

SmileBack attaches every review to a ticket, and every ticket to a board and the technicians who worked it. That makes it the most direct measure of how customers experience each tech and each board. This skill turns a period of reviews into a fair per-tech and per-board view for coaching and recognition. All tools used are Conduit read tier; none is admin-gated.

Anti-triggers

• A client's satisfaction for a QBR: use smileback-csat-qbr-summary.
• Calling back an unhappy customer: use smileback-detractor-follow-up.
• Badges, contests and prizes for techs: use crewhu-surveys or the rest of the Crewhu plugin. SmileBack has no recognition features.

Workflow

1. Reference lists

Call smileback_csat_agents_list for the active technicians and smileback_csat_boards_list for the PSA boards. The agent list holds active techs only; techs who have left still appear on older reviews. Report them under "former staff" rather than dropping their reviews.

2. Pull the period

smileback_reviews_list with modified_since at the period start and include_unrated: true, paged to the end. Keep reviews, rated or not, whose ticket.closed_on is in the period (fall back to rated_on when closed_on is missing), so rated and unrated reviews come from the same cohort and the response rate is not skewed. A month is the shortest useful period for one tech; a quarter is better.

3. Attribute

• Per tech: credit each review to every agent in ticket.agents. Say in the output that multi-agent tickets count once per agent, so per-tech totals add up to more than the board total.
• Per board: group by ticket.segment. Each review counts once.

4. Compute

For each tech and board: surveys sent, response rate, and the positive / neutral / negative counts, with net satisfaction (positive share minus negative share). Check the rating values on the first page before counting.

Do not rank anyone with fewer than 10 rated reviews in the period. List them separately with their counts and no score.

5. Pick the stories

• Recognition: positive reviews with a comment that names the tech or describes something specific. These are worth reading out in a team meeting.
• Coaching: negatives where the comment points at something the tech controls (communication, follow-through, tone) rather than at the client's environment or a vendor outage. Quote the comment and link the permalink.

Output

Technician CSAT - <period>

Tech        Sent  Resp.  +  =  -   Net   Notes
Sam          96   41%   37  2  0  +95
Priya        88   36%   28  2  2  +81   2 negatives on Projects board
Alex         71   30%   20  1  0  +95
Jordan        9    -     6  0  1   -    under 10 rated, not scored

Board          Rated  Net
Service Desk    118   +90
Projects         24   +71

Multi-agent tickets count once per agent.

Gotchas

• Response rate shapes the score. A tech whose customers rarely answer can look perfect on six reviews. Show response rate beside every score.
• Board mix. Techs on a projects or onboarding board get harder tickets. Compare techs on the same board before comparing across boards.
• Context before conclusions. A cluster of negatives during a vendor outage is not a coaching issue. Check ticket titles before attributing a dip to a person.
• Sharing. Comments include customers' names and words. A per-tech report is for the tech and their manager, not a team-wide channel.

You are a customer-satisfaction analyst for an MSP, working from SmileBack through Conduit. You build the satisfaction section of quarterly business reviews: what the client's people thought of ticket support this quarter, how that compares with last quarter, and what they said in their own words. SmileBack holds raw reviews and NPS responses but no per-client scores, so the numbers are yours to compute, and the value you add is computing them the same way every time and saying plainly when a sample is too small to mean anything.

You start by resolving scope. For each client named, you find it in smileback_csat_companies_list and record its id and exact name; if a name matches two companies you stop and ask. You take the quarter from the request (the last full quarter if none is named) and compare it with the quarter before it. Then you pull data once for the whole job: smileback_reviews_list with modified_since at the start of the comparison quarter and include_unrated: true, paged until next is null and checked against count, and smileback_nps_responses_list with created_since at the same date, after reading smileback_nps_campaigns_list to know which campaigns ran. On a truncated page you continue from offset plus returned_items with a smaller limit, never from the next URL. One pull serves every client in the request; you never re-pull per client.

You then compute per client and per quarter, following the smileback-csat-qbr-summary skill: reviews filtered by company.id and placed in a quarter by ticket.closed_on whether rated or not (rated_on only when closed_on is missing), so the response rate compares one cohort; surveys sent, response rate, positive / neutral / negative counts and net satisfaction; a breakdown by ticket.segment when the client uses more than one board; NPS from responses whose contact.company matches the client name, placed in a quarter by created_at (dropping any created after the requested quarter), with unmatched responses listed rather than dropped. Where the client ran a project, you read smileback_project_surveys_list and smileback_project_responses_list with created_since at the quarter start, and you say so if the responses do not identify the client. You check the rating encoding on the first page before counting anything. For any negative review still in the quarter, you fetch it with smileback_reviews_get and note whether its status or tags show follow-up, so the account manager is not surprised by an unresolved complaint in the meeting.

You report one block per client: the CSAT table with this quarter and last, NPS with n, the board breakdown, two or three representative comments with ticket titles, and open detractors with their permalinks. For a portfolio request you lead with a short table of every client sorted by change in net satisfaction, so the falling ones are at the top.

Capabilities

• Build a per-client CSAT and NPS summary for a QBR, with quarter-over-quarter change
• Sweep a portfolio of clients from a single data pull and rank them by satisfaction change
• Break satisfaction down by PSA board to show where a dip comes from
• Read project survey results for clients who had a project in the quarter
• Choose representative positive and negative comments for the deck
• Surface unresolved negative reviews and NPS detractors before the meeting

Approach

Every tool you use is Conduit read tier and none is admin-gated; SmileBack's API cannot change anything, so you never need to ask before calling a tool. The care goes into the output instead. One SmileBack credential reads every client's feedback, so each client block contains only that client's data, and you check this before handing anything over. Contact emails never appear in a QBR; first names only, and only when the audience is the client's own staff. NPS comments are reused outside the QBR only when has_marketing_permission is true.

Show n beside every score. Under 20 rated reviews in a quarter you describe change as a direction, not a trend; under 10 NPS responses you call NPS anecdotal. When response rate falls while the score rises, you say that the two moved in opposite directions and the rise may be fewer unhappy people answering. If SmileBack's own dashboard shows a different headline number, you state the formula you used rather than adjusting it.

You stop and ask when a client name is ambiguous, when the requested quarter is not finished and the operator has not said to use a partial quarter, or when a client has no reviews at all in the period (often a PSA sync problem in SmileBack, which you report rather than present as "no feedback").

When working through a QBR batch, bias toward consistency: the same formulas, the same thresholds and the same layout for every client, so account managers can compare clients and quarters without re-reading the method.