This page explains how to use our API to generate AI Talking Points for an existing report.
All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.
Generate AI Talking Points
Method: GET
Endpoint: https://api.insites.com/api/v1/report-talking-points/[ReportID]
Returns AI-generated talking points for an existing report. If talking points have already been generated for the same report and goal, the cached result will be returned unless generate-new=true is supplied.
The request can include the following query parameters:
Property | Definition | Required |
id | String – The report hash to generate talking points for. | Yes |
prompt | String – The business goal to guide the talking points. Supported values are website_visits, physical_visits, online_sales, more_calls and unsure. Defaults to website_visits if omitted. | No |
industry | String – Override the report’s detected industry. If omitted, Insites will use the report’s saved industry where available, or attempt to detect it automatically. | No |
generate-new | Boolean – If true, bypasses the cache and generates a fresh set of talking points. | No |
Example
curl "https://api.insites.com/api/v1/report-talking-points/855e8785e2c214f3fc5e13371b2bd28332c11c83?prompt=website_visits"\
--header "api-key:[YOUR API KEY]"
Expected response
If successful, you would expect a 200 response, with a body like this:
{
"request_status": "success",
"creditsRemaining": 5,
"talkingPoints": [
{
"category": "SEO & Online Visibility",
"testId": "Test_Site_LocalPack",
"testTitle": "Local pack",
"type": "bad",
"title": "Enhance Local SEO",
"description": "List your business in local pack on
Google My Business to enhance visibility in local search results."
},
{
"category": "SEO & Online Visibility",
"testId": "Test_Site_IncomingLinks",
"testTitle": "Backlinks",
"type": "bad",
"title": "Increase Backlink Profile",
"description": "Focus on acquiring high-quality backlinks to
improve domain authority and overall search ranking."
}],
"config": {
"prompt": "more_calls",
"industry": ""},
"status": "success"
}
All possible responses
Code | Reason |
200 | Talking points returned. |
400 | Missing required parameters. |
401 | Missing or invalid API key, or API access is not enabled for the account. |
402 | The account doesn’t have enough feature credits to generate talking points. |
404 | Report not found. |
405 | Method not allowed. |
422 | The request could not be processed (e.g. invalid prompt value). |
Prompt values
The request supports the following prompt values:
Value | Definition |
website_visits | Generate talking points focused on increasing website visits. |
physical_visits | Generate talking points focused on increasing in-person visits. |
online_sales | Generate talking points focused on increasing online sales. |
more_calls | Generate talking points focused on increasing phone enquiries. |
unsure | Generate general-purpose talking points when the business goal is not known. |
Talking point object
Each talking point in the response includes the following fields:
Property | Definition |
category | The category the recommendation belongs to. |
testId | The related test ID. |
testTitle | The related test title. |
type | The talking point type. |
title | The title of the recommendation. |
description | The recommendation details. |
Caching
By default, previously generated talking points may be returned from cache. To force a fresh set of talking points, include generate-new=true
Example
curl
"https://api.insites.com/api/v1/report-talking-points/855e8785e2c214f3fc5e13371b2bd28332c11c83?prompt=website_visits&generate-new=true"\
--header "api-key:[YOUR API KEY]"
Errors
Errors are returned as JSON.
Example error
{
"status": "error",
"request_status": "error",
"errorMessage": "The parameter 'prompt' must be one of:
website_visits, physical_visits, online_sales, more_calls, unsure",
"error_message": "The parameter 'prompt' must be one of:
website_visits, physical_visits, online_sales, more_calls, unsure"
}