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

# Hiring team

> Assign the people responsible for hiring on a job, and list your organization members (API v2)

A job's **hiring team** is the set of people responsible for hiring on it — hiring managers, recruiters, interviewers, and so on. Each member is either **matched** to an organization member or **pending**.

| State       | Meaning                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Matched** | The member's email belongs to an organization member (`organization_member` is set).                                                                                     |
| **Pending** | The email is not yet an organization member (`organization_member` is `null`). When that person later joins the organization, the row resolves to matched automatically. |

<Note>
  Once a hiring team member is **matched** (has an organization account), they are notified about this job: a daily applicant digest covering the jobs they are on (opt-in per member), plus an email when a new application arrives or an interview completes if the job enables those notifications. **Pending** members are notified only after they join the organization.
</Note>

## Manage a job's hiring team

| Method · Path                                          | Purpose                                                                    |
| ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `GET /api/v2/jobs/{job_id}/hiring-team`                | List the job's hiring team.                                                |
| `POST /api/v2/jobs/{job_id}/hiring-team`               | Add a member. Provide **exactly one** of `email` or `organization_member`. |
| `PATCH /api/v2/jobs/{job_id}/hiring-team/{member_id}`  | Update a member's `job_roles`.                                             |
| `DELETE /api/v2/jobs/{job_id}/hiring-team/{member_id}` | Remove a member.                                                           |

**Adding a member.** Send **exactly one** identifier — zero or both returns `400`:

| Field                 | Use when                                                                                                                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`               | You know the person's email. If it matches an existing organization member the row is **matched**; otherwise a **pending** row is created that resolves when they join. This mirrors how ATS syncs seed a team. |
| `organization_member` | You have the member's id from `GET /api/v2/organization/members`. It must belong to your organization.                                                                                                          |

```json theme={null}
{ "email": "recruiter@acme.com", "job_roles": ["RECRUITER"] }
```

**Roles.** `job_roles` is a list drawn from `HIRING_MANAGER`, `RECRUITER`, `COORDINATOR`, `SOURCER`, `INTERVIEWER`, `ADMIN`. It may be empty, and `PATCH` replaces it.

<Note>
  A person appears on a job's team **once** (keyed by email). Re-adding the same email — or an email already held as a pending row — returns `400`. Send an `Idempotency-Key` header to make a retried `POST` replay the original `201` instead of erroring.
</Note>

## List organization members

Use this to discover the `organization_member` ids (and emails) you assign to a hiring team:

| Method · Path                      | Purpose                                                          |
| ---------------------------------- | ---------------------------------------------------------------- |
| `GET /api/v2/organization/members` | List your organization's members, paginated and ordered by name. |

Each row is a membership: the top-level `id` is what you pass as `organization_member`, `role` is the member's org role (`owner`, `admin`, `editor`, `viewer`), and `user` carries their `first_name`, `last_name`, and `email`.

<Note>
  These endpoints, like every v2 write, are authorized by the **organization-scoped API key** alone — there is no per-role restriction, so any key for your organization can manage its hiring teams. The key is owned by a WorkOS user and is **revoked automatically** when that user leaves the organization; there is no service-account owner. Have a **long-tenured** team member own the key and **rotate it before off-boarding**.
</Note>