Skip to main content
POST
Create, change or archive a reason

Authorizations

Authorization
string
header
required

Supabase JWT — Authorization: Bearer <token>.

Body

application/json
type
enum<string>
required

decision (why a candidate was rejected or withdrew) or position_status (why a position went on hold, was cancelled, closed or filled).

Available options:
decision,
position_status
merchant_id
string<uuid>

Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.

reason_id
string<uuid>

The reason to change (from merchant-reason-list). Left out: a new reason is created.

kind
enum<string>

Decision reasons: reject or withdraw. Required for a new one; it cannot change later.

Available options:
reject,
withdraw
label
string

The reason, 1 to 120 characters. Required for a new one; left out on a change, it stays.

Maximum string length: 120
translations
object

Decision reasons: the label per two-letter language code, e.g. {"de": "Zu wenig Erfahrung"}. Replaces the stored translations; left out on a change, they stay.

applies_to
enum<string>[]

Position status reasons: the lifecycles it can be given for (on_hold, cancelled, closed, filled). Required for a new one; left out on a change, it stays.

Minimum array length: 1
Available options:
on_hold,
cancelled,
closed,
filled
sort_order
integer

Position in the list (lower first). Left out: the end of the list for a new reason, unchanged otherwise.

Required range: 0 <= x <= 100000
status
enum<string>

archived: no longer offered; past decisions and lifecycle changes keep it. active: offered again (decision reasons only: an archived position status reason cannot be restored).

Available options:
active,
archived

Response

The reason after the change.

id
string<uuid>
required

Reason id: reason_id of merchant-reason-save, of a decision and of job-interview-set-state.

type
enum<string>
required

decision: why a candidate was rejected or withdrew. position_status: why a position went on hold, was cancelled, closed or filled.

Available options:
decision,
position_status
label
string
required

The reason as the company wrote it.

sort_order
integer
required

Position in the list (lower first).

status
enum<string>
required

active: offered when deciding or changing a lifecycle. archived: kept on past decisions, no longer offered.

Available options:
active,
archived
created
boolean
required

True when a new reason was created.

kind
enum<string>

Decision reasons: reject (the company turned the candidate down) or withdraw (the candidate pulled out).

Available options:
reject,
withdraw
applies_to
enum<string>[]

Position status reasons: the lifecycles it can be given for.

Available options:
on_hold,
cancelled,
closed,
filled
display_label
string

Decision reasons: the label in the requested language (its translation, else the label).

translations
object

Decision reasons: the label per two-letter language code.

default_key
string

Position status reasons: set on the six defaults while their label is unchanged (budget_freeze, priorities_changed, internal_candidate, role_redefined, filled_outside, other).

use_count
integer

Decision reasons: how many decisions use it.