REST API | Senja Help

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.

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": "[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

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": "[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 `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