Welcome to the Senja REST API documentation 👋
The Senja REST API is available on the Starter plan and above. You can see the available plans on our pricing page.
With Senja’s API, you can easily build custom workflows for testimonial collection and sharing, or integrate Senja with tools that we currently do not have 1st party integrations for.
Getting started
Senja’s API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Endpoint
https://api.senja.io/v1Authentication
You can find your API in the Integrations tab of your project settings.
To authenticate your requests, you need to pass the newly created key as an Authorization header:
curl "https://api.senja.io/v1/testimonials" \
-H "Content-Type: application/json" \
-H "Authorization: <Replace this with your API Key>" \Endpoints
GET /testimonials: Retrieves all the testimonials in your Senja project.POST /testimonials: Creates a new testimonial.GET /testimonials/[id]: Retrieves a specific testimonial from your Senja project.
List all testimonials in your Senja project
Endpoint: GET /testimonials
This endpoint returns a list of all the testimonials in your Senja project. You can also filter the testimonials by tags, type, rating and integration.
By default, it returns the most recent testimonials first (date), but you can sort by rating (rating). You can also change the direction of the sort (asc/desc)
Example Request
curl "https://api.senja.io/v1/testimonials"
-H "Authorization: Bearer API_KEY"Query Parameters
Parameter | Possible options | Default | Description |
sort |
|
| Sort by date or rating. |
order |
|
| Order in ascending order (oldest testimonials first/lowest rated first) or descending order (newest testimonials first/lowest rated first). |
approved |
| NULL | List approved testimonials or unapproved testimonials. If left empty, both are retrieved. |
rating |
| NULL | List testimonials matching a rating |
type |
| NULL | List text or video testimonials |
integration | Integration | NULL | List testimonials matching a specific integration. If left empty all are retrieved. See supported integrations |
tags | string[] | [] | List testimonials matching specific tags. Use the names of the tags, not their ids. |
lang | ISO 639 language code | NULL | Find testimonials that are written in a specified language or have been translated to a specific language |
limit |
| 100 | Limit testimonials returned by the API |
page |
| NULL | Use this to paginate between responses |
Example Response
Example: Find 1 and 2-star reviews
You can use the rating parameter to find reviews with a specific star rating. The API lets you filter for one rating at a time. For example, you can retrieve all 2-star reviews.
curl "https://api.senja.io/v1/testimonials?rating=2"
-H "Authorization: Bearer API_KEY"{
"testimonials": [
{
"id": "5f6dca95-b19b-4de6-a104-885462a7e5e9",
"type": "text",
"integration": null,
"title": null,
"text": "I was so surprised how easily Senja could do what I hoped it to be able to that <mark>I subscribed within the first hour</mark> and I'm gonna port it to my other company during the day 😅",
"rating": 5,
"media": [],
"url": null,
"date": "2023-03-07T00:00:00.000Z",
"approved": true,
"project_id": "13c8e79b-dc26-4f12-aebd-908c01d440ca",
"thumbnail_url": null,
"form_id": "fe097815-9f08-4268-898d-789a0e1af571",
"customer_name": "Georg R.",
"customer_email": "[email protected]",
"customer_avatar": "https://senjaio.b-cdn.net/public/avatar/05765ede-0522-43ce-bc35-205096cc5ebc_2A3520FF-FD48-442D-BF66-554C809E1912-8377-000003EA11D0E6A3.jpg",
"customer_tagline": "Founder of StatusLink",
"customer_username": null,
"customer_url": "https://statuslink.io",
"customer_company_logo": null,
"customer_company": null,
"created_at": "2023-03-07T07:22:48.67+00:00",
"tags": [],
"lang": "en",
"translations": [
{
"id": "417bdd2e-fbba-4633-a3a4-e0aca1d0cc7d",
"customer_tagline": "Responsable marketing, Hubhouse",
"created_at": "2024-03-14T17:50:06.187+00:00",
"lang": "fr",
"review_id": "513fe6ca-fed4-4e1b-a161-325ec2191d80",
"text": "Je travaille ici depuis plus de 15 ans, d'abord dans un rôle junior. L'entreprise m'a toujours poussé à acquérir de nouvelles compétences et à relever de nouveaux défis. Mes collègues sont intelligents et travailleurs, mais aussi agréables à travailler. Je recommande de postuler.",
"title": "",
"updated_at": "2024-03-14T17:50:09.341311+00:00",
}
],
},
{
"id": "4757564f-7ea7-4e31-bfd3-06249f828f84",
"type": "video",
"integration": null,
"title": null,
"text": "",
"rating": 5,
"media": [],
"url": null,
"date": "2023-01-14T20:04:08.503Z",
"approved": true,
"project_id": "13c8e79b-dc26-4f12-aebd-908c01d440ca",
"thumbnail_url": null,
"form_id": "96392896-6f2c-43da-866d-95c7c33efd67",
"customer_name": "Zack Swire",
"customer_email": "[email protected]",
"customer_avatar": "https://senjaio.b-cdn.net/public/avatar/d1880ba0-b0ea-44f1-9e13-392113f3c62e_Untitled%20design%20%2845%29.png",
"customer_tagline": "Coach & Founder",
"customer_username": null,
"customer_url": "https://www.topcoachclub.com"
"customer_company_logo": null,
"customer_company": null,
"created_at": "2023-01-14T20:04:08.503+00:00",
"tags": [],
"video_url": "https://stream.mux.com/u2aVhj3KA2IjPpLg9hK00CKPFMd9kfXZVFU7mrAw2YiU/low.mp4",
"video": {
"duration": 89.709333,
"aspect_ratio": "16:9",
"mp4_urls": {
"high": "https://stream.mux.com/u2aVhj3KA2IjPpLg9hK00CKPFMd9kfXZVFU7mrAw2YiU/high.mp4",
"medium": "https://stream.mux.com/u2aVhj3KA2IjPpLg9hK00CKPFMd9kfXZVFU7mrAw2YiU/medium.mp4",
"low": "https://stream.mux.com/u2aVhj3KA2IjPpLg9hK00CKPFMd9kfXZVFU7mrAw2YiU/low.mp4"
},
"hls_url": "https://stream.mux.com/u2aVhj3KA2IjPpLg9hK00CKPFMd9kfXZVFU7mrAw2YiU.m3u8"
},
"lang": "en",
"translations": []
},
{
"id": "5d0be321-89d6-4eb6-b20a-7d869642e6a3",
"type": "text",
"integration": "twitter",
"title": null,
"text": "I've been using Senja for a few months and I genuinely don't think there's any testimonial tool that even comes close to how good it is.\n\nSenja to the mooon 🚀",
"rating": 0,
"media": [],
"url": "https://twitter.com/Jobsager/status/1634956105897086976",
"date": "2023-03-12T00:00:00.000Z",
"approved": true,
"project_id": "13c8e79b-dc26-4f12-aebd-908c01d440ca",
"thumbnail_url": null,
"form_id": null,
"customer_name": "Moi",
"customer_email": null,
"customer_avatar": "https://senjaio.b-cdn.net/public/media/5iSPwfACEB3xtigdUheRzGXt.jpeg",
"customer_tagline": "Hi 👋",
"customer_username": "Jobsager",
"customer_url": "https://twitter.com/Jobsager"
"created_at": "2023-03-12T16:37:16.16+00:00",
"tags": [],
"lang": "en",
"translations": []
}
]
}Add a testimonial to your Senja Project
Endpoint: POST /testimonials
This endpoint allows you to add a new testimonial to your Senja project. You must provide the required information in the form of a JSON payload in the request body.
Example Request
curl -X POST "https://api.senja.io/v1/testimonials"
-H "Authorization: Bearer API_KEY"
-H "Content-Type: application/json"
-d '{
"type": "text",
"title": "Amazing product!",
"text": "This product has changed my life!",
"rating": 5,
"endorser": {
"name": "John Doe",
"email": "[email protected]"
}
}'JSON Body Parameters
Parameter | Type | Required | Description |
type | string | Yes | The type of testimonial. Possible values: "text" or "video". |
title | string | No | The title of the testimonial. |
text | string | No | The text content of the testimonial. |
rating | number | No | The rating of the testimonial (e.g., 1-5). |
url | string | No | The URL of the testimonial. |
date | string | No | The date of the testimonial (ISO 8601 format). |
approved | boolean | No | The approval status of the testimonial. If |
thumbnail_url | string | No | The URL of the testimonial's thumbnail image. |
form_id | string | No | The ID of the form associated with the testimonial. |
customer_name | string | Yes | The name of the customer. |
customer_email | string | No | The email address of the customer. |
customer_avatar | string | No | The URL of the customer’s avatar. |
customer_company_logo | string | No | The URL of the customer’s company logo. |
customer_company | string | No | The customer’s company. |
customer_tagline | string | No | The customer’s tagline. |
customer_username | string | No | The customer’s username. |
customer_url | string | No | The URL of the customer’s website or social media profile. |
integration | Integration | No | The integration associated with the testimonial. See all supported values |
tags | string[] | No | An array of strings representing tags associated with the testimonial. |
video_url | string | No | The URL of the video testimonial. This field is required if the testimonial type is "video". |
media[] | { url: string; type: "image"; alt?: string; }[] | A list of images associated with the testimonial. | |
media[].alt | string | No | The alternative text for the media. |
media[].url | string | No | The URL of the media. |
media[].type |
| No | The type of media. |
Supported integrations
enum Integration {
TWITTER = 'twitter',
LINKEDIN = 'linkedin',
GOOGLE = 'google',
FACEBOOK = 'facebook',
AIRBNB = 'airbnb',
AMAZON = 'amazon',
APP_STORE = 'app_store',
APPLE_PODCASTS = 'apple_podcasts',
APPSUMO = 'appsumo',
CAPTERRA = 'capterra',
CHROME_WEB_STORE = 'chrome-web-store',
EMBEDSOCIAL = 'embedsocial',
FIVERR = 'fiverr',
G2 = 'g2',
HOMESTARS = 'homestars',
INSTAGRAM = 'instagram',
PLAY_STORE = 'play-store',
PRODUCT_HUNT = 'product-hunt',
REALTOR = 'realtor',
REDDIT = 'reddit',
SKILLSHARE = 'skillshare',
SOURCEFORGE = 'sourceforge',
TESTIMONIAL_TO = 'testimonial-to',
TIKTOK = 'tiktok',
TRUSTPILOT = 'trustpilot',
UDEMY = 'udemy',
UPWORK = 'upwork',
WHOP = 'whop',
WORDPRESS = 'wordpress',
YELP = 'yelp',
YOUTUBE = 'youtube',
ZILLOW = 'zillow',
}