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

# Sending Invites

> Guide to sending interview invites via email and SMS

## 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:

```json theme={null}
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "deliveryTypes": ["email", "sms"]
}
```

## Delivery Types

### Email Invites

Send invites via email with a link to start the interview:

```json theme={null}
{
  "sendInvite": true,
  "deliveryTypes": ["email"]
}
```

<Callout type="info">
  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.
</Callout>

### SMS Invites

Send invites via SMS with a link to start the interview:

```json theme={null}
{
  "sendInvite": true,
  "deliveryTypes": ["sms"]
}
```

<Callout type="warning">
  Ensure the candidate has `smsOptIn: true` when creating the candidate. SMS delivery requires SMS opt-in.
</Callout>

### Both Email and SMS

Send invites via both email and SMS:

```json theme={null}
{
  "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`

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/candidate-interviews/${candidateInterviewId}/resend-invite`,
      {
        method: 'POST',
        headers: {
          'x-api-key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          deliveryTypes: ['email']
        })
      }
    );
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        f'https://api.prod.qualifi.hr/qsi/gather/candidate-interviews/{candidate_interview_id}/resend-invite',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'deliveryTypes': ['email']
        }
    )
    ```
  </Tab>
</Tabs>

## Expiry Settings

Control when invites expire using the `expiryDays` parameter:

```json theme={null}
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "expiryDays": 7
}
```

<Callout type="info">
  If `expiryDays` is not specified, the default expiry from your organization settings will be used.
</Callout>

## External Redirects

Redirect candidates to a custom URL after completing the interview:

```json theme={null}
{
  "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:

```json theme={null}
{
  "candidateId": "uuid",
  "interviewId": "uuid",
  "sendInvite": true,
  "webhookUrl": "https://yourcompany.com/webhooks/interview-completed"
}
```

<Callout type="info">
  This webhook URL is specific to this candidate interview. For organization-wide webhooks, use the Gather API's webhook configuration endpoints (`/qsi/gather/webhooks`).
</Callout>

## 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}`

```json theme={null}
{
  "data": {
    "id": "uuid",
    "status": "invite_sent",
    "inviteSentAt": "2024-01-01T00:00:00Z",
    "expiry": "2024-01-08T00:00:00Z"
  }
}
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Candidate Interviews API" icon="code" href="/api-reference/candidate-interviews">
    Complete API reference for candidate interviews
  </Card>

  <Card title="Candidates API" icon="user" href="/api-reference/candidates">
    Learn about managing candidates
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Set up webhooks for interview completion notifications
  </Card>

  <Card title="Creating Your First Interview" icon="book" href="/guides/creating-first-interview">
    Complete guide to creating interviews
  </Card>
</CardGroup>