---
title: "Create application"
method: POST
path: "/v3/applications"
tags: ["Applications"]
---

# Create application

`POST /v3/applications`

Create a new application for an existing candidate. The body accepts one of two shapes: a candidate application (requires `candidate_id` + `job_id`) places the candidate at the job's first interview stage (or `initial_stage_id` when supplied); a prospect application (requires `candidate_id` + `prospect: true`) creates a prospect, optionally attached to one or more jobs via `job_ids`, a prospect pool via `prospect_pool_id` + `prospect_pool_stage_id`, or prospective department/office. To create a candidate and their first application in a single call, use `POST /v3/candidates` with a nested `application` object.

## Request body

- union
  - object
    - `source_id` integer
    - `recruiter_id` integer
    - `coordinator_id` integer
    - `referrer_id` integer
    - `created_at` string, date-time
    - `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
            - string
            - string
            - string
            - string
            - boolean
            - number — User ID
            - union
              - …
            - number
            - object
              - …
        - 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
            - string
            - string
            - string
            - string
            - boolean
            - number — User ID
            - union
              - …
            - number
            - object
              - …
    - `candidate_id` integer, required
    - `job_id` integer, required
    - `initial_stage_id` integer
  - object
    - `source_id` integer
    - `recruiter_id` integer
    - `coordinator_id` integer
    - `referrer_id` integer
    - `created_at` string, date-time
    - `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
            - string
            - string
            - string
            - string
            - boolean
            - number — User ID
            - union
              - …
            - number
            - object
              - …
        - 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
            - string
            - string
            - string
            - string
            - boolean
            - number — User ID
            - union
              - …
            - number
            - object
              - …
    - `candidate_id` integer, required
    - `prospect` boolean, required
    - `job_ids` integer[]
    - `prospect_pool_id` integer
    - `prospect_pool_stage_id` integer
    - `prospect_owner_id` integer
    - `prospective_department_id` integer
    - `prospective_office_id` integer

## Response `201`

Successful

- object
  - `id` integer
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `agency_note_id` integer, nullable — Id of the note created when the candidate was submitted by an agency, or `null` if the application did not come through an agency.
  - `candidate_id` integer — Id of the candidate (person) this application belongs to.
  - `coordinator_id` integer, nullable — Id of the user assigned as coordinator on the application's job, or `null` when unassigned.
  - `job_id` integer, nullable — Id of the job this application is on. `null` for jobless prospect applications.
  - `job_post_id` integer, nullable — Id of the job post the candidate applied through, or `null` if the application was created internally rather than from a posted role.
  - `recruiter_id` integer, nullable — Id of the user assigned as recruiter on the application's job, or `null` when unassigned.
  - `referrer_id` integer, nullable — Id of the referrer who credited this application, or `null` if there was no referral. References a referrer, not a Greenhouse user.
  - `source_id` integer, nullable — Id of the source the application is attributed to (e.g. a job board, an event, an employee referral source). `null` if no source is set.
  - `stage_id` integer, nullable — Id of the interview stage the candidate is currently in for this application. `null` for prospect applications and applications in a terminal state.
  - `job_interview_stage_id` integer, nullable — Id of the job interview stage definition (see `GET /v3/job_interview_stages`) the candidate is currently in for this application. `null` for prospect applications and applications in a terminal state.
  - `stage_name` string, nullable — Display name of the candidate's current interview stage on this application.
  - `status` 'rejected' | 'hired' | 'converted' | 'in_process' — Lifecycle status of the application. `in_process` for active candidates, `rejected` for rejected applications, `hired` once an offer is closed and the hire endpoint has fired, and `converted` for prospect applications that have been promoted to a candidate application via `convert_to_candidate`.
  - `needs_decision` boolean, nullable — `true` when the application is waiting on a hiring-team decision (scorecard completion, advance/reject, etc.) in its current stage.
  - `prospect` boolean — `true` for prospect applications (sourced candidates not yet attached to a single job), `false` for candidate applications on a specific job.
  - `rejected_at` string, date-time, nullable — Timestamp the application was rejected, in ISO 8601. `null` for applications that have not been rejected.
  - `last_activity_at` string, date-time, nullable — Timestamp of the most recent activity on this application (notes, emails, stage changes, etc.), in ISO 8601.
  - `location_address` string, nullable — Free-form location string captured on the application (typically from the job post's location question).
  - `answers` object[], nullable — Free-text answers the candidate provided on the job post application form. Each entry pairs the question text with the candidate's answer.
    - `question` string — Application-form question the candidate answered.
    - `answer` string — Candidate's free-text answer to the question.
  - `prospective_job_ids` integer[] — For prospect applications, the ids of jobs the prospect is being considered for. Empty for non-prospect applications and for jobless prospects.
  - `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)