> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ATS Enhanced Features: Reference Checks, Background Checks & Job Boards

> Comprehensive recruitment enhancements including reference checking, background check integration, candidate communication, and job board APIs.

## Overview

Comprehensive recruitment enhancements including reference checking, background check integration, candidate communication, and job board APIs.

## Phase 5.1: Reference Checking

### Database Tables

* `hr_references` - Reference request tracking with ratings
* `hr_reference_emails` - Reference email audit log

### Key Features

* Request references from former employers/colleagues
* Track reference status: pending → sent → viewed → completed
* 1-5 rating scale across multiple categories
* Secure public submission via access tokens

### Hooks

* `useReferences` - List all references
* `useReferencesForCandidate` - Filter by candidate
* `useCreateReference` - Create new reference request
* `useSendReferenceRequest` - Send email to referee

## Phase 5.2: Background Check Integration

### Database Tables

* `hr_background_check_providers` - Provider configuration (Checkr, GoodHire, Sterling)
* `hr_background_check_webhook_dlq` - Failed webhook dead letter queue

### Key Features

* Multi-provider support with encrypted API keys
* Automated FCRA compliance workflow
* Dead letter queue for failed webhooks with retry logic
* TCPA consent gates for SMS notifications

### Hooks

* `useBackgroundCheckProviders` - Manage provider configs
* `useBackgroundCheckDLQ` - Monitor failed webhooks
* `useRetryDLQItem` - Retry failed webhook processing

### Compliance

* FCRA workflow: notice\_sent → dispute\_pending → resolved → final\_notice\_sent
* TCPA: SMS opt-in consent required before sending

## Phase 5.3: Candidate Communication

### Database Tables

* `hr_communication_templates` - Email/SMS templates with variable substitution
* `hr_candidate_communications` - Delivery tracking
* `hr_candidate_portal_accounts` - Portal authentication
* `hr_candidate_portal_sessions` - JWT session management

### Key Features

* Template-driven email and SMS with {{variable}} substitution
* Delivery status tracking: sent → delivered → opened → clicked
* Custom JWT auth for candidate portal (independent of Supabase Auth)
* Magic link verification with rate limiting

### Hooks

* `useCommunicationTemplates` - CRUD for templates
* `useCandidateCommunications` - Send and track messages
* `useCandidatePortal` - Portal account management

### Edge Functions

* `hr-send-communication` - Entra/Gmail (email via shared provider) / RingCentral (SMS)
* `hr-portal-auth` - Magic link verification, JWT issuance
* `hr-portal-invite` - Send portal invitations

## Phase 5.4: Job Board Integration

### Database Tables

* `hr_job_board_integrations` - Board API configuration
* `hr_job_board_postings` - Sync status and performance metrics

### Key Features

* Indeed: API key + HMAC-SHA256 webhooks (baseline)
* LinkedIn: real OAuth 2.0 (3-legged auth + refresh tokens), URN-based job posting payloads, `/v2/jobApplications` import, and `linkedin_v2` HMAC webhook signature scheme. Provider adapters live in `supabase/functions/_shared/job-board-providers/` and are dispatched via `getProvider(board_type)`. OAuth flow: `hr-linkedin-oauth-start` (signed state) → LinkedIn authorize → `hr-linkedin-oauth-callback` (token exchange + vault storage). *(Core: HR | Module: HR-09-P5.4)*
* Auto-post and manual sync paths supported for both providers *(Core: HR | Module: HR-09-P5.4)*
* Webhook-driven metrics updates with provider-specific signature verification *(Core: HR | Module: HR-09-P5.4)*
* View count, click count, application count tracking in posting records *(Core: HR | Module: HR-09-P5.4)*
* Production hardening (auth lifecycle, retries/rate limits, webhook replay/idempotency, import pipeline) tracked in `specs/hr/specs/HR-09-P5-4-job-board-production-hardening.md` *(Core: HR | Module: HR-09-P5.4)*

### Hooks

* `useJobBoardIntegrations` - Manage board connections *(Core: HR | Module: HR-09-P5.4)*
* `useJobBoardPostings` - Track posting status *(Core: HR | Module: HR-09-P5.4)*
* `useJobBoardSync` - Manual sync trigger *(Core: HR | Module: HR-09-P5.4)*

### Edge Functions

* `hr-job-board-sync` - Push jobs to external boards
* `hr-job-board-webhook` - Process board events

## Testing

### RLS Tests

```bash theme={null}
npm run test:rls -- tests/rls/hr-references.rls.test.ts
npm run test:rls -- tests/rls/hr-communication-templates.rls.test.ts
npm run test:rls -- tests/rls/hr-job-board-integrations.rls.test.ts
```

### Unit Tests

```bash theme={null}
npm run test:unit -- tests/unit/hr/useReferences.test.ts
npm run test:unit -- tests/unit/hr/useCommunicationTemplates.test.ts
npm run test:unit -- tests/unit/hr/useJobBoardIntegrations.test.ts
```

### E2E Tests

```bash theme={null}
npm run test:e2e -- tests/e2e/hr/ats-hiring-workflow.spec.ts
```

## Security Considerations

1. **Multi-tenant isolation**: All tables have `organization_id` with RLS
2. **API key encryption**: Provider credentials stored encrypted
3. **TCPA compliance**: SMS requires explicit opt-in consent
4. **FCRA compliance**: Background check workflows enforce legal timelines
5. **Rate limiting**: Portal auth limited to 5 attempts per 30 minutes

## Database Schema Summary

| Table                             | Columns | Description                |
| --------------------------------- | ------- | -------------------------- |
| `hr_references`                   | 28      | Reference request tracking |
| `hr_reference_emails`             | 12      | Reference email audit log  |
| `hr_background_check_webhook_dlq` | 14      | Failed webhook queue       |
| `hr_background_check_providers`   | 16      | Provider configuration     |
| `hr_communication_templates`      | 18      | Email/SMS templates        |
| `hr_candidate_communications`     | 20      | Communication tracking     |
| `hr_candidate_portal_accounts`    | 16      | Portal authentication      |
| `hr_candidate_portal_sessions`    | 10      | Portal JWT sessions        |
| `hr_job_board_integrations`       | 18      | Board API configuration    |
| `hr_job_board_postings`           | 16      | Posting sync tracking      |