Sentiments
REST API v1

Sentiments API Documentation

Build powerful integrations with our RESTful API. Manage advocates, automate rewards, track referrals, and sync customer data.

Get API KeyView Endpoints

Quick Start

1. Get Your API Key

Generate an API key from your dashboard settings. Keep it secure - it grants access to your business data.

Go to API Settings

2. Authenticate Requests

Include your API key in the Authorization header of every request using Bearer token authentication.

Authorization: Bearer sk_live_...

3. Make Your First Request

Start with a simple GET request to list your advocates. All responses are JSON formatted.

GET /api/v1/advocates

Base URL

All API requests should be made to:

https://sentiments.com/api/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

Use Bearer token authentication with your API key:

# Example request
curl https://sentiments.com/api/v1/advocates \
-H "Authorization: Bearer sk_live_abc123..."

API Endpoints

Advocates

Manage your advocate community

MethodEndpointDescriptionResponses
GET/api/v1/advocates
Params: page, limit, search, tier
List all advocates with pagination200: { advocates: [], total, page }
GET/api/v1/advocates/:idGet a single advocate by ID200: { advocate } | 404: Not found
POST/api/v1/advocates
Body: { email, name, metadata }
Create a new advocate201: { advocate } | 400: Validation error
PATCH/api/v1/advocates/:id
Body: { name, tier, metadata }
Update an advocate200: { advocate } | 404: Not found
POST/api/v1/advocates/:id/points
Body: { amount, description, type }
Award or deduct points200: { transaction, newBalance }

Rewards

Manage rewards and redemptions

MethodEndpointDescriptionResponses
GET/api/v1/rewards
Params: status, type
List all rewards200: { rewards: [] }
GET/api/v1/rewards/:idGet reward details200: { reward } | 404: Not found
POST/api/v1/rewards
Body: { name, description, pointsCost, type, stock }
Create a new reward201: { reward } | 400: Validation error
POST/api/v1/rewards/:id/redeem
Body: { advocateId }
Redeem a reward for an advocate200: { redemption } | 400: Insufficient points

Quests

Manage campaigns and tasks

MethodEndpointDescriptionResponses
GET/api/v1/quests
Params: status
List all quests200: { quests: [] }
GET/api/v1/quests/:idGet quest with tasks200: { quest, tasks: [] } | 404: Not found
POST/api/v1/quests
Body: { title, description, tasks, reward }
Create a new quest201: { quest } | 400: Validation error
POST/api/v1/quests/:id/complete
Body: { advocateId, taskId }
Mark a task as complete for an advocate200: { completion, pointsAwarded }

Referrals

Track referral clicks and conversions

MethodEndpointDescriptionResponses
GET/api/v1/referralsList all referral codes200: { referrals: [] }
GET/api/v1/referrals/:code/statsGet referral statistics200: { clicks, conversions, revenue }
POST/api/v1/referrals/track
Body: { code, visitorId }
Track a referral click200: { tracked: true }
POST/api/v1/referrals/convert
Body: { code, orderId, orderValue }
Track a conversion200: { conversion, pointsAwarded }

Testimonials

Collect and manage testimonials

MethodEndpointDescriptionResponses
GET/api/v1/testimonials
Params: status, rating
List all testimonials200: { testimonials: [], total }
PATCH/api/v1/testimonials/:id
Body: { status }
Approve or reject a testimonial200: { testimonial } | 404: Not found

Feedback

Manage feedback boards and ideas

MethodEndpointDescriptionResponses
GET/api/v1/feedback/boardsList feedback boards200: { boards: [] }
GET/api/v1/feedback/boards/:id/ideas
Params: status, sort
List ideas in a board200: { ideas: [], total }
PATCH/api/v1/feedback/ideas/:id
Body: { status }
Update idea status200: { idea } | 404: Not found

SSO & Customer Mapping

Single sign-on for seamless widget personalization

MethodEndpointDescriptionResponses
POST/api/v1/sso/recognize
Body: { businessId, externalCustomerId, timestamp, signature }
Recognize a customer via SSO token200: { advocateId, sessionToken }
GET/api/v1/sso/mappingsList customer mappings200: { mappings: [] }
POST/api/v1/sso/mappings
Body: { advocateId, externalCustomerId, externalEmail, externalName }
Create a customer mapping201: { mapping } | 400: Validation error

Rate Limiting

Default Limits

PlanRequests/minRequests/day
Starter301,000
Growth6010,000
Professional120100,000

Rate Limit Headers

Every response includes headers to help you track usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1704067200

Error Handling

The API uses conventional HTTP response codes. Errors include a JSON body with details.

HTTP Status Codes

200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Rate Limited
500Server Error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "field": "email"
  }
}

Webhooks

Receive real-time HTTP notifications when events happen in your account. Get notified about new reviews, advocates joining, reward redemptions, quest completions, survey responses, and more. Webhooks support retry logic and signature verification for secure integrations.

View Webhook DocumentationConfigure Webhooks

SDKs & Libraries

JS

JavaScript

npm install @sentiments/sdk

Official SDK for Node.js and browser environments.

Coming Soon
PY

Python

pip install sentiments

Official SDK for Python applications.

Coming Soon
PHP

PHP

composer require sentiments/sdk

Official SDK for PHP applications.

Coming Soon

Need Help?

Our team is here to help you build your integration.

Contact SupportGetting Started Guide