Skip to Content
Introduction

ThinkVoice Public API

Welcome to the ThinkVoice Public API.

The ThinkVoice Public API lets external systems securely query call records in ThinkVoice, download call recordings, manage voice agent calls, and send text channel conversations to ThinkVoice.

How It Works

Using the API comes down to two basic steps:

  1. Get a Bearer token with your username and password
  2. Call the relevant endpoint with that token

Available endpoints:

  • Call Records — Query analyzed call records
  • Call Detail — Retrieve all information about a single call
  • Call Recording — Download the audio recording of a call
  • Start Voice Agent Call — Start a new call through a voice agent
  • Call Logs — List the voice agent call history
  • Call Ingestion — Forward a call from your PBX, together with its recording, to ThinkVoice for analysis
  • Text Channels — Forward a conversation from a text channel such as live chat, together with its messages, to ThinkVoice for analysis

ThinkVoice can also notify your system: when a call analysis completes, it automatically sends a notification to the URL you configure. See the Webhook section for details.

The tenant is not selected via a header. Only the data of the tenant the user belongs to is visible.

Key Facts

PropertyDetail
Base URLhttps://public-api.thinkvoice.ai
Auth MethodBearer Token
Token LifetimeAccess token 2 hours (7200 seconds), refresh token 7 days
Rate LimitGeneral: 40 requests / 60 seconds · Token: 5 requests / 60 seconds · Call Ingestion and Text Channels: 600 requests / 60 seconds
Data SourceElasticsearch (per-tenant indices)

Security

  • Only users granted Public API access can obtain a token
  • An optional IP restriction can be applied
  • Sensitive data in call titles and summaries is returned as [MASKED] — phone numbers, email addresses and Turkish national ID numbers (TCKN) are masked
  • The customer phone number is returned only in the customerPhoneNumber field; it never appears as plain text in text fields

Before You Start the Integration

Before starting the integration, you need to share the following information with our team:

#InformationDescription
1Environmentproduction
2User credentialsEmail and password of the user who will call the API (Public API access is granted to the user by our team)
3Outbound IP addressesIf IP restriction will be enabled, as static IPs or in CIDR format
4Call type filtersFull names of any types to be used other than the defaults
5Date/time conventionWhether UTC or local time will be used
6Expected traffic volumeRate limits can be reviewed for high volumes
7Call ingestion (PBX integration)If you will send calls from your PBX, you will receive X-Api-Key and X-Api-Secret values

Practical Tips

  • Run your first tests with cURL
  • Get a token first, then test the endpoints one by one with the same token
  • The token is valid for 2 hours; renew it with refresh_token instead of logging in on every request (the token endpoint is limited to 5 requests per minute)
  • If you need deep pagination, keep the skip + take ≤ 10,000 limit in mind (for /public-calls/get-calls)
  • You can get the latest state of a call by querying the callId received via webhook with /public-calls/call
  • You can track calls started with voice-agent/start-call through voice-agent/call-log
  • Do not treat feedback summary texts as raw data — sensitive fields are masked
Last updated: