Documentation | Codiris

Ready-to-use React components and hooks for embedding interviews in your application.

InterviewProvider

Context provider that must wrap your application to use Interview SDK components and hooks.

import { InterviewProvider } from '@codiris/interview-sdk/react';

function App() {
  return (
    <InterviewProvider
      apiKey="your-api-key"
      workspaceId="optional-workspace-id"
    >
      <YourApp />
    </InterviewProvider>
  );
}

Prop	Type	Default	Description
apiKey	string	-	Your Codiris API key (required)
baseUrl	string	Production URL	Custom API base URL
workspaceId	string	-	Optional workspace ID
timeout	number	30000	Request timeout in ms

InterviewEmbed

Embed an interview form in your application via iframe. Ideal for full-page interview experiences.

import { InterviewEmbed } from '@codiris/interview-sdk/react';

function InterviewPage() {
  return (
    <InterviewEmbed
      projectId="your-project-id"
      width="100%"
      height="600px"
      theme="light"
      candidateName="John Doe"
      candidateEmail="john@example.com"
      onReady={() => console.log('Interview loaded')}
      onComplete={(interview) => {
        console.log('Completed:', interview.id);
        // Handle completion
      }}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Prop	Type	Default	Description
projectId	string	-	The project ID to embed (required)
width	string \| number	'100%'	Iframe width
height	string \| number	'600px'	Iframe height
theme	'light' \| 'dark' \| 'system'	'system'	Color theme
locale	string	-	Language locale (e.g., "en", "fr")
showBranding	boolean	true	Show Codiris branding
autoStart	boolean	false	Auto-start the interview
candidateName	string	-	Pre-fill candidate name
candidateEmail	string	-	Pre-fill candidate email
customVariables	Record<string, string>	-	Custom variables to pass
onReady	() => void	-	Called when interview is ready
onComplete	(interview: Interview) => void	-	Called on completion
onError	(error: Error) => void	-	Called on error
onMessage	(message: string) => void	-	Called on postMessage

Floating widget button that opens an interview modal. Perfect for adding interviews to any page.

import { InterviewWidget } from '@codiris/interview-sdk/react';

function App() {
  return (
    <div>
      {/* Your app content */}

      <InterviewWidget
        projectId="your-project-id"
        position="bottom-right"
        buttonText="Start Interview"
        buttonStyle={{
          backgroundColor: '#6366f1',
          textColor: '#ffffff',
          borderRadius: '24px',
        }}
        onOpen={() => console.log('Widget opened')}
        onClose={() => console.log('Widget closed')}
        onComplete={(interview) => {
          console.log('Interview completed:', interview.id);
        }}
      />
    </div>
  );
}

Prop	Type	Default	Description
projectId	string	-	The project ID (required)
position	'bottom-right' \| 'bottom-left' \| 'center'	'bottom-right'	Widget position
triggerType	'button' \| 'auto' \| 'custom'	'button'	How to trigger the widget
triggerDelay	number	0	Delay in seconds for auto trigger
buttonText	string	'Start Interview'	Button label
buttonStyle	ButtonStyle	-	Custom button styling
onOpen	() => void	-	Called when widget opens
onClose	() => void	-	Called when widget closes
onComplete	(interview: Interview) => void	-	Called on completion

InterviewCard

Display an interview summary card with candidate info, status, rating, and duration.

import { InterviewCard } from '@codiris/interview-sdk/react';

function InterviewGrid({ interviews }) {
  return (
    <div className="grid grid-cols-3 gap-4">
      {interviews.map(interview => (
        <InterviewCard
          key={interview.id}
          interview={interview}
          showStatus
          showRating
          showDuration
          onClick={(interview) => {
            router.push(`/interviews/${interview.id}`);
          }}
        />
      ))}
    </div>
  );
}

Prop	Type	Default	Description
interview	Interview	-	The interview data (required)
showStatus	boolean	true	Show status badge
showRating	boolean	true	Show star rating
showDuration	boolean	true	Show duration
onClick	(interview: Interview) => void	-	Click handler

InterviewList

Display a list of interviews with loading states and empty message.

import { InterviewList, useInterviews } from '@codiris/interview-sdk/react';

function InterviewDashboard({ projectId }) {
  const { interviews, loading } = useInterviews(projectId);

  return (
    <InterviewList
      interviews={interviews?.items || []}
      loading={loading}
      emptyMessage="No interviews yet. Share your interview link to get started."
      onInterviewClick={(interview) => {
        router.push(`/interviews/${interview.id}`);
      }}
    />
  );
}

TranscriptViewer

Display interview transcript with message bubbles and timestamps.

import { TranscriptViewer, useTranscript } from '@codiris/interview-sdk/react';

function TranscriptPage({ interviewId }) {
  const { transcript, loading } = useTranscript(interviewId);

  if (loading) return <Loading />;

  return (
    <TranscriptViewer
      transcript={transcript}
      showTimestamps
      style={{ maxHeight: '600px' }}
    />
  );
}

Hooks

useProject

import { useProject } from '@codiris/interview-sdk/react';

function ProjectDetails({ projectId }) {
  const { project, loading, error, refetch } = useProject(projectId);

  if (loading) return <Loading />;
  if (error) return <Error message={error.message} />;

  return (
    <div>
      <h1>{project.name}</h1>
      <p>Use case: {project.useCase}</p>
    </div>
  );
}

useInterviews

import { useInterviews } from '@codiris/interview-sdk/react';

function InterviewsList({ projectId }) {
  const { interviews, loading, error, refetch } = useInterviews(projectId, {
    status: ['completed'],
    page: 1,
    pageSize: 20,
  });

  return (
    <div>
      <p>Total: {interviews?.total}</p>
      {interviews?.items.map(i => <InterviewRow key={i.id} interview={i} />)}
    </div>
  );
}

useInterview

import { useInterview } from '@codiris/interview-sdk/react';

function InterviewDetails({ interviewId }) {
  const { interview, loading, error } = useInterview(interviewId);

  return (
    <div>
      <h2>{interview?.candidateName}</h2>
      <p>Status: {interview?.status}</p>
      <p>Duration: {Math.round((interview?.duration || 0) / 60)} min</p>
    </div>
  );
}

useInterviewResults

import { useInterviewResults } from '@codiris/interview-sdk/react';

function ResultsView({ interviewId }) {
  const { results, loading, generateResults } = useInterviewResults(interviewId);

  if (!results && !loading) {
    return (
      <button onClick={() => generateResults()}>
        Generate AI Analysis
      </button>
    );
  }

  return (
    <div>
      <h3>Score: {results?.overallScore}/100</h3>
      <h4>Strengths</h4>
      <ul>{results?.strengths.map(s => <li key={s}>{s}</li>)}</ul>
    </div>
  );
}

Available Hooks

useProject(projectId) - Fetch a single project
useProjects(options?) - Fetch projects list
useInterview(interviewId) - Fetch a single interview
useInterviews(projectId, filters?) - Fetch interviews list
useTranscript(interviewId) - Fetch transcript
useInterviewResults(interviewId) - Fetch/generate results
useQuestions(projectId) - Fetch questions
useAgents(projectId) - Fetch agents
useInterviewTokens(projectId, filters?) - Fetch tokens
useProjectUsage(projectId) - Fetch usage stats
useCreateBoardFromInterview() - Create Brainboard from interview

API Reference

Complete client methods

Examples

Code examples and recipes

React Components