---
title: "Create Role"
method: POST
path: "/api/roles"
tags: ["roles"]
---

# Create Role

`POST /api/roles`

## 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`
- Auth: none declared

Create a role. Always a draft, never live on the board.

201 here and 200 on the company upsert, and the difference is real rather than
stylistic: this creates a NEW addressable thing with an id the client did not
have, which is exactly what 201 is for. A company page is keyed by the account
and is a save.

Nothing published by this call. See ``RoleCreate`` for why ``status`` is not
an accepted field.

## Headers

- `authorization` string, nullable

## Request body

- RoleCreate: A new role. Created as a draft, always -- ``status`` is not a field here. Publishing is its own endpoint because it has its own precondition (the company page has to be public first) and its own side effect (a timestamp set once). Letting ``POST`` accept ``status: "open"`` would be a second way to publish that skips both, and the one that skips them would be the one a script used.
  - `title` string, required
  - `description` string, nullable
  - `location` string, nullable
  - `remote` 'onsite' | 'hybrid' | 'remote', nullable
  - `employment_type` 'full_time' | 'part_time' | 'contract' | 'internship', nullable
  - `seniority` 'intern' | 'junior' | 'mid' | 'senior' | 'staff' | 'principal' | 'exec', nullable
  - `comp_min` integer, nullable
  - `comp_max` integer, nullable
  - `comp_currency` string, nullable
  - `comp_period` 'year' | 'day' | 'hour', nullable
  - `apply_url` string, nullable: must be a http:// or https:// URL with a hostname and no credentials
  - `skills` string[]

## Response `201`

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)