Quickstart

Get up and running with the IdentityCall API in 5 minutes. This guide will walk you through uploading your first recording and retrieving the transcription.

Prerequisites

Before you begin, you’ll need:

An IdentityCall account (Sign up here )
An API key (Create one in the dashboard )
An audio file to analyze (MP3, WAV, M4A, or other supported format)

Step 1: Set Up Your API Key

First, set your API key as an environment variable:

macOS/Linux


export IDENTITYCALL_API_KEY="idc_your_api_key_here"

Windows


set IDENTITYCALL_API_KEY=idc_your_api_key_here

Windows PowerShell


$env:IDENTITYCALL_API_KEY = "idc_your_api_key_here"

Step 2: Upload a Recording

Upload your audio file to start the transcription process:

cURL


curl -X POST "https://api.identitycall.com/api/v1/public/recordings" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -F "file=@your-recording.mp3" \
  -F "language=en" \
  -F "name=My First Recording"

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
BASE_URL = "https://api.identitycall.com/api/v1/public"
 
with open("your-recording.mp3", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/recordings",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"language": "en", "name": "My First Recording"}
    )
 
recording = response.json()
print(f"Recording ID: {recording['data']['id']}")
print(f"Status: {recording['data']['status']}")

Node.js


const fs = require('fs');
const FormData = require('form-data');
 
const API_KEY = process.env.IDENTITYCALL_API_KEY;
const BASE_URL = 'https://api.identitycall.com/api/v1/public';
 
const formData = new FormData();
formData.append('file', fs.createReadStream('your-recording.mp3'));
formData.append('language', 'en');
formData.append('name', 'My First Recording');
 
const response = await fetch(`${BASE_URL}/recordings`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: formData
});
 
const recording = await response.json();
console.log(`Recording ID: ${recording.data.id}`);
console.log(`Status: ${recording.data.status}`);

PHP


<?php
$apiKey = getenv('IDENTITYCALL_API_KEY');
$baseUrl = 'https://api.identitycall.com/api/v1/public';
 
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/recordings",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('your-recording.mp3'),
        'language' => 'en',
        'name' => 'My First Recording'
    ]
]);
 
$response = curl_exec($ch);
$recording = json_decode($response, true);
 
echo "Recording ID: " . $recording['data']['id'] . "\n";
echo "Status: " . $recording['data']['status'] . "\n";

Ruby


require 'net/http'
require 'net/http/post/multipart'
require 'json'
 
API_KEY = ENV['IDENTITYCALL_API_KEY']
BASE_URL = 'https://api.identitycall.com/api/v1/public'
 
uri = URI("#{BASE_URL}/recordings")
File.open('your-recording.mp3') do |file|
  request = Net::HTTP::Post::Multipart.new(
    uri.path,
    'file' => UploadIO.new(file, 'audio/mpeg', 'your-recording.mp3'),
    'language' => 'en',
    'name' => 'My First Recording'
  )
  request['Authorization'] = "Bearer #{API_KEY}"
 
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
 
  recording = JSON.parse(response.body)
  puts "Recording ID: #{recording['data']['id']}"
  puts "Status: #{recording['data']['status']}"
end

Response:


{
  "data": {
    "id": 123,
    "status": "pending",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Transcription is asynchronous. The recording status will be pending immediately after upload, then change to processing, and finally completed when ready.

Step 3: Check Recording Status

Wait for the transcription to complete (usually 1-2 minutes for a 5-minute recording):

cURL


curl -X GET "https://api.identitycall.com/api/v1/public/recordings/123" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


import time
 
recording_id = 123
 
while True:
    response = requests.get(
        f"{BASE_URL}/recordings/{recording_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    status = response.json()['data']['status']
    print(f"Status: {status}")
 
    if status == 'completed':
        break
    elif status == 'failed':
        print("Transcription failed")
        break
 
    time.sleep(5)  # Wait 5 seconds before checking again

Node.js


const recordingId = 123;
 
async function checkStatus() {
  const response = await fetch(
    `${BASE_URL}/recordings/${recordingId}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );
  return response.json();
}
 
// Poll until complete
let status = 'pending';
while (status !== 'completed' && status !== 'failed') {
  const recording = await checkStatus();
  status = recording.data.status;
  console.log(`Status: ${status}`);
 
  if (status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
  }
}

PHP


$recordingId = 123;
 
do {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => "$baseUrl/recordings/$recordingId",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"]
    ]);
    $response = curl_exec($ch);
    $recording = json_decode($response, true);
    $status = $recording['data']['status'];
 
    echo "Status: $status\n";
 
    if ($status !== 'completed' && $status !== 'failed') {
        sleep(5);
    }
} while ($status !== 'completed' && $status !== 'failed');

Ruby


recording_id = 123
 
loop do
  uri = URI("#{BASE_URL}/recordings/#{recording_id}")
  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Bearer #{API_KEY}"
 
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
 
  recording = JSON.parse(response.body)
  status = recording['data']['status']
  puts "Status: #{status}"
 
  break if status == 'completed' || status == 'failed'
  sleep 5
end

Step 4: Get the Transcription

Once the status is completed, retrieve the full transcription:

cURL


curl -X GET "https://api.identitycall.com/api/v1/public/recordings/123/transcription" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


response = requests.get(
    f"{BASE_URL}/recordings/{recording_id}/transcription",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
transcription = response.json()
 
print(f"Full transcript:\n{transcription['data']['full_text']}\n")
 
for dialogue in transcription['data']['dialogues']:
    print(f"[{dialogue['speaker']}]: {dialogue['text']}")

Node.js


const response = await fetch(
  `${BASE_URL}/recordings/${recordingId}/transcription`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const transcription = await response.json();
 
console.log(`Full transcript:\n${transcription.data.full_text}\n`);
 
for (const dialogue of transcription.data.dialogues) {
  console.log(`[${dialogue.speaker}]: ${dialogue.text}`);
}

PHP


$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/recordings/$recordingId/transcription",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $apiKey"]
]);
$response = curl_exec($ch);
$transcription = json_decode($response, true);
 
echo "Full transcript:\n" . $transcription['data']['full_text'] . "\n\n";
 
foreach ($transcription['data']['dialogues'] as $dialogue) {
    echo "[{$dialogue['speaker']}]: {$dialogue['text']}\n";
}

Ruby


uri = URI("#{BASE_URL}/recordings/#{recording_id}/transcription")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{API_KEY}"
 
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end
 
transcription = JSON.parse(response.body)
 
puts "Full transcript:\n#{transcription['data']['full_text']}\n\n"
 
transcription['data']['dialogues'].each do |dialogue|
  puts "[#{dialogue['speaker']}]: #{dialogue['text']}"
end

Response:


{
  "data": {
    "recording_id": 123,
    "language": "en",
    "full_text": "Hello, thank you for calling IdentityCall support...",
    "dialogues": [
      {
        "id": 456,
        "position": 1,
        "speaker": "Speaker 1",
        "text": "Hello, thank you for calling IdentityCall support. How can I help you today?",
        "start_ms": 0,
        "end_ms": 4500,
        "emotion": {
          "happy": 0.7,
          "neutral": 0.2,
          "calm": 0.1,
          "sad": 0.0,
          "angry": 0.0,
          "fearful": 0.0,
          "surprised": 0.0,
          "disgust": 0.0
        }
      },
      {
        "id": 457,
        "position": 2,
        "speaker": "Speaker 2",
        "text": "Hi, I'm having trouble logging into my account.",
        "start_ms": 5000,
        "end_ms": 8200,
        "emotion": {
          "happy": 0.0,
          "neutral": 0.6,
          "calm": 0.1,
          "sad": 0.2,
          "angry": 0.1,
          "fearful": 0.0,
          "surprised": 0.0,
          "disgust": 0.0
        }
      }
    ]
  }
}

Step 5: Get Analysis Results

Retrieve goal achievements, keyword detections, and pause analysis:

cURL


curl -X GET "https://api.identitycall.com/api/v1/public/recordings/123/results" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


response = requests.get(
    f"{BASE_URL}/recordings/{recording_id}/results",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
results = response.json()
 
print("Goals:")
for goal in results['data']['goals']:
    status = "✓" if goal['met'] else "✗"
    print(f"  {status} {goal['goal_name']} (score: {goal['score']})")
 
print("\nKeywords detected:")
for keyword in results['data']['keywords']:
    print(f"  - {keyword['keyword_name']}: {keyword['count']} times")

Node.js


const results = await fetch(
  `${BASE_URL}/recordings/${recordingId}/results`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
).then(r => r.json());
 
console.log("Goals:");
for (const goal of results.data.goals) {
  const status = goal.met ? "✓" : "✗";
  console.log(`  ${status} ${goal.goal_name} (score: ${goal.score})`);
}
 
console.log("\nKeywords detected:");
for (const keyword of results.data.keywords) {
  console.log(`  - ${keyword.keyword_name}: ${keyword.count} times`);
}

Next Steps

Now that you’ve uploaded your first recording, explore these topics:

Learn about API key permissions and security

Authentication

Explore all available endpoints

API Reference

Understanding the transcription pipeline

Transcription Workflow

Deep dive into goal and keyword analysis

Analyzing Results