---
title: "Move an application to another phase"
method: PATCH
path: "/api/v0/applications/{application_id}/phase"
tags: ["Applications"]
---

# Move an application to another phase

`PATCH /api/v0/applications/{application_id}/phase`

## Request

- Base URL: `https://www.getonbrd.com`
- URL: `https://www.getonbrd.com/api/v0/applications/{application_id}/phase`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/getonbrd/apis/get-on-board-api/docs/api/v0/applications/:application_id/phase/patch.ts> (a function with typed inputs; its response is checked against the schema)

Discover phase IDs with `GET /api/v0/processes/{process_id}/phases`. For phases with `kind: "discarded"`, discover valid `discard_reason` values with `GET /api/v0/applications/discard_reasons` and send one returned `id`. Moving back to a non-discarded phase clears the stored discard reason.

## Path parameters

- `application_id` integer, required

## Headers

- `Authorization` string

## Request body

- object
  - `phase_id` integer, required: Target phase ID from `GET /api/v0/processes/{process_id}/phases`.
  - `position` integer: Optional target card position within the target phase.
  - `expand` string[]
  - `discard_reason` string: Required only when the target phase has `kind: "discarded"`; use an `id` from `GET /api/v0/applications/discard_reasons`.

## Response `200`

Moves one application through a hiring process and manages discard reasons for rejected phases. Use `GET /api/v0/processes/{process_id}/phases` to discover valid phase IDs. When the target phase has `kind: "discarded"`, first call `GET /api/v0/applications/discard_reasons` and send one returned `id` as `discard_reason`; moving back to a non-discarded phase clears the stored reason.

- object
  - `data` object, required
    - `id` string, required
    - `type` string, required
    - `attributes` object, required
      - `slug` string, required
      - `deleted` boolean, required
      - `read` boolean, required
      - `messages_count` integer, required
      - `notes_count` integer, required
      - `unlocked` boolean, required
      - `source_channel` 'boost' | 'talent_db' | 'invite' | 'getonbrd' | 'linkedin' | 'facebook' | 'twitter' | 'email' | 'chat' | 'slack' | 'notion' | 'github' | 'gitlab' | 'angel_list' | 'medium' | 'awesomefest' | 'blog' | 'youtube' | 'academy' | 'search' | 'instagram' | 'meetup' | 'google_jobs' | 'aggregator' | 'other' | 'null', nullable: Server-calculated application source. Null means no source was captured; omitted for locked applications. Also included in job.application.sent and job.application.withdrawn webhooks.
      - `unread_messages_from_webpro` integer, required
      - `unread_messages_from_company` integer, required
      - `discard_reason` string, nullable, required
      - `expected_salary` integer, required
      - `reason_to_apply` string, required
      - `professional_background` string, required
      - `academic_background` string, required
      - `sent_at` integer, required
      - `created_at` integer, required
      - `updated_at` integer, required
      - `job` object, required
        - `data` object, required
          - `id` integer, required
          - `type` string, required
      - `phase` object, required
        - `data` object, required
          - `id` integer, required
          - `type` string, required
          - `attributes` object
            - `title` string, required
            - `position` integer, required
            - `kind` string, required
            - `reserved` boolean, required
            - `created_at` integer, required
            - `updated_at` integer, required
      - `professional` object, required
        - `data` object, required
          - `id` integer, required
          - `type` string, required
      - `answers` object, required
        - `data` unknown[], required
          - unknown
      - `messages` object, required
        - `data` unknown[], required
          - unknown
      - `notes` object, required
        - `data` unknown[], required
          - unknown

## Other responses

- `401`: Moves one application through a hiring process and manages discard reasons for rejected phases. Use `GET /api/v0/processes/{process_id}/phases` to discover valid phase IDs. When the target phase has `kind: "discarded"`, first call `GET /api/v0/applications/discard_reasons` and send one returned `id` as `discard_reason`; moving back to a non-discarded phase clears the stored reason.
- `404`: Moves one application through a hiring process and manages discard reasons for rejected phases. Use `GET /api/v0/processes/{process_id}/phases` to discover valid phase IDs. When the target phase has `kind: "discarded"`, first call `GET /api/v0/applications/discard_reasons` and send one returned `id` as `discard_reason`; moving back to a non-discarded phase clears the stored reason.
- `422`: Moves one application through a hiring process and manages discard reasons for rejected phases. Use `GET /api/v0/processes/{process_id}/phases` to discover valid phase IDs. When the target phase has `kind: "discarded"`, first call `GET /api/v0/applications/discard_reasons` and send one returned `id` as `discard_reason`; moving back to a non-discarded phase clears the stored reason.

---

[API](https://skmtc.dev/getonbrd/apis/get-on-board-api.md) - [All operations](https://skmtc.dev/getonbrd/apis/get-on-board-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getonbrd/apis/get-on-board-api/revisions/f8405113049f?raw)