Help Center
How can we help? 👋
All Categories
Senja for developers
REST API

REST API

Build custom workflows for testimonial collection and sharing, or integrate Senja with tools that we currently do not have 1st party integrations for.

Last updated on May 9, 2023

Please note, access to the Senja API is part of our Pro plan. See more about plans here. Welcome to the Senja REST API documentation 👋

 

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/v1

Authentication

You can find your API in the Integrations tab of your project settings.

Notion image
 

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
date rating
date
Sort by date or rating.
order
asc desc
desc
Order in ascending order (oldest testimonials first/lowest rated first) or descending order (newest testimonials first/lowest rated first).
approved
true false
NULL
List approved testimonials or unapproved testimonials. If left empty, both are retrieved.
rating
int
NULL
List testimonials matching a rating
type
text video
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
int between 1 and 1000
100
Limit testimonials returned by the API
page
int
NULL
Use this to paginate between responses

Example Response

{
  "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": "georg@statuslink.io",
      "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": "zack@topcoachclub.com",
      "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

bashCopy code
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": "john@example.com"
    }
  }'
 

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 true, the testimonial is approved; if false, it is unapproved.
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
image video
No
The type of media.

Supported integrations

twitter product_hunt google facebook reddit appsumo capterra g2 linkedin app_store trustpilot shopify play_store yelp slack discord apple_podcasts telegram whatsapp youtube instagram apple_podcasts youtube tiktok instagram

 
Did this answer your question?
😞
😐
🤩
Contact Us