How to Use the Testimonial Boost API
Testimonial Boost is becoming more than a dashboard for collecting and distributing customer proof.
With API access, developers, automation tools, and AI agents can securely interact with Testimonial Boost programmatically — while keeping access scoped, auditable, and tenant-safe.
This guide walks through how to create an API credential and make your first authenticated request.
What You Can Do With the API
The first version of the Testimonial Boost API supports a focused set of campaign workflows.
You can:
- List campaigns
- Retrieve a campaign
- Create a campaign
- Create an AI campaign variant
- Retrieve campaign performance data
Higher-risk actions such as automated publishing and scheduling are not currently exposed through the external API.
This is intentional. We are introducing machine access gradually so that authorization, auditability, and safety remain first-class concerns.
Step 1: Create an API Credential
From your Testimonial Boost dashboard, open:
Settings → API Access
Enter a name for the credential, such as:
Marketing Automation
or:
AI Agent
Then choose the permissions the credential needs.
Available scopes currently include:
campaigns:read— view campaignscampaigns:write— create campaignsdistribution:generate— generate AI campaign variantsanalytics:read— read campaign performance data
Choose only the permissions the integration actually needs.
This follows the principle of least privilege: an automation that only needs campaign reporting should not receive permission to create campaigns.
Step 2: Choose an Expiration
API credentials currently support limited lifetimes such as:
- 7 days
- 30 days
- 90 days
Credentials do not live forever.
This reduces the risk of an old credential remaining active indefinitely.
When a credential expires, create a new one.
Step 3: Copy Your Credential
After creating the credential, Testimonial Boost displays the secret once.
It looks similar to:
tb_api_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxx
Copy it immediately and store it securely.
For security reasons, Testimonial Boost stores only a cryptographic hash of the credential. The original secret cannot be displayed again.
Never:
- place an API credential in client-side JavaScript
- commit it to GitHub
- put it in a public repository
- share it in screenshots
- expose it in browser URLs
Store it in a secure environment variable or secrets manager.
For example:
export TB_API_TOKEN='your-api-credential'
Step 4: Make Your First Request
The external API is available under:
/api/v1
To list your campaigns:
curl \
-H "Authorization: Bearer $TB_API_TOKEN" \
https://app.testimonialboost.com/api/v1/campaigns
A successful response returns campaign data similar to:
{
"data": [
{
"id": "campaign_id",
"name": "LinkedIn Proof Post",
"status": "draft",
"sourceType": "testimonial",
"provider": null,
"createdAt": "2026-11-14T08:45:51.389Z",
"updatedAt": "2026-11-14T08:45:51.389Z"
}
]
}
Step 5: Create a Campaign
Creating resources requires an Idempotency-Key.
An idempotency key identifies one logical operation and protects your integration from creating duplicates if a network request is retried.
Example:
curl \
-X POST \
-H "Authorization: Bearer $TB_API_TOKEN" \
-H "Idempotency-Key: campaign-create-001" \
-H "Content-Type: application/json" \
https://app.testimonialboost.com/api/v1/campaigns \
-d '{
"...": "valid campaign input"
}'
If your integration retries the exact same request using the same idempotency key, Testimonial Boost returns the same logical result instead of creating a duplicate campaign.
A new intentional operation should use a new key.
Why Idempotency Matters for AI Agents
Traditional users click buttons once.
Agents and automation systems behave differently.
They may:
- retry after a timeout
- repeat a workflow after a network failure
- execute several steps automatically
- resume a partially completed task
Without idempotency, a retry could accidentally create two campaigns or repeat another write operation.
Testimonial Boost treats idempotency as part of the API contract for external write operations.
Create an AI Campaign Variant
A credential with both:
campaigns:writedistribution:generate
can create an AI variant of an existing campaign.
Conceptually:
curl \
-X POST \
-H "Authorization: Bearer $TB_API_TOKEN" \
-H "Idempotency-Key: variant-001" \
-H "Content-Type: application/json" \
https://app.testimonialboost.com/api/v1/campaigns/CAMPAIGN_ID/variants \
-d '{
"strategy": "new_hook"
}'
The API uses the same grounded campaign-variant system available inside Testimonial Boost.
AI generation does not bypass campaign ownership, proof eligibility, or tenant authorization.
Read Campaign Performance
A credential with:
campaigns:readanalytics:read
can retrieve campaign performance.
curl \
-H "Authorization: Bearer $TB_API_TOKEN" \
https://app.testimonialboost.com/api/v1/campaigns/CAMPAIGN_ID/performance
Performance endpoints return trusted first-party metrics.
They do not automatically trigger an AI model simply because the data is requested.
That distinction is important to our architecture:
deterministic data first, AI interpretation second.
API Permissions Are Scoped
Every credential has explicit scopes.
For example, a reporting integration might only receive:
campaigns:read
analytics:read
If that credential attempts to create a campaign, the API rejects the request.
This prevents integrations from gaining more power than they were intentionally given.
Credentials Are Bound to Your Account or Organization
API credentials are not floating master keys.
Each credential is bound to the account and tenant context in which it was created.
Testimonial Boost revalidates that relationship when the credential is used.
If the user’s organization relationship changes, an old organization credential does not silently gain access to a different tenant.
Credentials Can Be Revoked
From Settings → API Access, you can revoke a credential at any time.
Once revoked, requests using that credential immediately stop authenticating.
Revoked credentials cannot be restored.
Create a new credential instead.
Built for Automation and AI Agents
The API foundation is being designed around both traditional integrations and emerging agent workflows.
That means our API architecture emphasizes:
- scoped permissions
- structured errors
- idempotent writes
- rate limiting
- tenant isolation
- audit trails
- explicit side effects
- reusable domain services
These same principles will eventually allow AI agents to interact with Testimonial Boost through standards such as the Model Context Protocol without requiring a separate security model.
What Comes Next
The current API focuses on safe campaign creation, generation, and analytics.
Future capabilities may include additional agent and automation workflows while keeping higher-risk operations independently permissioned.
Our goal is not simply to make Testimonial Boost accessible through an API.
The goal is to make customer-proof workflows safely programmable — by developers, automations, and eventually intelligent agents.



