canonical: https://jentic.com/apis/getfivestars.xyz/getfivestars

# Getfivestars Xyz FiveStars API

Jentic publishes the only available OpenAPI specification for FiveStars API, keeping it validated and agent-ready. FiveStars exposes a small Zapier-oriented REST API for managing review campaigns and triggering review-request emails after a customer interaction. The five endpoints cover the OAuth 2.0 authorization code flow, a token validity check, listing campaigns, and submitting a review request for a contact. It is a focused, narrow integration designed for connecting external systems to a FiveStars review workflow.

## For AI agents

Trigger FiveStars review-request emails for customers and list available review campaigns over OAuth 2.0.

## Scope

Does not handle loyalty points, SMS marketing, or in-store check-ins - use for review-request email automation only.

## Capabilities

- Complete the OAuth 2.0 authorization code exchange to obtain a FiveStars access token
- Verify whether a stored FiveStars token is still valid before sending a request
- List all review campaigns configured on a FiveStars account
- Send a review-request email to a customer by name, email, and campaign ID
- Embed FiveStars review prompts into post-transaction CRM and POS workflows

## Use cases

### Post-Transaction Review Request

Send a FiveStars review request the moment a transaction completes in a POS or e-commerce system. The integration calls POST `/api/zapier/review-request` with the customer's first name, last name, email, and the campaign ID returned by GET `/api/zapier/campaigns.` Setup is a few hours once the OAuth client is registered.

Example prompt: Call POST `/api/zapier/review-request` with email=customer@example.com, firstName=Jane, lastName=Doe, and campaignId from a prior GET `/api/zapier/campaigns` response.

### OAuth Connection Health Check

Run a periodic background job that calls GET `/api/zapier/test` to confirm the stored FiveStars OAuth token still authenticates. If the call returns a 401, the system surfaces a reconnection prompt to the user before the next review request would silently fail. This avoids losing review opportunities mid-campaign.

Example prompt: Call GET `/api/zapier/test` with the stored FiveStars Bearer token and surface a reconnect prompt if the response code is 401.

### Campaign Picker for CRM Integrations

Render a dropdown of FiveStars campaigns inside a CRM so that staff can choose which review flow to use for each contact segment. The integration calls GET `/api/zapier/campaigns` once per session and caches the campaign IDs. This gives users a low-friction way to route different customer types into different review templates.

Example prompt: Call GET `/api/zapier/campaigns` and return a JSON list of campaign id and name pairs for the connected merchant.

### AI Agent Review Request Trigger

An AI agent hooked into a service business's calendar uses Jentic to fire a FiveStars review request after every completed appointment. It searches for the right operation, loads the schema, and submits the request without the developer wiring up the OAuth flow manually. Time-to-first-review-sent drops from days to under an hour.

Example prompt: Search Jentic for 'send a FiveStars review request', load the schema, and submit a request for the customer attached to the most recent completed appointment.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/oauth/authorize` | Initiate the OAuth 2.0 authorization code flow |
| POST | `/api/oauth/token` | Exchange an authorization code for an access token |
| GET | `/api/zapier/test` | Verify that an access token is still valid |
| GET | `/api/zapier/campaigns` | List configured review campaigns |
| POST | `/api/zapier/review-request` | Send a review-request email to a named customer |

## Key resources

- **Authentication** — Initiate OAuth authorization and exchange codes for access tokens
- **Campaigns** — List configured review campaigns on an account
- **Review Requests** — Send a single review request email to a named customer

## Why Jentic

- **Setup:** Wiring FiveStars by hand means running its OAuth2 authorization-code flow, exchanging the code for a token at `/api/oauth/token`, and refreshing it before the protected Zapier endpoints yourself. Through Jentic you install once, import the FiveStars API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The FiveStars endpoints act on your connected account rather than a resource named in the path, so you limit the agent to the operations it needs, such as listing campaigns or sending a review request. Because you pick the operation set, anything beyond those is not reachable unless you add it.
- **Credential handling:** Your FiveStars OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a review request' or 'list review campaigns', and Jentic returns the matching FiveStars operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Yotpo UGC API** — Broader review and user-generated-content platform with photo and video reviews
- **Loyalzoo API** — Loyalty and rewards programmes that pair with review-request automation
- **SendGrid Mail Send API** — Send the transactional confirmation that precedes a FiveStars review request

## FAQ

### Why is there no official OpenAPI spec for FiveStars API?

FiveStars does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call FiveStars API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the FiveStars API use?

The FiveStars API uses OAuth 2.0 with the authorization code grant. Agents redirect users to `/api/oauth/authorize`, then exchange the returned code for a Bearer access token at `/api/oauth/token.` Jentic stores the resulting token in its encrypted vault and injects it on each call.

### Can I send a review request to a customer with the FiveStars API?

Yes. Call POST `/api/zapier/review-request` with the customer's email, first name, last name, and the campaignId returned by GET `/api/zapier/campaigns.` The endpoint sends the review email immediately under that campaign's template.

### What are the rate limits for the FiveStars API?

FiveStars does not document a published rate limit for these Zapier endpoints. Treat the API as low-throughput and pace review requests at no more than a few per second per merchant; if you receive a 429 response, back off exponentially before retrying.

### How do I trigger a FiveStars review email through Jentic?

Search Jentic for 'send a FiveStars review request', load the schema for POST `/api/zapier/review-request`, and execute with the customer details. The OAuth token stays in your Jentic One instance and is attached at execution time.

### Can I limit what my agent is allowed to do with the FiveStars API?

Yes. Because Jentic One is self-hosted, you decide which FiveStars operations your agent may call, so you can allow it to list campaigns with GET `/api/zapier/campaigns` and send review requests with POST `/api/zapier/review-request` while leaving the OAuth token endpoints out of its reach. These endpoints act on your connected account rather than a resource named in the path, so the operation set you choose is the boundary and anything you do not add stays unreachable. Your own rules also govern which stored credential the agent uses at execution time.