API Documentation

Get all testimonials for a brand

GET/brands/:id/testimonials

Example URI

{
  "code": "OK",
  "data": [
    {
      "id": "1fe4e62f-48bc-4feb-a286-2906c5ce9833",
      "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
      "content": "This is an amazing real estate service! They helped us find our dream home.",
      "rating": 5,
      "created_at": 1791656559.69392,
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
      "updated_by": null,
      "captured_at": 1791656559.69392,
      "tags": [],
      "source": "Manual",
      "zillow_review": null,
      "google_review": null,
      "published_at": null,
      "testimonialtree_review": null,
      "type": "testimonial"
    },
    {
      "id": "d83cef5e-6b2e-4c6f-a5e5-c349fd4ee8dd",
      "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
      "content": "This is an amazing real estate service! They helped us find our dream home.",
      "rating": 5,
      "created_at": 1791656559.69392,
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
      "updated_by": null,
      "captured_at": 1791656559.69392,
      "tags": [],
      "source": "Manual",
      "zillow_review": null,
      "google_review": null,
      "published_at": null,
      "testimonialtree_review": null,
      "type": "testimonial"
    },
    {
      "id": "1538aac1-bb39-4b53-ac15-776b22b2d691",
      "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
      "content": "Great service!",
      "rating": null,
      "created_at": 1791656559.69392,
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
      "updated_by": null,
      "captured_at": 1791656559.69392,
      "tags": [],
      "source": "Manual",
      "zillow_review": null,
      "google_review": null,
      "published_at": null,
      "testimonialtree_review": null,
      "type": "testimonial"
    }
  ],
  "info": {
    "count": 3,
    "total": 3
  }
}

Get a specific testimonial

GET/brands/:id/testimonials/:testimonial

Example URI

{
  "code": "OK",
  "data": {
    "id": "1fe4e62f-48bc-4feb-a286-2906c5ce9833",
    "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
    "contact": {
      "id": "c77cb07d-9d27-4e23-b512-2a418fb27e8b",
      "display_name": "Johnny",
      "partner_name": "Jane Doe",
      "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
      "brand_id": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
      "user_id": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
      "sort_field": "Johnny",
      "last_touch": null,
      "last_touch_action": null,
      "next_touch": null,
      "touch_freq": null,
      "ios_address_book_id": null,
      "android_address_book_id": null,
      "created_at": 1791656560.147586,
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "created_for": "direct_request",
      "updated_for": "direct_request",
      "deleted_for": null,
      "title": null,
      "first_name": "John",
      "partner_first_name": "Jane",
      "middle_name": "M.",
      "last_name": "Doe",
      "partner_last_name": "Doe",
      "marketing_name": null,
      "nickname": "Johnny",
      "email": "[email protected]",
      "primary_email": "[email protected]",
      "emails": [
        "[email protected]"
      ],
      "parked": false,
      "partner_email": "[email protected]",
      "phone_number": "+989124834198",
      "primary_phone_number": "+989124834198",
      "phone_numbers": [
        "+989124834198"
      ],
      "company": "Rechat",
      "birthday": "1970-01-12T00:00:00.000Z",
      "profile_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "cover_image_url": "https://inomics.com/sites/default/files/pictures/picture-95970-1460131169.png",
      "job_title": "Contact Test Subject",
      "source_type": "ExplicitlyCreated",
      "source": null,
      "website": [
        "http://www.gholi.com"
      ],
      "tags": [
        "poo",
        "foo",
        "New"
      ],
      "address": [
        {
          "city": "Dallas",
          "full": "Street, Dallas Texas 72890",
          "name": "Street",
          "type": "stdaddr",
          "extra": "Office",
          "line1": "Street",
          "line2": "Dallas Texas 72890",
          "state": "Texas",
          "country": "US",
          "postcode": "72890"
        }
      ],
      "type": "contact"
    },
    "content": "This is an amazing real estate service! They helped us find our dream home.",
    "rating": 5,
    "created_at": 1791656559.69392,
    "updated_at": 1791656559.69392,
    "deleted_at": null,
    "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
    "updated_by": null,
    "captured_at": 1791656559.69392,
    "tags": [],
    "source": "Manual",
    "zillow_review": null,
    "google_review": null,
    "published_at": null,
    "testimonialtree_review": null,
    "type": "testimonial"
  }
}

Get testimonial settings

GET/brands/:id/testimonials/settings

Returns the testimonial capture settings for a brand, including the template instance used for the capture form.

Example URI

{
  "code": "OK",
  "data": {
    "id": "7020ccef-2a93-416a-9e7b-184b2e143910",
    "brand": "ebc024b1-b9ae-4480-98ec-b854eda28cd4",
    "template_instance": {
      "id": "9dbdd2b4-4129-427e-857c-d74d53f9a24f",
      "created_at": 1791656559.69392,
      "html": "SOME HTML",
      "file": {
        "id": "a1671b77-3f49-47fc-857c-9b29f52c9cad",
        "created_at": 1791656560.600387,
        "updated_at": 1791656560.600387,
        "deleted_at": null,
        "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
        "path": "templates/instances/940b7e70-c4d7-11f1-89da-fb554657817f.png",
        "name": "image.png",
        "public": true,
        "type": "file",
        "url": "https://test.cloudfront.net/templates/instances/940b7e70-c4d7-11f1-89da-fb554657817f.png",
        "preview_url": "https://test.cloudfront.net/templates/instances/940b7e70-c4d7-11f1-89da-fb554657817f.png",
        "mime": "image/png"
      },
      "created_by": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
      "branch": "http://mock-branch-url",
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "type": "template_instance"
    },
    "created_at": 1791656559.69392,
    "updated_at": 1791656559.69392,
    "collection_method": "Rechat",
    "user": "5d65a582-04dd-441f-8fc1-4b24ffb39fe9",
    "google_business_account": null,
    "google_business_location": null,
    "type": "testimonial_settings"
  }
}

Search Zillow reviewees

GET/zillow/reviewees/search{?q}

Searches the global Zillow reviewees catalog. Used by the web client to populate the picker UI before calling [PUT /brands/:id/testimonials/zillow]. The match is a case-insensitive substring (ILIKE '%q%') OR’d across screen_name, full_name, business_name, and email.

Query parameters:

Example URI

{
  "code": "OK",
  "data": [
    {
      "id": "d5e91494-28a1-4f42-ad85-e79e6ba7df0d",
      "reviewee_key": "test-reviewee-key-1",
      "account_id": "test-account-1",
      "screen_name": "testagent",
      "full_name": "Test Agent",
      "title": "Real Estate Agent",
      "email": "[email protected]",
      "business_name": "Test Realty",
      "profile_url": "https://www.zillow.com/profile/testagent",
      "review_request_url": "https://www.zillow.com/profile/testagent/review",
      "review_count": 0,
      "average_review_rating": null,
      "bridge_modification_timestamp": "2026-01-01T00:00:00.000Z",
      "created_at": 1791656559.69392,
      "updated_at": 1791656559.69392,
      "deleted_at": null,
      "type": "zillow_reviewee"
    }
  ],
  "info": {
    "count": 1,
    "total": 0
  }
}

Request Testimonial Tree connect link

GET/brands/:id/testimonials/testimonialtree/auth

Returns the URL of the Testimonial Tree authorization screen for the authenticated user, to be opened in a popup. The flow is OpenID Connect authorization code with PKCE (S256) — the verifier and the user/brand the connection is for are carried in a signed state, so the callback does not need a session.

Testimonial Tree’s consent screen is only shown on the first connect; after that the agent goes straight through. Requested scopes are openid profile email offline_access tt:testimonials.read — offline_access is required to receive a refresh token.

Example URI

{
  "code": "OK",
  "data": {
    "url": "https://dev-auth.testimonialtree.com/application/o/authorize/?response_type=code&client_id=test_client_id&redirect_uri=http%3A%2F%2Flocalhost%3A3079%2Ftestimonialtree%2Fauth%2Fdone&scope=openid+profile+email+offline_access+tt%3Atestimonials.read&state=eyJzaWduYXR1cmUiOiIwVDJWb0VZdnFxRkVkVjZacWdxTnlTQlJlZVVCQTZhczIyaHk3M1g0Z2ErYUh2a2srQmhiYzl2NUQxbTM5TUpvV0xCN0hGMmJIMVUrbUFJRHBMaktBaUg1cnpuSFRUTG5od3BnTUpsQ0hnT1k4Tk83T2xudlo3UEhWMTZES2NFc1lTcmpzT1RTbnBMNHNPa1ZsWms4NGhhM1RBU0o0Wms4eFU1ZFdJdFRFQ2NTK2ovVmp6aVJ3U25teEk1R3JIU2xyNDZsNGV6Z0dlTTBrQzdub08zbmdyZkx3OFM2UzdMNmxvYndza0RveXM0QVNQVkx4RHNJWXIxOTl5Q3FLeTl3QzB6by8zMXJGSUVOMWVJSDN0dGw0Mmw0TUlmWHlqTnp5bkJlZjhJRkdNdHZnZjVoMENVWDFtNHo3Lys3Q05WVFZWUWRuYk4yWmUvakFaN29YbUUwcVE9PSIsInZlcmlmaWVyIjoic3gvcDhHTlZmV3U1dnR6akN4VXVWWmwyMWQ2ZGNFN1NKM3dIRDR0WFZpQ0NlRFIvS05MY2s1b3gvQT09IiwidXNlciI6IjVkNjVhNTgyLTA0ZGQtNDQxZi04ZmMxLTRiMjRmZmIzOWZlOSIsImJyYW5kIjoiZWJjMDI0YjEtYjlhZS00NDgwLTk4ZWMtYjg1NGVkYTI4Y2Q0In0&code_challenge=HIVcjaVdQvsiOLizQFejd1UMT2rvO7hKbEXA3reaJ4U&code_challenge_method=S256",
    "type": "testimonialtree_auth_link"
  }
}

Complete Testimonial Tree connection

GET/testimonialtree/auth/done{?code,state}

Public callback of the Testimonial Tree authorization flow, registered with Testimonial Tree as https://api.rechat.com/testimonialtree/auth/done. It exchanges the code for tokens, reads the connected agent from GET /api/v1/partner/me, stores the connection on the user’s testimonial settings and sets their collection_method to TestimonialTree.

On success the response is an HTML page that posts success to the window that opened the popup, with a rechat://testimonialtree-authenticated redirect as fallback. Failures (a refused consent screen, an invalid state, a failed token exchange) return an error response instead.

Tokens are stored encrypted; access tokens last 15 minutes, refresh tokens 30 days. Connecting also pulls the agent’s existing testimonials — see Sync Testimonial Tree testimonials for what gets imported.

Example URI

{
  "trace": true,
  "http": 400,
  "message": "TestimonialTree state is invalid",
  "code": "BadRequest"
}

Testimonial capture form

GET/brands/:id/testimonials/:user/capture{?contact,s}

Public endpoint (no authentication required). Routes based on the user’s collection_method:

• Zillow — 302 redirect to the Zillow reviewee’s review_request_url.

• Google — looks up the connected location’s metadata.newReviewUri via the Business Information API (using the user’s stored credential) and 302 redirects to it.

• TestimonialTree — 302 redirect to the connected agent’s Testimonial Tree collection link, prefilled with the contact’s name, email and company.

• Rechat (default) — renders the Rechat capture form HTML (uses the stored template instance, or falls back to the brand’s TestimonialCapture template).

Optional query parameter contact (uuid) can be passed to pre-populate contact data in the Rechat form, and to prefill the Testimonial Tree collection link. Optional query parameter s (integer between 1 and 5) is passed on to Testimonial Tree as the star rating.

Example URI

SOME HTML