How to Use Your Workspace API Key

Your workspace API key gives you programmatic access to your testimonials — read them, approve them, create them from external sources, or sync them with your own product. This is the integration point for developers who want to go beyond the built-in embed widgets.

Generating Your API Key

Step 1: Open your workspace admin panel

Log in to SocialProof.Reviews and navigate to your workspace. Click the Settings or Integrations tab in the left sidebar.

Step 2: Generate the key

Click Generate API Key. Your full key will be shown once — copy it immediately and store it in a secure location such as a password manager or secrets vault.

After you leave the page, only the first 10 characters of the key are displayed. If you lose the key, you must regenerate it — the old key is invalidated.

Step 3: Store it securely

Never put your API key in:

Client-side JavaScript (it will be visible in the browser)
A public GitHub repository
A shared Slack channel or document

Always store it in:

Environment variables on your server (process.env.SPR_API_KEY)
A secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler)
Firebase Secret Manager for Cloud Functions

Authentication

Include your API key in every request as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

All API requests must be made over HTTPS. HTTP requests are rejected.

Base URL

https://api.socialproof.reviews/v1

All endpoints are scoped to your workspace automatically based on the API key.

Core Endpoints

List testimonials

Retrieve all testimonials in your workspace:

GET /testimonials
Authorization: Bearer YOUR_API_KEY

Optional query parameters:

Parameter	Type	Description
`approved`	boolean	Filter by approval status
`rating`	number	Filter by minimum rating (1–5)
`limit`	number	Number of results (default 20, max 100)
`offset`	number	Pagination offset

Example response:

{
  "data": [
    {
      "id": "t_abc123",
      "reviewer": {
        "name": "Sarah Chen",
        "email": "[email protected]",
        "jobTitle": "Product Manager",
        "company": "TechCorp"
      },
      "rating": 5,
      "review": "Incredible tool. We embedded the wall on our homepage and saw a 23% lift in demo requests.",
      "approved": true,
      "submittedAt": "2026-03-10T14:22:00Z",
      "photos": [],
      "videoUrl": null
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Get a single testimonial

GET /testimonials/:id
Authorization: Bearer YOUR_API_KEY

Approve a testimonial

PATCH /testimonials/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "approved": true
}

Create a testimonial

Import a testimonial from an external source (CSV import, legacy platform migration, or a completed survey):

POST /testimonials
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "reviewer": {
    "name": "Marcus Webb",
    "email": "[email protected]",
    "jobTitle": "CEO",
    "company": "Acme Corp"
  },
  "rating": 5,
  "review": "We replaced our old review widget within a day. The setup was seamless.",
  "approved": false,
  "source": "import"
}

Delete a testimonial

DELETE /testimonials/:id
Authorization: Bearer YOUR_API_KEY

Returns 204 No Content on success.

Code Examples

Node.js (fetch)

const SPR_API_KEY = process.env.SPR_API_KEY;

async function getApprovedTestimonials() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&limit=10',
    {
      headers: {
        'Authorization': `Bearer ${SPR_API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );
  const data = await res.json();
  return data.data;
}

Python (requests)

import os
import requests

api_key = os.environ['SPR_API_KEY']
headers = {'Authorization': f'Bearer {api_key}'}

response = requests.get(
    'https://api.socialproof.reviews/v1/testimonials',
    headers=headers,
    params={'approved': 'true', 'rating': 5}
)
testimonials = response.json()['data']

cURL

curl -X GET \
  "https://api.socialproof.reviews/v1/testimonials?approved=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Integration Patterns

Pull testimonials into your own website

If you need testimonials rendered in a fully custom design that doesn't match the embed widgets, fetch them from the API and render them yourself:

// Next.js server-side example
export async function getStaticProps() {
  const res = await fetch(
    'https://api.socialproof.reviews/v1/testimonials?approved=true&rating=5',
    { headers: { Authorization: `Bearer ${process.env.SPR_API_KEY}` } }
  );
  const { data } = await res.json();
  return { props: { testimonials: data }, revalidate: 3600 };
}

Auto-approve high-rating testimonials via webhook + API

Combine your webhook trigger with the API to create a fully automated approval flow:

Webhook fires when a testimonial is submitted
Your server receives the payload
If rating === 5, call PATCH /testimonials/:id with { "approved": true }
The testimonial appears on your Wall of Love instantly

Sync to your CRM

After a testimonial is submitted, use the API to pull the full record and push it to your CRM as a customer note or activity:

// Triggered by your webhook handler
async function syncToCRM(testimonialId) {
  const testimonial = await fetchTestimonial(testimonialId);
  await crm.createNote({
    contactEmail: testimonial.reviewer.email,
    note: `Left a ${testimonial.rating}-star testimonial: "${testimonial.review}"`,
    date: testimonial.submittedAt,
  });
}

Rate Limits

Plan	Requests per minute	Requests per day
Starter	30	1,000
Pro	120	10,000
Agency	300	50,000

Requests that exceed the rate limit receive a 429 Too Many Requests response. Implement exponential backoff in your integration.

Error Reference

Status	Meaning
`200`	Success
`201`	Created
`204`	Deleted
`400`	Bad request — check your request body
`401`	Invalid or missing API key
`403`	Key doesn't have permission for this action
`404`	Testimonial not found
`429`	Rate limit exceeded
`500`	Server error — try again