---
title: "Create a custom role"
method: POST
path: "/api/v3/roles/"
tags: ["Roles"]
---

# Create a custom role

`POST /api/v3/roles/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/roles/`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/roles/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new agency-scoped custom role. The role's title must be unique within the agency
and every `(layer, permission)` pair must come from the catalog (`GET /api/v3/roles/permissions`).

## Request body

- RoleWriteRequest: Payload for creating or updating a custom role.
  - `title` string, required: Role title. Must be non-empty and unique within the agency.
  - `description` string: Optional description.
  - `layers` object, required: Permissions grouped by product layer. Use codes from `GET /api/v3/roles/permissions`.

## Response `201`

Role created

- CreateRoleResponse
  - `id` integer, required: ID of the newly created role.

## Other responses

- `400`: Invalid payload (empty title, unknown layer/permission, etc.)
- `409`: A role with the same title already exists in this agency.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)