REST API - Team Connect API Documentation

🚀 API Overview

The Team Connect REST API provides unified access to enterprise communication services through a single endpoint. Send voice calls, SMS messages, emails, and AI chat requests with consistent request/response formats.

🎯 Why Choose Our API:

✅ Single endpoint for all communication services
✅ Real-time billing with transparent pricing
✅ 99.9% uptime with enterprise infrastructure
✅ No monthly fees - pay only for what you use
✅ GDPR compliant with UK-based servers

🔐 Authentication

All API requests require a valid API key. You can create and manage API keys in your dashboard.

API Key Types

Live Keys: tc_live_... - Real services, charges credits
Test Keys: tc_test_... - Sandbox mode, no charges

# Include your API key in the request body
curl -X POST https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI \
  -H "Content-Type: application/json" \
  -d '{
    "service": "voice",
    "action": "make_call",
    "data": {
      "to": "+447123456789",
      "message": "Hello from Team Connect!"
    },
    "api_key": "tc_live_your_api_key_here"
  }'

🔒 Security Best Practices:

Never expose API keys in client-side code
Use environment variables to store keys
Regenerate keys if compromised
Use test keys for development

🌐 Base Endpoint

All API requests are made to a single unified endpoint:

POST

https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI

Unified endpoint for all services (Voice, SMS, Email, AI)

Request Format

All requests use JSON and require these parameters:

{
  "service": "voice|sms|email|ai",
  "action": "make_call|send|chat",
  "data": {
    // Service-specific parameters
  },
  "api_key": "tc_live_your_api_key_here"
}

Response Format

All responses follow a consistent structure:

✅ Success Response

{
  "success": true,
  "result": {
    // Service-specific result data
  },
  "billing": {
    "cost": 7,
    "costFormatted": "7p",
    "service": "voice",
    "action": "make_call",
    "isLive": true,
    "creditsRemaining": 2493,
    "creditsRemainingFormatted": "£24.93"
  },
  "timestamp": "2025-08-05T15:05:58.000Z",
  "nodeVersion": "20"
}

❌ Error Response

{
  "success": false,
  "error": "Insufficient credits. You have 50p but need 70p. Please top up your account.",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. You have 50p but need 70p. Please top up your account.",
  "topUpUrl": "https://team-connect.co.uk/api-dashboard.html#topup",
  "timestamp": "2025-08-05T15:05:58.000Z",
  "service": "voice",
  "action": "make_call"
}

📞 Voice Calls

Make AI-powered voice calls to any phone number worldwide.

POST

/executeAPI

Make an AI voice call

Request Parameters

{
  "service": "voice",
  "action": "make_call",
  "data": {
    "to": "+447123456789",           // Required: Phone number (E.164 format)
    "message": "Hello, this is...",  // Required: AI instructions/script
    "from": "+441234567890",         // Optional: Your phone number
    "voice": "Polly.Amy",           // Optional: Voice ID (default: Polly.Amy)
    "webhook_url": "https://..."     // Optional: Webhook for call events
  },
  "api_key": "tc_live_your_api_key_here"
}

Response

{
  "success": true,
  "result": {
    "call_id": "CA1234567890abcdef",
    "status": "initiated",
    "to": "+447123456789",
    "from": "+441234567890",
    "estimated_duration": 120
  },
  "billing": {
    "cost": 14,
    "costFormatted": "14p",
    "service": "voice",
    "action": "make_call",
    "creditsRemaining": 2486
  }
}

Available Voices

Voice ID	Language	Gender	Accent
`Polly.Amy`	English (UK)	Female	British
`Polly.Brian`	English (UK)	Male	British
`Polly.Emma`	English (UK)	Female	British
`Polly.Joanna`	English (US)	Female	American
`Polly.Matthew`	English (US)	Male	American

cURL Example

curl -X POST https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI \
  -H "Content-Type: application/json" \
  -d '{
    "service": "voice",
    "action": "make_call",
    "data": {
      "to": "+447123456789",
      "message": "Hi, this is Sarah from Dad-Link calling to confirm your appointment tomorrow at 2 PM. Can you please confirm if this time still works for you?",
      "voice": "Polly.Amy"
    },
    "api_key": "tc_live_your_api_key_here"
  }'

💬 SMS Messages

Send SMS messages to any mobile number worldwide.

POST

/executeAPI

Send an SMS message

Request Parameters

{
  "service": "sms",
  "action": "send",
  "data": {
    "to": "+447123456789",           // Required: Mobile number
    "message": "Your code is 123456", // Required: SMS content (160 chars = 1 SMS)
    "from": "+441234567890"          // Optional: Your SMS number
  },
  "api_key": "tc_live_your_api_key_here"
}

Response

{
  "success": true,
  "result": {
    "message_id": "SM1234567890abcdef",
    "status": "sent",
    "to": "+447123456789",
    "from": "+441234567890"
  },
  "billing": {
    "cost": 3,
    "costFormatted": "3p",
    "service": "sms",
    "action": "send",
    "creditsRemaining": 2497
  }
}

cURL Example

curl -X POST https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI \
  -H "Content-Type: application/json" \
  -d '{
    "service": "sms",
    "action": "send",
    "data": {
      "to": "+447123456789",
      "message": "Your verification code is 123456. Valid for 5 minutes."
    },
    "api_key": "tc_live_your_api_key_here"
  }'

📧 Email Sending

Send HTML emails with high deliverability through SendGrid.

POST

/executeAPI

Send an HTML email

Request Parameters

{
  "service": "email",
  "action": "send",
  "data": {
    "to": "customer@example.com",    // Required: Recipient email
    "subject": "Welcome!",           // Required: Email subject
    "html": "Welcome!...",  // Required: HTML content
    "from_name": "Dad-Link Team"     // Optional: Sender name
  },
  "api_key": "tc_live_your_api_key_here"
}

Response

{
  "success": true,
  "result": {
    "message_id": "x-message-id-12345",
    "status": "sent",
    "to": "customer@example.com",
    "subject": "Welcome!"
  },
  "billing": {
    "cost": 0.15,
    "costFormatted": "0.15p",
    "service": "email",
    "action": "send",
    "creditsRemaining": 2499.85
  }
}

HTML Email Example

curl -X POST https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI \
  -H "Content-Type: application/json" \
  -d '{
    "service": "email",
    "action": "send",
    "data": {
      "to": "customer@example.com",
      "subject": "Welcome to Dad-Link!",
      "html": "Welcome!
Thanks for signing up
Your account is now active and ready to use.",
      "from_name": "Dad-Link Team"
    },
    "api_key": "tc_live_your_api_key_here"
  }'

🤖 AI Chat

Use GPT-4 for intelligent conversations and content generation.

POST

/executeAPI

Chat with AI (GPT-4)

Request Parameters

{
  "service": "ai",
  "action": "chat",
  "data": {
    "messages": [                    // Required: Array of message objects
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "model": "gpt-4"                // Optional: AI model (default: gpt-4)
  },
  "api_key": "tc_live_your_api_key_here"
}

Response

{
  "success": true,
  "result": {
    "response": "Hello! I'm doing well, thank you for asking. How can I help you today?",
    "model": "gpt-4",
    "tokens_used": 45
  },
  "billing": {
    "cost": 15,
    "costFormatted": "15p",
    "service": "ai",
    "action": "chat",
    "creditsRemaining": 2485
  }
}

Available Models

gpt-4 - Most capable, best for complex tasks
gpt-3.5-turbo - Faster, good for simple tasks

cURL Example

curl -X POST https://us-central1-customerservice-2156c.cloudfunctions.net/executeAPI \
  -H "Content-Type: application/json" \
  -d '{
    "service": "ai",
    "action": "chat",
    "data": {
      "messages": [
        {
          "role": "system",
          "content": "You are a customer service assistant for Dad-Link."
        },
        {
          "role": "user",
          "content": "How do I integrate voice calls into my app?"
        }
      ],
      "model": "gpt-4"
    },
    "api_key": "tc_live_your_api_key_here"
  }'

⚠️ Error Handling

The API uses standard HTTP status codes and provides detailed error information.

200 - Success

Request completed successfully

401 - Unauthorized

Invalid or missing API key

402 - Payment Required

Insufficient credits

403 - Forbidden

Service unavailable for account

429 - Too Many Requests

Rate limit exceeded

500 - Internal Error

Server error, try again

Error Response Format

{
  "success": false,
  "error": "Insufficient credits. You have 50p but need 70p. Please top up your account.",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits. You have 50p but need 70p. Please top up your account.",
  "topUpUrl": "https://team-connect.co.uk/api-dashboard.html#topup",
  "timestamp": "2025-08-05T15:05:58.000Z",
  "service": "voice",
  "action": "make_call"
}

Error Codes

MISSING_API_KEY - API key not provided
INVALID_API_KEY - API key invalid or revoked
INSUFFICIENT_CREDITS - Not enough credits in account
SERVICE_UNAVAILABLE - Service not available for account
INTERNAL_ERROR - Server error occurred

⏱️ Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Service	Rate Limit	Window	Burst Limit
Voice Calls	10 requests/min	1 minute	5 concurrent
SMS Messages	100 requests/min	1 minute	50 concurrent
Email Sending	200 requests/min	1 minute	100 concurrent
AI Chat	30 requests/min	1 minute	10 concurrent

💡 Rate Limit Best Practices:

Implement exponential backoff for 429 responses
Cache responses where appropriate
Use background queues for bulk operations
Monitor rate limit headers in responses

🔗 Webhooks

Receive real-time notifications about call status, SMS delivery, and other events.

Webhook Events

call.completed - Voice call finished
call.failed - Voice call failed
sms.delivered - SMS delivered successfully
sms.failed - SMS delivery failed
email.delivered - Email delivered
email.bounced - Email bounced

Webhook Payload Example

{
  "event": "call.completed",
  "timestamp": "2025-08-05T15:05:58.000Z",
  "data": {
    "call_id": "CA1234567890abcdef",
    "to": "+447123456789",
    "from": "+441234567890",
    "status": "completed",
    "duration": 145,
    "cost": 17,
    "user_id": "user_abc123",
    "api_key": "tc_live_abc123..."
  }
}

Webhook Verification

Verify webhook authenticity using HMAC-SHA256 signatures:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

💰 Pricing

Simple, transparent pricing with no monthly fees. Pay only for what you use.

Service	Price	Unit	API Call
📞 Voice Calls	7p	per minute	`{"service": "voice", "action": "make_call"}`
💬 SMS Messages	3p	per message	`{"service": "sms", "action": "send"}`
📧 Email Sending	0.15p	per email	`{"service": "email", "action": "send"}`
🤖 AI Processing	15p	per request	`{"service": "ai", "action": "chat"}`

💡 Example Monthly Costs

Startup with 1,000 customers:

500 voice calls (2 min avg) = £70.00
2,000 SMS messages = £60.00
10,000 emails = £15.00
200 AI requests = £30.00
Total: £175.00/month (vs £thousands for building in-house)

Credit Management

Minimum top-up: £5.00 (500 credits)
Maximum top-up: £1,000.00 (100,000 credits)
Credits never expire
Real-time balance tracking
Low credit alerts available

💳 Manage Credits: Visit your API Dashboard to top up credits and view usage.

⚡ REST API

🚀 API Overview

🔐 Authentication

API Key Types

🌐 Base Endpoint

Request Format

Response Format

✅ Success Response

❌ Error Response

📞 Voice Calls

Request Parameters

Response

Available Voices

cURL Example

💬 SMS Messages

Request Parameters

Response

cURL Example

📧 Email Sending

Request Parameters

Welcome!

Response

HTML Email Example

Welcome!

Thanks for signing up

🤖 AI Chat

Request Parameters

Response

Available Models

cURL Example

⚠️ Error Handling

Error Response Format

Error Codes

⏱️ Rate Limits

🔗 Webhooks

Webhook Events

Webhook Payload Example

Webhook Verification

💰 Pricing

💡 Example Monthly Costs

Credit Management