Skip to main content

​
Prerequisites

Before you begin, ensure you have:
You’ll need a valid API token. If you haven’t created one yet, follow the authentication guide to generate your token.
Know your workspace tenant/subdomain. This is the subdomain in your Mindhunters workspace URL (e.g., if your URL is https://abc.mindhunters.ai, your tenant is abc).
You’ll need an Agent ID to initiate calls. You can find your agents in the Mindhunters dashboard under the Agents section. The Agent ID is a UUID format identifier.

​
Make Your First API Call

Let’s initiate an AI-powered voice call using the Mindhunters API. This example will show you how to start a conversation with a phone number.

​
Step 1: Set Up Your Environment

First, set up your credentials as environment variables: 
export MIHU_API_TOKEN="your-api-token-here"
export MIHU_TENANT="your-tenant-here"
export MIHU_AGENT_ID="your-agent-id-here"

​
Step 2: Initiate Your First Call

curl -X POST https://{your-tenant}.mindhunters.ai/api/v1/call \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id-here",
    "participant": {
      "number": "+1234567890"
    }
  }'

​
Step 3: Understanding the Response

When successful, you’ll receive a response like this: 
{
  "success": true,
  "message": "Call initiated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "initiated",
    "provider": "twilio",
    "agentId": "your-agent-id-here",
    "participant": {
      "number": "+1234567890"
    },
    "createdAt": "2025-01-15T10:30:00Z"
  }
}
​
success
boolean
Indicates whether the call was initiated successfully
​
message
string
A human-readable message describing the result
​
data
object
Contains the call details

​
Advanced Call Options

You can customize your call with additional parameters: 
curl -X POST https://your-tenant.mindhunters.ai/api/v1/call \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id-here",
    "participant": {
      "number": "+1234567890",
      "name": "John Doe"
    },
    "greetingMessage": "Hello! This is an automated call from Mindhunters.",
    "metadata": {
      "campaign": "customer-survey",
      "customerId": "12345"
    }
  }'

​
Checking Call Status

After initiating a call, you can check its status using the call ID: 
curl -X GET https://your-tenant.mindhunters.ai/api/v1/calls/{call-id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

​
Handling Errors

Always implement proper error handling: 
const initiateCall = async () => {
  try {
    const response = await fetch('https://your-tenant.mindhunters.ai/api/v1/call', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.MIHU_API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        agentId: process.env.MIHU_AGENT_ID,
        participant: {
          number: '+1234567890'
        }
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Failed to initiate call:', error.message);
    throw error;
  }
};

​
Common Error Responses

Status CodeErrorSolution
400Bad RequestCheck your request body format and required fields
401UnauthorizedVerify your API token is correct
404Not FoundCheck your tenant subdomain and endpoint URL
422Validation ErrorReview the error message for invalid parameters

​
Next Steps

Congratulations! You’ve made your first API call. Here’s what to explore next:

Set Up Webhooks

Receive real-time updates about your calls

Explore API Reference

Discover all available endpoints and features

Monitor API Usage

Track your API requests and responses

Error Handling

Learn about error codes and troubleshooting

​
Complete Example

Here’s a complete working example that initiates a call and monitors its status: 
require('dotenv').config();

const MIHU_CONFIG = {
  tenant: process.env.MIHU_TENANT,
  token: process.env.MIHU_API_TOKEN,
  agentId: process.env.MIHU_AGENT_ID
};

const initiateAndMonitorCall = async (phoneNumber) => {
  const baseUrl = `https://${MIHU_CONFIG.tenant}.mindhunters.ai/api/v1`;
  const headers = {
    'Authorization': `Bearer ${MIHU_CONFIG.token}`,
    'Content-Type': 'application/json'
  };

  try {
    // Step 1: Initiate the call
    console.log('Initiating call to', phoneNumber);
    const callResponse = await fetch(`${baseUrl}/call`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        agentId: MIHU_CONFIG.agentId,
        participant: { number: phoneNumber }
      })
    });

    if (!callResponse.ok) {
      throw new Error(`Failed to initiate call: ${callResponse.statusText}`);
    }

    const callData = await callResponse.json();
    console.log('Call initiated:', callData.data.id);

    // Step 2: Monitor call status
    const callId = callData.data.id;
    const statusResponse = await fetch(`${baseUrl}/calls/${callId}`, {
      headers
    });

    const statusData = await statusResponse.json();
    console.log('Call status:', statusData.data.status);

    return statusData;
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
};

// Run the example
initiateAndMonitorCall('+1234567890');