---
title: "Create user"
method: POST
path: "/v3/users"
tags: ["Users"]
---

# Create user

`POST /v3/users`

Create a new Greenhouse user in your organization. `first_name`, `last_name`, and `primary_email` are required; the user is created with the Basic permission level and no job assignments. Set `send_email_invite=true` to email the new user an invitation; leave it `false` (the default) when an HRIS sync is provisioning accounts ahead of the user's start date. Provide `employee_id` to link the new user to an HRIS record so subsequent calls can look the user up via `employee_ids`. Use `POST /v3/user_job_permissions` or `POST /v3/future_job_permissions` afterwards to grant the user Job Admin access on specific jobs or scopes.

## Request body

- object
  - `send_email_invite` boolean — If `true`, Greenhouse sends the new user an invitation email so they can set a password and sign in. Defaults to `false` — useful when an HRIS sync provisions accounts ahead of the user's actual hire date.
  - `first_name` string, required
  - `last_name` string, required
  - `primary_email` string, email, required — Primary email address for the new user. Sign-in identifier and the address Greenhouse uses for invitation and notification mail. Must be unique within the organization.
  - `job_title` string — Free-form job title to set on the user's Greenhouse profile (e.g. `Senior Recruiter`).
  - `employee_id` string — Partner-supplied external employee identifier — typically the user's HRIS or payroll id. Recommended for HRIS-driven user sync so the user can be looked up later via `employee_ids`.
  - `office_ids` integer[] — Greenhouse office ids to pin the user to. Used for future job permission scoping. Mutually exclusive with `external_office_ids`.
  - `external_office_ids` string[] — External office identifiers (the offices' `external_id`) to pin the user to. Use this when the partner only has external office identifiers. Mutually exclusive with `office_ids`.
  - `department_ids` integer[] — Greenhouse department ids to pin the user to. Used for future job permission scoping. Mutually exclusive with `external_department_ids`.
  - `external_department_ids` string[] — External department identifiers (the departments' `external_id`) to pin the user to. Use this when the partner only has external department identifiers. Mutually exclusive with `department_ids`.
  - `interviewer_tag_ids` integer[] — Ids of interviewer tags to apply to the user, marking them as a qualified interviewer for those skill or panel groupings.
  - `custom_fields` union[]
    - union
      - object
        - `name_key` string, required — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `custom_field_id` integer — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `value` union
          - boolean
          - number — User ID
          - union
            - string[]
            - number[]
      - object
        - `name_key` string — Required if custom_field_id is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `custom_field_id` integer, required — Required if name_key is not provided. Exactly one of name_key or custom_field_id must be specified.
        - `value` union
          - boolean
          - number — User ID
          - union
            - string[]
            - number[]

## Response `201`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `first_name` string, nullable
  - `last_name` string, nullable
  - `primary_email` string — Primary email address on the user's account. Sign-in identifier and the address Greenhouse uses for outbound mail; additional verified addresses are not surfaced here. Service accounts (integration/ISU users) have no email and are excluded from this endpoint by default; when included via `show_service_accounts=true`, their `primary_email` is an empty string.
  - `job_title` string, nullable — Free-form job title set on the user's Greenhouse profile (e.g. `Senior Recruiter`). Not synchronized with any HRIS title.
  - `agency_id` integer, nullable — Id of the staffing agency this user belongs to, when the user is an external agency recruiter rather than an employee of your organization. `null` for in-house users.
  - `name` string, nullable — Concatenation of `first_name` and `last_name` rendered as a single display string. Provided for convenience; partners that need either component should read `first_name`/`last_name` directly.
  - `deactivated` boolean — Whether the user has been deactivated. Deactivated users cannot sign in or be assigned to new jobs, but their historical activity (notes, scorecards, emails) is preserved. Toggle via `POST /v3/users/{id}/deactivate` and `POST /v3/users/{id}/activate`.
  - `site_admin` boolean — Whether the user holds the Site Admin role. Site admins have unrestricted access to every non-confidential job and to organization-level settings. Demote a site admin to a Basic user with `POST /v3/users/{id}/revoke_permissions`.
  - `employee_id` string, nullable — Partner-supplied external employee identifier, typically the user's HRIS or payroll id. Free-form string; not unique across organizations and `null` when no employee id has been set.
  - `linked_candidate_ids` integer[] — Ids of candidate records linked to this user. Populated when an employee is represented by both a user record (for Greenhouse access) and a candidate record (for past or internal applications).
  - `office_ids` integer[] — Ids of the offices this user is assigned to. Used to scope future job permissions and to filter the user list by office. Empty when the user is not pinned to any office.
  - `department_ids` integer[] — Ids of the departments this user is assigned to. Used to scope future job permissions and to filter the user list by department. Empty when the user is not pinned to any department.
  - `interviewer_tags` object[] — Interviewer tags applied to this user — the labeled skill or panel groupings (e.g. `Senior Engineer`, `Bar Raiser`) used to suggest qualified interviewers when building an interview plan. Each entry pairs the tag's `id` with its `name`.
    - `id` integer, required
    - `name` string, required
  - `emails` string[] — All email addresses on the user's account, including the primary address and any additional verified addresses.
  - `custom_fields` object, nullable

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Content

---

[API](https://skmtc.net/greenhouse/apis/auth-api.md) · [All operations](https://skmtc.net/greenhouse/apis/auth-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greenhouse/auth-api/versions/9517a2e54640/schema)