---
title: "Publish Role"
method: POST
path: "/api/roles/{role_id}/publish"
tags: ["roles"]
---

# Publish Role

`POST /api/roles/{role_id}/publish`

## Request

- Base URL: `https://api.parlel.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.parlel.com/api/roles/{role_id}/publish`
- Auth: none declared

Put a role on the board. Requires the company page to be public already.

## Why the company has to be public first

A role links back to its company for everything a candidate needs in order to
decide whether to apply -- who they are, what they do, where they are, how to
reach them. If the company page is private, ``GET /api/public/companies/{handle}``
404s, the board's join excludes the role anyway, and the "role_url" in every
payload points at a page nobody can load. Publishing into that state would
report success and produce nothing: an opening that is live, unreachable, and
invisible.

So it is a 422 with a sentence naming the fix, rather than a silent success or
a cascade that publishes the company page on the user's behalf. Publishing a
company page is a consent decision (see ``models.Company.is_public``) and it is
not this endpoint's to make.

## Idempotent, and the timestamp is written once

Publishing an already-open role is a 200 and changes nothing. ``published_at``
is stamped only if it is null, so a role that was open, closed, and reopened
keeps its ORIGINAL publication date -- which is the fact that matters, both for
the board's ordering and for anyone asking how long this opening has been
around. ``closed_at`` is cleared on the way back to open, because a role that
is open now is not closed and leaving a stale timestamp would make the payload
say both.

## Path parameters

- `role_id` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/parlel/apis/parlel-api.md) · [All operations](https://skmtc.dev/parlel/apis/parlel-api/llms.txt) · [OpenAPI document](https://skmtc.dev/parlel/apis/parlel-api/revisions/4d41a8f5cfc9?raw)