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

# Participants

> What a participant is, every field explained simply, and how to add one — with hiring, training, and mock-interview examples.

A **participant** is the **person being interviewed** — a candidate, a trainee,
or a student. You create the participant first, then book interviews
(sessions) for them.

A participant belongs to one template. So the same email can show up as two
different participants under two different templates.

## Every field, in plain words

<ParamField path="name" type="string" required>
  The person's full name.
</ParamField>

<ParamField path="email" type="string" required>
  Their email. Must be unique in your account. The invite is sent here.
</ParamField>

<ParamField path="role_id" type="uuid">
  The role you're checking them against.
</ParamField>

<ParamField path="external_id" type="string">
  The person's ID in **your** system (ATS, LMS, app). It comes back in every
  webhook, so you can match results without storing our IDs.
</ParamField>

<ParamField path="profile" type="object">
  Basic info to help the AI: `{ title, organization, experienceLevel, location }`.
</ParamField>

<ParamField path="background" type="object">
  More detail: `{ skills: [...], education, languages: [...] }`.
</ParamField>

<ParamField path="resume_url" type="url">
  A link to their resume. The AI reads it so it can ask better questions.
</ParamField>

<ParamField path="tags" type="string[]">
  Labels you choose, like `["senior", "remote"]`, to find people later.
</ParamField>

## Add one, step by step

<Tabs>
  <Tab title="Dashboard (UI)">
    <Steps>
      <Step title="Open Participants">
        In the team dashboard, click **Participants** in the left sidebar.
      </Step>

      <Step title="Add a participant">
        Click **Add** (or **New participant**).
      </Step>

      <Step title="Fill in name and email">
        These two are required. The email is where the interview invite is sent.
      </Step>

      <Step title="Pick the Role">
        Choose the **Role** this person is being evaluated for.
      </Step>

      <Step title="Save">
        Save. The participant appears in the list, ready to schedule.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    <Steps>
      <Step title="Pick the template">
        Decide which `role_id` this person is for.
      </Step>

      <Step title="Fill in name and email">
        These two are required. The email gets the invite.
      </Step>

      <Step title="Add your own ID">
        Set `external_id` to the person's ID in your system. This saves you pain later.
      </Step>

      <Step title="Send the request">
        ```bash theme={null}
        curl -X POST "https://www.intervyo.ai/api/v1/participants?accountSlug=<slug>" \
          -H "x-api-key: iv_live_your_key_here" \
          -H "Content-Type: application/json" \
          -d '{
            "name": "Jane Smith",
            "email": "jane@example.com",
            "external_id": "greenhouse-8821",
            "role_id": "ce1cd564-...",
            "profile": { "title": "Software Engineer", "experienceLevel": "senior" }
          }'
        ```
      </Step>

      <Step title="Save the ID">
        The response gives you a participant `id`. Use it to schedule a session.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Tip>
  Have a big list? Use the
  [bulk import](/api-reference/participants/post-participants-bulk) endpoint to
  add up to 500 people in one call. Duplicate emails are skipped automatically.
</Tip>

## Examples for each use case

<Tabs>
  <Tab title="Hiring">
    A candidate from your ATS, with a resume.

    ```json theme={null}
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "external_id": "greenhouse-8821",
      "role_id": "ce1cd564-...",
      "profile": { "title": "Software Engineer", "experienceLevel": "senior" },
      "resume_url": "https://.../jane-resume.pdf",
      "tags": ["senior", "backend"]
    }
    ```
  </Tab>

  <Tab title="Training">
    An employee learning a skill. The ID is their HR record.

    ```json theme={null}
    {
      "name": "Carlos Reyes",
      "email": "carlos@yourco.com",
      "external_id": "workday-44120",
      "role_id": "ce1cd564-...",
      "profile": { "title": "Account Executive", "organization": "West Region" },
      "tags": ["q3-cohort"]
    }
    ```
  </Tab>

  <Tab title="Mock interview">
    A student practicing. Keep it light — just enough to say hello.

    ```json theme={null}
    {
      "name": "Priya Patel",
      "email": "priya@student.edu",
      "external_id": "user_98213",
      "role_id": "ce1cd564-...",
      "profile": { "title": "New Grad", "experienceLevel": "entry" }
    }
    ```
  </Tab>
</Tabs>

## Next

<CardGroup cols={2}>
  <Card title="Sessions" icon="message-circle" href="/en/concepts/sessions">
    Book the actual interview for your participant.
  </Card>

  <Card title="Create a participant (API)" icon="terminal" href="/api-reference/participants/post-participants">
    The full endpoint reference.
  </Card>
</CardGroup>