Skip to main content

​
Overview

This guide covers how to send interview invites to candidates using the Gather API. You can send invites via email, SMS, or both.

​
Creating Candidate Interviews

When you create a candidate interview, you can optionally send an invite immediately: 
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "deliveryTypes": ["email", "sms"]
}

​
Delivery Types

​
Email Invites

Send invites via email with a link to start the interview: 
{
  "sendInvite": true,
  "deliveryTypes": ["email"]
}
Email invites include a branded email with a link to start the interview. The link expires based on your organization’s settings or the expiryDays parameter.

​
SMS Invites

Send invites via SMS with a link to start the interview: 
{
  "sendInvite": true,
  "deliveryTypes": ["sms"]
}
Ensure the candidate has smsOptIn: true when creating the candidate. SMS delivery requires SMS opt-in.

​
Both Email and SMS

Send invites via both email and SMS: 
{
  "sendInvite": true,
  "deliveryTypes": ["email", "sms"]
}

​
Resending Invites

If a candidate didn’t receive the invite or it expired, you can resend it: Endpoint: POST /qsi/gather/candidate-interviews/{candidateInterviewId}/resend-invite 
curl -X POST https://api.prod.qualifi.hr/qsi/gather/candidate-interviews/{id}/resend-invite \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryTypes": ["email"]
  }'

​
Expiry Settings

Control when invites expire using the expiryDays parameter: 
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "expiryDays": 7
}
If expiryDays is not specified, the default expiry from your organization settings will be used.

​
External Redirects

Redirect candidates to a custom URL after completing the interview: 
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "externalRedirectUri": "https://yourcompany.com/thank-you"
}

​
Webhook URLs

Specify a webhook URL to receive notifications when the interview is completed: 
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "webhookUrl": "https://yourcompany.com/webhooks/interview-completed"
}
This webhook URL is specific to this candidate interview. For organization-wide webhooks, configure them via Eucalyptus.

​
Best Practices

  1. Verify Contact Information: Ensure email addresses and phone numbers are correct before sending
  2. Use Appropriate Delivery: Use email for professional communications, SMS for urgent reminders
  3. Set Reasonable Expiry: Balance urgency with candidate convenience (7-14 days is typical)
  4. Monitor Status: Check candidate interview status to see if invites were delivered
  5. Resend Strategically: Don’t spam candidates; resend only if needed

​
Checking Invite Status

Check the status of a candidate interview to see if the invite was sent: Endpoint: GET /qsi/gather/candidate-interviews/{candidateInterviewId} 
{
  "data": {
    "id": "uuid",
    "status": "invite_sent",
    "inviteSentAt": "2024-01-01T00:00:00Z",
    "expiry": "2024-01-08T00:00:00Z"
  }
}

Candidate Interviews API

Complete API reference for candidate interviews

Candidates API

Learn about managing candidates

Webhooks

Set up webhooks for interview completion notifications

Creating Your First Interview

Complete guide to creating interviews