API Reference

Postman Collections

Download pre-built Postman collections for testing every Teamcast v2 API endpoint — pre-wired auth, environment variables, and auto-extraction scripts included.

Three ready-to-import Postman collections cover the entire Teamcast v2 API surface — 138 requests organized by domain across 31 folders, with test scripts that auto-save tokens, IDs, and runIds to environment variables as you test.

External integrators (ATS / HRIS): You only need the Interview Integration APIs collection. It uses API key authentication only — no JWT or login required. Teamcast provisions your API key and Tenant ID. That is all you need to drive the full interview lifecycle.

Recruiters and workspace admins: Use the Tenant Admin APIs collection — covers everything from creating jobs and managing interviews to notifications and RBAC.

Platform admins (e.g. LinkedIn): The Platform Admin APIs collection covers login, invite flow, customer tenant API keys, webhook config, and cross-tenant operations.

Import into Postman

Download the JSON files below, then use File > Import in Postman (or drag-and-drop) to load them instantly.

Environment Setup

Start by importing the shared environment file. It defines all variables used across all three collections — base URL, credentials, and auto-populated IDs.

Teamcast v2 — Local Dev Environment

Pre-configured for localhost:4100. Update baseUrl to https://devapi.teamcast.ai/api/v2 for dev cloud.

Environment

Variable	Auto-set?	Description
baseUrl	No	tc-core base URL including /api/v2 (default: http://localhost:4100/api/v2)
adminEmail / recruiterEmail	No	Login credentials — used by the Login request body.
jwtToken	Yes	Auto-saved by Login. Bearer token for Tenant Admin and Platform Admin collections.
tenantId	Yes	Auto-saved by Login. Required alongside X-API-Key on every integration request.
apiKey	Yes	Integration API key (sk_live_...). Auto-saved by Create API Key — shown ONCE.
apiKeyId	Yes	Auto-saved by Create API Key. Used in Update / Revoke API Key.
jobId	Yes	Auto-saved by Create Job.
runId	Yes	Auto-saved by Submit Interview Request. Use for all integration lifecycle calls.
interviewId	Yes	Auto-saved by Create Interview, Add Candidate, or Integration Submit.
candidateToken	Yes	Extracted from joinLink returned by Issue Invite. Used in candidate-access paths.
sessionToken	Yes	Auto-saved by Verify Token. Authorization: Bearer for all candidate endpoints.
userId	Yes	Auto-saved by Create User.
roleId	Yes	Auto-saved by Create Role.
rubricId	Yes	Auto-saved by Generate Rubric.
roleConfigId	Yes	Auto-saved by Save Role Config.
oauthClientId	Yes	Auto-saved by Register OAuth Client.
oauthClientSecret	Yes	Auto-saved by Register OAuth Client — shown ONCE, store immediately.
accessToken	Yes	Auto-saved by OAuth token endpoint (RS256 JWT).
refreshToken	Yes	Auto-saved by OAuth token endpoint. Rotates on every use.
notificationId	Yes	Auto-saved by List Notifications (first item).
platformTenantId	No	Set manually for Platform Admin operations targeting a specific customer tenant.
dlqEntryId	Yes	Auto-saved by List Webhook DLQ (first item). Used to retry dead-lettered deliveries.

Collections

For External Partners

Interview Integration APIs

For external ATS / HRIS partners. Full interview lifecycle (15 REST endpoints), JSON-RPC 2.0 A2A, candidate access flow, OAuth 2.1 token exchange, webhook config, and API key management. API key auth — no JWT login required.

42 requests7 folders

Interview Lifecycle (REST)JSON-RPC 2.0 A2ACandidate AccessOAuth 2.1Webhook ConfigAPI KeysHealth

Download

Tenant Admin APIs

Full recruiter and workspace-admin surface. Auth, Jobs, Interviews (lifecycle + plan + assessment + recording + orchestration), Rubrics, Role Configs, User/RBAC management, API Keys, Workspace OAuth Apps, Notifications, and Webhook Config. Bearer JWT auth.

72 requests17 folders

AuthenticationJobsInterviewsInterview PlanInterview OrchestrationInterview AssessmentInterview RecordingInterview DeliveryCandidate AccessRubrics (HITL-0)Role ConfigsAdmin — Users & RolesAPI KeysWorkspace OAuth AppsNotificationsWebhook ConfigHealth

Download

Platform Admin APIs

For Teamcast super admins and partner platform admins (e.g. LinkedIn). Login, invite flow, customer tenant API key & webhook management, and webhook DLQ. Requires platform-admin role.

24 requests7 folders

AuthenticationPlatform — Tenant ManagementPlatform — Invite FlowPlatform — Customer Tenant API KeysPlatform — Customer Tenant Webhook ConfigWebhook DLQHealth

Download

Quick Start: ATS / HRIS Integration

If you are connecting an external ATS, HRIS, or recruitment platform to Teamcast, this is the only flow you need. No JWT login, no session management — just your API key and Tenant ID on every request.

Set apiKey and tenantId in your Postman environment before starting. Both are issued by your Teamcast account manager.

1. Drive the Interview Lifecycle

Run Submit Interview Request — auto-saves runId
Run Get Interview Status — check the state field
If INFO_NEEDED: run Supply Missing Info
When PLAN_GENERATED: run Approve Plan
Run Issue Candidate Invite — send the joinLink to the candidate
When ASSESSMENT_PENDING: run Approve Assessment

2. Candidate Flow (magic link)

Copy the token from the end of joinLink into candidateToken
Run 1. Get Invitation Info — shows role title + duration (pre-auth)
Run 2. Verify Token — auto-saves sessionToken and interviewId
Run 3. Record Consent — required before start (server-side enforced)
Run 4. Start Interview — advances to IN_PROGRESS, starts clock
Run 5. Get LiveKit Session — creates WebRTC room, dispatches Maya
Run 6. Complete Interview — triggers assessor pipeline

Authentication Modes

Collection	Who Uses It	Auth	Headers Required
Interview Integration APIs	External ATS / HRIS systems	API Key only	X-API-Key + X-Tenant-ID
Tenant Admin APIs	Recruiters and workspace admins	Bearer JWT (jwtToken)	Authorization: Bearer <token>
Platform Admin APIs	Teamcast super admins + partner platform admins	Bearer JWT (platform-admin role)	Authorization: Bearer <token>

Integration APIs use only an API key — no login or JWT required. The key is passed as the X-API-Key header alongside X-Tenant-ID on every request. Tenant Admin and Platform Admin collections use Authorization: Bearer {{jwtToken}} issued by POST /auth/login.

Auto-Extraction Scripts

Key requests include Postman test scripts that automatically save response values to environment variables. You can run requests in sequence without manually copying IDs between calls.

Example: auto-save runId after Submit Interview Request

// Runs automatically after Submit Interview Request
if (pm.response.code === 201 || pm.response.code === 200) {
  const r = pm.response.json();
  if (r.run_id)     pm.environment.set('runId', r.run_id);
  if (r.interview_id) pm.environment.set('interviewId', r.interview_id);
}

Requests that auto-save variables: Login (jwtToken, tenantId), Create Job (jobId), Create Interview (interviewId), Submit Interview Request (runId, interviewId), Issue Invite (candidateToken), Verify Token (sessionToken, interviewId), Start Interview (state check), Create API Key (apiKeyId, apiKey), Create User (userId), Create Role (roleId), Generate Rubric (rubricId), Register OAuth Client (oauthClientId, oauthClientSecret), OAuth Token Exchange (accessToken, refreshToken), List Notifications (notificationId), List Webhook DLQ (dlqEntryId).

Was this page helpful?

Previous← Webhooks

NextOverview →