REST API

Senja's REST API lets you list, create, and work with testimonials in your project. Use it when you want to build your own integration or automate a workflow that Senja does not support natively.

This is applicable to any Senja plans (Free, Starter, and Pro).

Getting started

Senja's API uses REST, JSON responses, and standard HTTP methods.

Base URL

https://api.senja.io/v1

Authentication

Find your API key in Integrations page: https://app.senja.io/settings/integrate?tab=api

To authenticate your requests, pass the newly created key as the Authorization header

curl "https://api.senja.io/v1/testimonials" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Replace this with your API Key>"

If your API key is exposed, rotate it right away. This is useful if you accidentally show it during a live stream, screen share, or in a public code sample.

Go to Automate, press Regenerate API Key, then update every app or script that uses the old one. The old key will stop working in a few minutes.

Only users with the Admin or Owner role can regenerate an API key.

Rotating API keys

If your API key is exposed, rotate it right away. This is useful if you accidentally show it during a live stream, screen share, or in a public code sample.

Go to Integrations page: https://app.senja.io/settings/integrate?tab=api
Click the rotate icon to regenerate your new API key
Update every app or script that uses the old one
The old key will stop working in a few minutes

Only users with the Admin or Owner role can regenerate an API key.

Endpoints

GET /testimonials returns testimonials from your Senja project
POST /testimonials creates a testimonial
GET /testimonials/[id] returns one testimonial by ID
PATCH /testimonials/[id] updates a testimonial's approval status or tags
DELETE /testimonials/[id] permanently deletes a testimonial
GET /links returns your links, including their IDs
POST /invites sends testimonial invites to a list of people

List testimonials in your Senja project

Use GET /testimonials to return testimonials from your project
You can filter by tags, type, rating, and integration
Use query for full-text search across testimonial text, title, customer name, customer email, and customer tagline
By default, results are sorted by date in descending order
You can also sort by rating and change the order to asc or desc

Example request

curl "https://api.senja.io/v1/testimonials" \
  -H "Authorization: Bearer API_KEY"

Query parameters

Parameter	Possible options	Default	Description
`sort`	`date` `rating`	`date`	Sort by date or rating
`order`	`asc` `desc`	`desc`	Return oldest or newest results first
`approved`	`true` `false`	`null`	Return approved or unapproved testimonials
`rating`	`int`	`null`	Return testimonials with a specific rating
`type`	`text` `video`	`null`	Return text or video testimonials
`integration`	Integration	`null`	Return testimonials from one integration
`tags`	`string[]`	`[]`	Return testimonials that match any of the given tag names
`query`	`string`	`null`	Full-text search across testimonial text, title, customer name, customer email, and customer tagline
`lang`	ISO 639 language code	`null`	Return testimonials in a language or with a translation in that language
`limit`	`1` to `1000`	`100`	Limit the number of testimonials returned
`page`	`int`	`null`	Paginate through results

In the GET /testimonials response, total is the number of results returned on the current page, not a global count. To fetch everything, keep paginating until total is lower than your limit.

Working with dates?

Some providers do not return exact review dates
For the recommended approach, see Handling review dates and the API

Example: find 2-star reviews

curl "https://api.senja.io/v1/testimonials?rating=2" \
  -H "Authorization: Bearer API_KEY"

Response fields

reward is the reward string
translations is an array of translation objects, each with a lang field
created_at is the creation timestamp
video_url is the highest quality MP4 URL for video testimonials
video contains video metadata, including duration, aspect_ratio, mp4_urls, hls_url, and transcript as a string
links contains URLs for the testimonial, including senja for the dashboard URL and public for the shareable URL

{
  "total": 1,
  "testimonials": [
    {
      "id": "a1b2c3d4-...",
      "type": "text",
      "integration": "google",
      "title": "Great product",
      "text": "Senja makes it so easy to collect and share testimonials.",
      "rating": 5,
      "media": [],
      "url": "https://google.com/maps/reviews/...",
      "date": "2026-04-01T12:00:00.000Z",
      "approved": true,
      "project_id": "b2c3d4e5-...",
      "form_id": null,
      "thumbnail_url": null,
      "customer_name": "Jane Smith",
      "customer_email": "[email protected]",
      "customer_avatar": "https://ik.imagekit.io/senja/...",
      "customer_company": "Acme Inc",
      "customer_company_logo": null,
      "customer_tagline": "Head of Marketing",
      "customer_url": "https://example.com",
      "reward": null,
      "translations": [],
      "created_at": "2026-04-01T12:00:00.000Z",
      "tags": ["featured"],
      "video_url": null,
      "video": null,
      "links": {
        "senja": "https://app.senja.io/?project=b2c3d4e5-...&testimonial=a1b2c3d4-...",
        "public": "https://senja.io/p/acme/t/a1b2c3d4-..."
      }
    }
  ]
}

Update a testimonial

Use PATCH /testimonials/[id] to update a testimonial's approval status or tags
At least one of approved, add_tags, or remove_tags is required
Only these fields can be changed with the API. To edit text, rating, or customer details, use the Senja dashboard

JSON body parameters

Parameter	Type	Required	Description
`approved`	boolean	No	Set approval status. `true` publishes the testimonial and `false` sets it back to pending
`add_tags`	`string[]`	No	Tag names to add. Tags are created automatically if they do not already exist
`remove_tags`	`string[]`	No	Tag names to remove

Example request

curl -X PATCH "https://api.senja.io/v1/testimonials/[id]" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "add_tags": ["featured"],
    "remove_tags": ["needs-review"]
  }'

The API returns the updated testimonial.

Delete a testimonial

Use DELETE /testimonials/[id] to permanently delete a testimonial
This action is irreversible

Example request

curl -X DELETE "https://api.senja.io/v1/testimonials/[id]" \
  -H "Authorization: Bearer API_KEY"

Example response

{
  "message": "Testimonial deleted"
}

Create a testimonial

Use POST /testimonials to create a testimonial in your project
The response returns a confirmation message and the new testimonial ID

Example request

curl -X POST "https://api.senja.io/v1/testimonials" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "customer_name": "Jane Doe",
    "customer_email": "[email protected]",
    "customer_company": "Acme Corp",
    "customer_tagline": "Head of Product",
    "title": "Absolute game-changer",
    "text": "This is a fake testimonial for demo purposes. The product saved us 10 hours a week and made our team mass unboxers.",
    "rating": 5,
    "approved": false,
    "tags": ["demo", "fake"]
  }'

Example response

{
  "message": "Testimonial created",
  "id": "a1b2c3d4-..."
}

JSON body parameters

Parameter	Type	Required	Description
`type`	string	Yes	`text` or `video`
`title`	string	No	Testimonial title
`text`	string	No	Testimonial text
`rating`	number	No	Rating value, usually 1 to 5
`url`	string	No	Source URL for the testimonial
`date`	string	No	ISO 8601 date
`approved`	boolean	No	Approval status
`thumbnail_url`	string	No	Thumbnail image URL
`form_id`	string	No	Form ID linked to the testimonial
`customer_name`	string	Yes	Customer name
`customer_email`	string	No	Customer email address
`customer_avatar`	string	No	Customer avatar URL
`customer_company_logo`	string	No	Customer company logo URL
`customer_company`	string	No	Customer company name
`customer_tagline`	string	No	Customer tagline
`customer_username`	string	No	Customer username
`customer_url`	string	No	Customer website or profile URL
`integration`	Integration	No	Source integration value
`tags`	`string[]`	No	Tag names
`video_url`	string	No	Video URL for video testimonials
`media[]`	array	No	Attached media items
`media[].alt`	string	No	Alt text for the media
`media[].url`	string	No	Media URL
`media[].type`	`image` `video`	No	Media type

Get links from the API

Use GET /links when you need the shareable URL for one of your Senja links, such as a widget URL you want to display somewhere else
The response also includes each link's id, so you can use it as a programmatic reference when needed
The response is grouped by link type
If you need a testimonial ID for a shareable testimonial URL, use GET /testimonials or GET /testimonials/[id]

Example request

curl "https://api.senja.io/v1/links" \
  -H "Authorization: Bearer API_KEY"

Example response

{
  "case_studies": [
    {
      "id": "a1b2c3d4-...",
      "name": "...",
      "url": "https://senja.io/p/.../case-studies/a1b2c3d4-..."
    }
  ],
  "forms": [
    {
      "id": "b2c3d4e5-...",
      "name": "...",
      "url": "https://senja.io/p/.../r/..."
    }
  ],
  "quick_links": [
    {
      "id": "c3d4e5f6-...",
      "name": "...",
      "url": "https://senja.io/p/.../s/..."
    }
  ],
  "sizzle_reels": [
    {
      "id": "d4e5f6a7-...",
      "name": "...",
      "url": "https://senja.io/p/.../mv/d4e5f6a7-..."
    }
  ],
  "walls_of_love": [
    {
      "id": "e5f6a7b8-...",
      "name": "...",
      "url": "https://senja.io/p/.../..."
    }
  ],
  "widgets": [
    {
      "id": "f6a7b8c9-...",
      "name": "...",
      "type": "...",
      "url": "https://widget.senja.io/widget/f6a7b8c9-..."
    }
  ]
}

Send form invite emails to your customers

Sends invite emails for one of your forms
The email content and follow-up sequence come from that form's email sequence settings in your dashboard
Use GET /links to get the form_id

Example request

curl -X POST https://api.senja.io/v1/invites \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "a1b2c3d4-...",
    "recipients": [
      { "email": "[email protected]", "name": "Olly Meakings" },
      { "email": "[email protected]" }
    ]
  }'

name is optional. form_id comes from GET /links -> forms[].id

Example response

{
  "sent": 1,
  "skipped": [
    {
      "email": "[email protected]",
      "reason": "already_invited"
    }
  ]
}

Shareable testimonial URL

You can build a direct URL for a testimonial with your project permalink and the testimonial ID
https://senja.io/p/[permalink]/t/[testimonial_id]

Replace [permalink] with your project permalink and [testimonial_id] with the testimonial ID you want to share
To retrieve testimonial IDs, use GET /testimonials

Supported integrations

enum Integration {
  TWITTER = 'twitter',
  PRODUCT_HUNT = 'product_hunt',
  GOOGLE = 'google',
  FACEBOOK = 'facebook',
  REDDIT = 'reddit',
  CAPTERRA = 'capterra',
  G2 = 'g2',
  LINKEDIN = 'linkedin',
  APP_STORE = 'app_store',
  TRUSTPILOT = 'trustpilot',
  SHOPIFY = 'shopify',
  PLAY_STORE = 'play_store',
  YELP = 'yelp',
  SLACK = 'slack',
  DISCORD = 'discord',
  APPLE_PODCASTS = 'apple_podcasts',
  TELEGRAM = 'telegram',
  WHATSAPP = 'whatsapp',
  INSTAGRAM = 'instagram',
  YOUTUBE = 'youtube',
  TIKTOK = 'tiktok',
  APPSUMO = 'appsumo',
  AMAZON = 'amazon',
  ZILLOW = 'zillow',
  UDEMY = 'udemy',
  CHROME_WEB_STORE = 'chrome_web_store',
  AIRBNB = 'airbnb',
  SKILLSHARE = 'skillshare',
  REALTOR = 'realtor',
  SOURCEFORGE = 'sourceforge',
  WHOP = 'whop',
  WORDPRESS = 'wordpress',
  FIVERR = 'fiverr',
  HOMESTARS = 'homestars',
  WEB_PAGE = 'web_page',
}

Was this helpful?