Integration API

Privacy & Data

PII minimization, data retention windows, candidate data purge, and controller/processor boundaries.

Teamcast is designed to handle candidate data minimally and transparently. You can run complete interview workflows using only an opaque candidateRef token — no name, email, or personal data required. When PII is provided, it is stored per-tenant with configurable retention windows and can be purged on demand via a dedicated API with an immutable audit log.

What Is PII in This System

Field	Category	Required?	Notes
candidateRef	Pseudonymous	Recommended	Opaque partner token — no PII stored by Teamcast
candidateName	PII	No	Display name — stored encrypted, purgeable
candidateEmail	PII	No	Used for OTP interview access link — stored encrypted, purgeable
candidateProfile	Context	No	Free-text background summary — purged with PII
qualifications[]	Job data	Recommended	Skill requirements — not personal data
position / level	Job data	Yes	Role description — not personal data
Audio recordings	PII	N/A	Stored in object storage, TTL = recordingRetentionDays

Use candidateRef as your primary candidate identifier. Pass your ATS application ID (e.g. li_app_a1b2c3d4) and never send name or email unless your workflow specifically requires it.

Retention Windows

Each tenant has independent retention windows configured at onboarding. Automatic purge jobs run daily and remove data that has exceeded its window.

Setting	Scope	Default	What Is Purged
candidatePiiRetentionDays	Per-tenant	90 days	candidateName, candidateEmail, candidateProfile, audio recordings
assessmentRetentionDays	Per-tenant	365 days	Assessment JSON, competency scores, qualification evaluations
recordingRetentionDays	Per-tenant	30 days	Raw audio recordings only (assessment text is kept separately)

Retention windows are set per-tenant, not per-platform. If you manage multiple tenants with different compliance requirements (e.g. EU vs US customers), each tenant can have distinct windows.

Candidate Data Purge API

You can purge PII for a specific interview at any time — before the retention window expires. This is useful when a candidate withdraws consent or requests erasure under GDPR Article 17. The purge is irreversible and recorded in an immutable audit log.

Purge Request

bash

curl -X DELETE https://mayaapi.teamcast.ai/api/v1/integration/interviews/run_1749123456_a1b2c3d4/candidate-data \
  -H "X-API-Key: your_api_key" \
  -H "X-Tenant-ID: your_tenant_id" \
  -H "Content-Type: application/json" \
  -d '{
    "requestedBy": "li_recruiter_8821",
    "reason": "Candidate requested erasure under GDPR Article 17"
  }'

Response 200

{
  "message": "Candidate PII purged successfully.",
  "interviewId": "interview-uuid",
  "fieldsWiped": ["candidateName", "candidateEmail", "candidateProfile"],
  "purgedAt": "2024-03-15T09:30:00.000Z",
  "auditLogId": "purge-log-uuid"
}

What Gets Wiped

Field	Action
candidateName	Set to NULL in interviews table
candidateEmail	Set to NULL in interviews table
candidateProfile	Set to NULL in interviews table
Audio recordings	Deleted from object storage
candidateRef	Retained — needed for your ATS correlation
Assessment text	Retained — anonymised by removing name references

Audit Log

Every purge creates an immutable CandidatePurgeLog record. Audit log entries cannot be deleted — they survive even after the interview record is removed by the retention window.

CandidatePurgeLog record

{
  "id": "purge-log-uuid",
  "tenantId": "tenant-uuid",
  "interviewId": "interview-uuid",
  "purgedAt": "2024-03-15T09:30:00.000Z",
  "purgedBy": "li_recruiter_8821",
  "fieldsWiped": ["candidateName", "candidateEmail", "candidateProfile"]
}

Controller / Processor Boundary

Under GDPR, the roles are clearly separated:

Party	GDPR Role	Responsibilities
Your platform (e.g. LinkedIn)	Data Controller	Determines purposes for processing, holds lawful basis, responds to data subject requests, instructs Teamcast on retention and purge
Teamcast	Data Processor	Processes candidate data only on controller instruction, does not use data for its own purposes, provides purge and retention APIs, maintains audit log

Teamcast processes data only to conduct the interview and deliver the assessment back to you. It does not use candidate data for model training, product analytics, or any purpose beyond the contracted service.

Encryption Posture

Layer	Mechanism
In transit	TLS 1.2+ on all API endpoints and webhooks
At rest (database)	PostgreSQL transparent data encryption (TDE) — column-level for name/email
At rest (audio)	Object storage server-side encryption (SSE)
Webhook signing	HMAC-SHA256 — prevents spoofing of inbound events
Interview links	Short-lived signed JWTs — expire after first use or 7 days

Minimal PII Checklist

Use candidateRef — pass your ATS application ID instead of sending name and email
Omit candidateName / candidateEmail — the Hiring Assistant does not need a name to conduct a professional interview
Set short retention windows — configure candidatePiiRetentionDays to the minimum required by your data retention policy
Purge on withdrawal — call DELETE /integration/interviews/:runId/candidate-data immediately on candidate erasure request
Store candidateRef, not PII — your ATS holds the name/email; Teamcast only ever needs the opaque reference

The candidateRef field is returned as-is in all webhooks and status responses. Make sure it does not itself contain PII (e.g. do not use email address as the ref).

Was this page helpful?

Previous← Webhooks

NextData Validation →