---
name: Hireflixsl
description: Use when building integrations with one-way video interview workflows, managing candidate invitations and interview tracking, connecting ATS systems, or automating recruitment processes via API or webhooks
metadata:
    mintlify-proj: hireflixsl
    version: "1.0"
---

# Hireflix Skill

## Product summary

Hireflix is a one-way video interview platform that lets you send candidates a set of questions to record answers on their own schedule, then review, score, and share responses. The GraphQL API at `https://api.hireflix.com/me` lets you programmatically invite candidates, track interview progress, fetch results, and manage positions. Authenticate with an API key (generated in your Hireflix account under Profile → API Keys). Key workflows: invite candidates, list interviews, fetch results, update interview status, manage positions, and subscribe to webhooks for real-time events. Primary docs: https://hireflixsl.mintlify.app/tech

## When to use

Reach for this skill when:
- Building an ATS integration or custom recruitment workflow
- Inviting candidates to interviews programmatically from your system
- Tracking interview completion and candidate progress in real time
- Fetching video responses and transcripts to display in your platform
- Setting up webhooks to sync interview events (completion, scoring, status changes)
- Automating bulk candidate invitations or re-invitations
- Updating interview stages (shortlist, discard, archive) from your system
- Connecting Hireflix to Zapier, Make, or other automation platforms
- Embedding interview links or results in your own product

## Quick reference

### API Endpoint & Authentication
| Item | Value |
|------|-------|
| **GraphQL Endpoint** | `https://api.hireflix.com/me` |
| **Auth Header** | `X-Api-Key: <your-api-key>` |
| **Playground** | Apollo Studio (studio.apollographql.com) |
| **HTTP Status** | Always 200 (check response body for errors) |

### Core GraphQL Operations
| Operation | Type | Use Case |
|-----------|------|----------|
| `inviteCandidateToInterview` | Mutation | Invite a candidate to a position |
| `positions` | Query | Fetch all open/archived positions |
| `interviewList` | Query | List all interviews for a position |
| `interview` | Query | Fetch single interview with results, transcripts, scores |
| `Interview(id).delete` | Mutation | Delete an interview (required before re-inviting) |
| `Interview(id).finalist` | Mutation | Mark interview as shortlisted |
| `Interview(id).archive` | Mutation | Mark interview as discarded |
| `Interview(id).score` | Mutation | Add reviewer score and comment |

### Webhook Events
| Event | Trigger | Use For |
|-------|---------|---------|
| `interview.create` | Candidate invited | Sync to ATS, log activity |
| `interview.finish` | Candidate completes | Notify reviewers, update status |
| `interview.status-change` | Status updated (shortlist/discard) | Sync back to ATS |
| `interview.score-updated` | Score added | Update candidate ranking |
| `interview.delete` | Interview deleted | Clean up records |

### Interview Status Values
- `pending` — invite sent, awaiting response
- `completed` — candidate submitted answers
- `shortlisted` — marked as finalist
- `discarded` — rejected
- `archived` — closed/hidden

## Decision guidance

| Scenario | Use API | Use Webhooks | Use ATS Integration |
|----------|---------|--------------|-------------------|
| Invite single candidate from your UI | ✓ | — | ✓ (if available) |
| Bulk invite 100+ candidates | ✓ (with aliases) | — | ✓ (if available) |
| Track completion in real time | — | ✓ (recommended) | ✓ (if available) |
| Periodic status check (no webhooks) | ✓ (polling) | — | — |
| Sync results back to ATS | ✓ or ✓ | ✓ (recommended) | ✓ (if available) |
| Re-invite same candidate | ✓ (delete first) | — | ✓ (if available) |
| Embed interview in your product | ✓ (get URL) | — | — |
| Automate with Zapier/Make | ✓ (custom request) | ✓ | — |

## Workflow

### Typical integration task: Invite candidates and track completion

1. **Fetch available positions**
   - Query `positions` to get position IDs and names
   - Filter out archived positions (where `archivedAtISO` is not null)
   - Store position IDs for later use

2. **Invite a candidate**
   - Call `inviteCandidateToInterview` mutation with position ID, email, first/last name
   - Include phone number with country code if SMS invites needed (e.g., `+1 555 123 4567`)
   - Optionally pass `externalId` to link to your system's candidate record
   - Capture returned interview ID and URLs (public, private, short)

3. **Set up webhook for real-time tracking** (recommended)
   - Go to Profile → Webhooks in Hireflix dashboard
   - Create webhook pointing to your backend endpoint
   - Subscribe to `interview.finish` and `interview.status-change` events
   - Validate webhook signature using secret key (see validation guide)
   - When webhook fires, update candidate status in your system

4. **Alternative: Poll for status** (if webhooks unavailable)
   - Query `interviewList` for a position periodically
   - Check `answered` field (true = completed, false = pending)
   - Update your system when status changes

5. **Fetch interview results after completion**
   - Query `interview` with interview ID
   - Access `stepExecutions[].latestAnswer.video.url` for video playback
   - Access `stepExecutions[].latestAnswer.video.transcription.text` for transcript
   - Note: Video URLs expire after 14 days; fetch fresh URLs on each access

6. **Update interview stage in Hireflix**
   - Call `Interview(id).finalist` to mark as shortlisted
   - Call `Interview(id).archive` to mark as discarded
   - Optionally call `Interview(id).score` to add reviewer feedback

## Common gotchas

- **Each email can only be invited once per position.** If you need to re-invite, delete the old interview first using `Interview(id).delete`, then re-invite.
- **Phone numbers must include country code** (e.g., `+1` for US, `+34` for Spain). Without it, SMS invites fail silently.
- **Video URLs expire after 14 days.** Don't store them in your database. Fetch fresh URLs whenever you need to play a video.
- **GraphQL always returns HTTP 200**, even on errors. Inspect the response body: check for `errors` array or `__typename` field (for union-type mutations). A `__typename` of `InterviewAlreadyExistsInPositionError` means the candidate was already invited.
- **Mutations require a selection set.** You must specify what fields to return (e.g., `id`, `url`), even for delete operations. Omitting this causes "Field X must have a selection of subfields" error.
- **GraphQL queries must be one-line JSON strings** when sent via web clients (Zapier, Make). Use jsonblob.com to convert multi-line queries: escape all quotes and encode line breaks as `\n`.
- **Bulk invites via single HTTP request:** Use GraphQL aliases (`result1:`, `result2:`, etc.) to send multiple mutations in one request, not separate HTTP calls.
- **Positions can't be created via API.** Create them in the Hireflix dashboard first, then fetch their IDs via the API.
- **Interview status changes don't sync automatically.** If you update status in your ATS, you must also call the Hireflix API to keep them in sync (or use a pre-built ATS integration).
- **Webhook secret validation is optional but recommended.** Use the secret key from Profile → Webhooks to verify `x-hireflix-signature` header and prevent spoofed events.

## Verification checklist

Before submitting work with Hireflix integrations:

- [ ] API key is stored securely (environment variable, not hardcoded)
- [ ] All GraphQL mutations include a selection set (return fields specified)
- [ ] Phone numbers include country code prefix (e.g., `+1`)
- [ ] Error handling checks `__typename` or `errors` array, not HTTP status codes
- [ ] Video URLs are fetched fresh on each access (not cached longer than 14 days)
- [ ] Webhook endpoint validates signature using secret key
- [ ] Webhook endpoint returns HTTP 200 to acknowledge receipt
- [ ] Re-invite logic deletes old interview before creating new one
- [ ] Position IDs are fetched and validated before inviting candidates
- [ ] Interview status in your system matches Hireflix status (via webhook or polling)
- [ ] Bulk invites use GraphQL aliases, not separate HTTP requests
- [ ] GraphQL queries are properly escaped if sent as JSON strings (via Zapier/Make)

## Resources

- **Full page navigation:** https://hireflixsl.mintlify.app/llms.txt
- **GraphQL API Quickstart:** https://hireflixsl.mintlify.app/tech/quickstart
- **GraphQL Basics (queries vs mutations):** https://hireflixsl.mintlify.app/tech/graphql-basics
- **Webhook Setup & Events:** https://hireflixsl.mintlify.app/tech/webhooks/getting-started
- **ATS Integrations:** https://hireflixsl.mintlify.app/tech/integrations/overview

---

> For additional documentation and navigation, see: https://hireflixsl.mintlify.app/llms.txt