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:
- Call
smileback_reviews_list with modified_since set to the start
of the window and page to the end.
- 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.
1---2name: smileback-api-patterns3description: >4 The SmileBack tool surface as exposed through Conduit: the 12 read-only5 tools over the Data Replication API v3, the five-header credential (OAuth26 password grant run by the server), the US/EU region, Conduit access tiers7 (all read, none admin-gated), limit/offset pagination, response truncation,8 client-side filtering because the API has no per-company or date-range9 filter, the error vocabulary, and the personal data the responses carry.10when_to_use: >-11 When calling any SmileBack tool, paging through reviews or NPS responses,12 or diagnosing a SmileBack connection failure. Use when: smileback api,13 smileback mcp, smileback auth, smileback credentials, smileback 401,14 invalid_grant, invalid_client, smileback pagination, smileback region, or15 "can Claude write to SmileBack".16metadata:17 source: https://skillmd.com/skills/wyre-ai/smileback-api-patterns18---1920# SmileBack API Patterns2122## Overview2324SmileBack collects customer feedback for MSPs: a one-click CSAT reaction25on each closed PSA ticket, NPS campaigns, and project surveys. The26Conduit connector reads that data through SmileBack's Data Replication27API v3. The API itself is read-only (OAuth scopes `read` and28`read_recent`), so every tool is a GET. Nothing can create, change or29delete data in SmileBack. Follow-up actions happen in the PSA.3031## Connection3233Claude Code reaches SmileBack through Conduit's unified endpoint34(`https://conduit.wyre.ai/v1/mcp`, via `wyre-gateway`). Conduit stores five35values when you connect SmileBack in the Conduit web UI36(`/connect/smileback`) and maps them to these headers on every call.37Nothing is set on the client, and Conduit drops any `X-SmileBack-*` header38a client sends:3940| Conduit field | Header | Required |41|---|---|---|42| Client ID | `X-SmileBack-Client-Id` | Yes |43| Client Secret | `X-SmileBack-Client-Secret` | Yes |44| Username (email) | `X-SmileBack-Username` | Yes |45| Password | `X-SmileBack-Password` | Yes |46| Region | `X-SmileBack-Region` | No (`us` or `eu`, default `us`) |4748- **Client ID and Client Secret** come from the SmileBack Account menu >49 API Credentials (one pair per account).50- **Username and password** are the email and native SmileBack password51 of the user Conduit signs in as. Native credentials work even when52 ConnectWise SSO is on. They also sign in to the SmileBack web app, so53 use a dedicated user for API access.54- **Region**: `us` is `app.smileback.io`. Pick `eu` only if the account55 lives on `app.smileback.eu`. There is no base-URL field; the server56 only ever calls one of those two hosts.5758The server runs the OAuth2 password grant itself, caches the access59token, and on a 401 fetches one fresh token and retries once. Refresh60tokens are not used.6162## Conduit Access Tiers6364All 12 tools are classified **read** in Conduit. None is admin-gated and65none is a write, so any Conduit role that can read the SmileBack66connector sees the whole surface. Two consequences the tier does not67show:6869- One credential set reads the MSP's entire SmileBack dataset across70 every client. SmileBack has no per-client scoping.71- Reviews, NPS responses, contacts and project responses contain end72 customers' personal data: names, emails, titles, locations, free-text73 comments and marketing-permission flags. Share output only with people74 allowed to see it, and strip emails from anything client-facing.7576Conduit does not cache SmileBack results, so every call reaches77SmileBack.7879## Tool Surface8081| Tool | Endpoint | Parameters | Paged |82|---|---|---|---|83| `smileback_reviews_list` | `GET /reviews/` | `modified_since`, `include_unrated`, `limit`, `offset` | Yes |84| `smileback_reviews_list_recent` | `GET /reviews/recent/` | `limit`, `offset` | Yes |85| `smileback_reviews_get` | `GET /reviews/{review_id}/` | `review_id` (required) | No |86| `smileback_nps_responses_list` | `GET /nps-responses/` | `created_since`, `campaign_name`, `score_gt`, `score_lt`, `score_exact`, `limit`, `offset` | Yes |87| `smileback_nps_responses_get` | `GET /nps-responses/{response_id}/` | `response_id` (required) | No |88| `smileback_nps_campaigns_list` | `GET /nps-campaigns/` | none | No |89| `smileback_csat_companies_list` | `GET /csat-companies/` | none | No |90| `smileback_csat_contacts_list` | `GET /csat-contacts/` | none | No |91| `smileback_csat_agents_list` | `GET /csat-agents/` | none | No |92| `smileback_csat_boards_list` | `GET /csat-boards/` | none | No |93| `smileback_project_surveys_list` | `GET /prj-surveys/` | none | No |94| `smileback_project_responses_list` | `GET /prj-responses/` | `created_since` | No |9596What the records hold:9798- **Review** (CSAT): `rating`, `comment`, `ticket` (`id`, `title`,99 `segment` = the PSA board, `agents`, `closed_on`), `contact`,100 `company` (`id`, `name`, `territory`, `market`), `status`, `tags`,101 `rated_on`, `permalink`, `last_modified`.102- **NPS response**: `score` (0-10), `comment`,103 `has_marketing_permission`, `contact` (name, email, company, title,104 location), `contact_remote_id`, `campaign_name`, `created_at`.105- **CSAT company**: the MSP's end clients, with territory, market and106 PSA remote IDs.107- **CSAT agent**: the MSP's active technicians. **CSAT board**: PSA108 service boards (a review's `ticket.segment`).109110SmileBack's CSAT reaction is a three-point scale (positive, neutral,111negative). Read the `rating` values on the first page you fetch before112computing anything, rather than assuming how they are encoded.113114## Filtering Happens Client-Side115116The API has no per-company filter, no aggregate endpoint and no date117upper bound. To get a client's CSAT for a quarter:1181191. Call `smileback_reviews_list` with `modified_since` set to the start120 of the window and page to the end.1212. Keep reviews whose `company.id` matches and whose `rated_on` falls122 inside the window.123124`modified_since` filters on `last_modified`, not `rated_on`. A review125rated last year but edited this week comes back, so the `rated_on` filter126in step 2 is required. Every review rated inside the window has127`last_modified` at or after `rated_on`, so nothing is missed. When you128also need a response rate (`include_unrated: true`), place rated and129unrated reviews by `ticket.closed_on` instead, as `smileback-csat-qbr-summary`130does, so both come from the same cohort.131132NPS responses are grouped by `contact.company`, which is a name, not the133CSAT company ID. Match names carefully and report any responses whose134company you could not match.135136Dates are ISO 8601 dates or date-times (`2026-10-01` or137`2026-10-01T00:00:00Z`). NPS score filters are integers 0-10;138detractors are `score_lt: 7`.139140## Pagination141142`smileback_reviews_list`, `smileback_reviews_list_recent` and143`smileback_nps_responses_list` use `limit`/`offset` and return144`{count, next, previous, results}` as SmileBack sent it.145146- `limit` defaults to 50 and is capped at 100.147- The server never pages for you. Keep calling with a larger `offset`148 until `next` is null, and compare the rows you collected with `count`149 before calling a set complete.150- The other lists are not paginated. `smileback_project_responses_list`151 returns everything since `created_since`, so always pass it.152153## Truncated Responses154155Output is capped at about 60,000 characters. When a page is larger,156items are dropped from the end of `results` and the response adds157`truncated: true`, `returned_items`, `total_items_in_page` and a158`truncation_hint`. `count`, `next` and `previous` are kept unchanged.159160On a truncated page, the next offset is the current `offset` plus161`returned_items`. The `next` URL assumes the whole page arrived, so162following it skips the dropped rows. Lower `limit` (25 works well for163reviews with long comments) and continue. If even the first item is too164large, `results` is empty and `first_item_truncated` holds the start of165it; fetch that record on its own with `smileback_reviews_get` or166`smileback_nps_responses_get`.167168## Errors169170Vendor errors come back as tool errors with the HTTP status, the OAuth171error code from the token endpoint, and SmileBack's message.172173| Error | Meaning | Fix |174|---|---|---|175| `invalid_client` | Client ID or Client Secret wrong, or the wrong region | Copy both again from Account > API Credentials; confirm `us` or `eu` |176| `invalid_grant` | Username or password wrong, or the wrong region | Use the user's email and native SmileBack password; confirm the region |177| HTTP 401 with no SmileBack status | A required field is missing from the Conduit connection | Reconnect SmileBack in Conduit with all four required fields |178| 404 | Unknown review or response ID | Re-list; IDs are integers |179| Argument error | Bad date, score outside 0-10, empty campaign name | Fixed client-side; never reached SmileBack |180181## Rate Limits182183SmileBack publishes no rate limit but asks integrators to keep bandwidth184low. The server retries only a 401. On a 429 or a 5xx, wait before185retrying and do not loop. Use `modified_since` and `created_since` to186read only what changed rather than re-pulling full history, and pull a187quarter once, then compute every client from that one pull.188189## Related Skills190191- `smileback-csat-qbr-summary` builds a per-client CSAT/NPS review.192- `smileback-detractor-follow-up` triages negative reviews and NPS193 detractors.194- `smileback-technician-csat` reports CSAT by technician and board.