API Reference & Webhooks
REST API access for programmatic control of your AI teammates, conversations, contacts, and integrations. JWT authentication via AWS Cognito.
Overview
Teammates.ai provides a REST API for programmatic access to your AI teammates, conversations, contacts, and integrations. The API uses JWT authentication via AWS Cognito. All endpoints return JSON responses and follow REST conventions.
Authentication
All API requests require a JWT bearer token. Obtain tokens through the standard login flow. Tokens refresh automatically when using the Dashboard SDK. For direct API calls, include the token in the Authorization header. Your base URL is your organization’s Dashboard URL followed by /api/v1/.
- 1
Obtain a JWT Token
Sign in through the Dashboard login flow. The JWT token is returned upon successful authentication via AWS Cognito.
- 2
Include the Authorization Header
Add the header to every API request: Authorization: Bearer {your_jwt_token}
- 3
Handle Token Refresh
Tokens expire periodically. Use the Cognito refresh token flow to obtain a new access token without re-authenticating. The Dashboard SDK handles this automatically.
Webhooks
Teammates.ai sends and receives webhooks for real-time data sync. Inbound webhooks accept events from Freshdesk, Zendesk, Intercom (ticket events), and HubSpot (CRM events). Outbound webhooks deliver notifications to Slack and Microsoft Teams. All inbound webhooks are securely validated to prevent unauthorized access, and built-in deduplication prevents double-processing of events.
Important
Always validate inbound webhook signatures before processing. Reject any request that fails HMAC verification. Your organization-specific secret is available in Organization Settings > API.
Key API Endpoints
Below is a high-level overview of the available API categories. For full endpoint documentation including request/response schemas, contact support@teammates.ai.
| Category | Endpoints | Description |
|---|---|---|
| Agents | /api/v1/agents/ | CRUD operations on AI teammates |
| Conversations | /api/v1/chat/ | Chat sessions, message history |
| Interviews | /api/v1/interviews/ | Interview scheduling, scoring |
| Campaigns | /api/v1/campaigns/ | Sales campaign management |
| CRM | /api/v1/crm/ | CRM integration hub, sync status |
| Integrations | /api/v1/integrations/ | OAuth callbacks, connection status |
| Webhooks | /api/v1/webhooks/ | Inbound webhook handlers |
Rate Limits
API requests are rate-limited per organization to ensure platform stability. Standard rate limits apply to all plans. If you require higher throughput for high-volume integrations, contact support@teammates.ai to discuss Enterprise plan rate limit adjustments.
Frequently Asked Questions
Can I build custom integrations?
Is there a Postman collection?
Do API calls consume credits?
Related Articles
Ready to try Integrations?
Start free — no credit card required.