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

# Integration Flow

> Understand how the Tidyhire API integration works end-to-end

## How It Works

The diagram below shows how your system connects with Tidyhire.

You can use Tidyhire in two ways:

* **AI Call** — The AI calls candidates on their phone.
* **Interview** — Candidates receive an email with a link to complete an AI interview.

<Frame caption="API Integration Flow">
  <img src="https://mintcdn.com/tidyhireapp/7bq56dfpYw9WljzJ/images/api-integration-flow.png?fit=max&auto=format&n=7bq56dfpYw9WljzJ&q=85&s=2f48e19c75a649d97cc79bcb19a4fdbd" alt="API Integration Flow" width="6823" height="6697" data-path="images/api-integration-flow.png" />
</Frame>

***

### 1. Setup (One-time)

<Steps>
  <Step title="Get your API key">
    Log in to the [Tidyhire Dashboard](https://platform.tidyhire.app) and create an API key from **Settings > API Keys**. See [Authentication](/api-reference/authentication) for details.
  </Step>

  <Step title="Set up your webhook">
    Add a webhook URL in your Tidyhire Dashboard so we can send you results. See [Webhooks](/api-reference/webhooks) for details.
  </Step>
</Steps>

***

### 2. AI Call

Use this when you want the AI to call candidates directly.

<Steps>
  <Step title="Send the call request">
    From your system, use the [Initiate AI Call API](/api-reference/endpoint/call-initiate) with candidate details and what the AI should talk about. You can also set retry rules, WhatsApp messages, and a schedule time.
  </Step>

  <Step title="Candidate receives the call">
    The candidate gets an AI call on their phone.
  </Step>

  <Step title="AI talks to the candidate">
    The AI follows the script and instructions you provided.
  </Step>

  <Step title="Call finishes">
    The call ends and a report is created.
  </Step>

  <Step title="You get the results">
    Call details, transcripts, and collected data are sent to your webhook URL automatically.
  </Step>
</Steps>

***

### 3. Interview

Use this when you want candidates to complete an AI interview on their own time.

<Steps>
  <Step title="Send the interview invitation">
    From your system, use the [Interview Invite API](/api-reference/endpoint/interview-invite). The candidate receives an email with a unique interview link.
  </Step>

  <Step title="Candidate opens the interview">
    The candidate clicks the link and starts the interview.
  </Step>

  <Step title="AI conducts the interview">
    The AI asks the questions and tasks you configured.
  </Step>

  <Step title="Interview finishes">
    The interview ends and scores and reports are created.
  </Step>

  <Step title="You get the results">
    Scores and report links are sent to your webhook URL automatically. You can then update the candidate status in your system.
  </Step>
</Steps>