---
title: "Create project role"
method: POST
path: "/rest/api/3/role"
tags: ["Project roles"]
---

# Create project role

`POST /rest/api/3/role`

Creates a new project role with no [default actors](#api-rest-api-3-resolution-get). You can use the [Add default actors to project role](#api-rest-api-3-role-id-actors-post) operation to add default actors to the project role after creating it.

*Note that although a new project role is available to all projects upon creation, any default actors that are associated with the project role are not added to projects that existed prior to the role being created.*<

**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).

## Request body

- CreateUpdateRoleRequestBean
  - `description` string — A description of the project role. Required when fully updating a project role. Optional when creating or partially updating a project role.
  - `name` string — The name of the project role. Must be unique. Cannot begin or end with whitespace. The maximum length is 255 characters. Required when creating a project role. Optional when partially updating a project role.

## Response `200`

Returned if the request is successful.

- ProjectRole — Details about the roles in a project.
  - `actors` RoleActor[] — The list of users who act in this role.
    - `actorGroup` ProjectRoleGroup — Details of the group associated with the role.
      - `displayName` string — The display name of the group.
      - `groupId` string — The ID of the group.
      - `name` string — The name of the group. As a group's name can change, use of `groupId` is recommended to identify the group.
    - `actorUser` ProjectRoleUser — Details of the user associated with the role.
      - `accountId` string — The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Returns *unknown* if the record is deleted and corrupted, for example, as the result of a server import.
    - `avatarUrl` string, uri — The avatar of the role actor.
    - `displayName` string — The display name of the role actor. For users, depending on the user’s privacy setting, this may return an alternative value for the user's name.
    - `id` integer — The ID of the role actor.
    - `name` string — This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details.
    - `type` 'atlassian-group-role-actor' | 'atlassian-user-role-actor' — The type of role actor.
  - `admin` boolean — Whether this role is the admin role for the project.
  - `currentUserRole` boolean — Whether the calling user is part of this role.
  - `default` boolean — Whether this role is the default role for the project
  - `description` string — The description of the project role.
  - `id` integer — The ID of the project role.
  - `name` string — The name of the project role.
  - `roleConfigurable` boolean — Whether the roles are configurable for this project.
  - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
    - `project` ProjectDetails — Details about a project.
      - `avatarUrls` AvatarUrlsBean
        - `16x16` string, uri — The URL of the item's 16x16 pixel avatar.
        - `24x24` string, uri — The URL of the item's 24x24 pixel avatar.
        - `32x32` string, uri — The URL of the item's 32x32 pixel avatar.
        - `48x48` string, uri — The URL of the item's 48x48 pixel avatar.
      - `id` string — The ID of the project.
      - `key` string — The key of the project.
      - `name` string — The name of the project.
      - `projectCategory` UpdatedProjectCategory — A project category.
        - `description` string — The name of the project category.
        - `id` string — The ID of the project category.
        - `name` string — The description of the project category.
        - `self` string — The URL of the project category.
      - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
      - `self` string — The URL of the project details.
      - `simplified` boolean — Whether or not the project is simplified.
    - `type` 'PROJECT' | 'TEMPLATE' — The type of scope.
  - `self` string, uri — The URL the project role details.
  - `translatedName` string — The translated name of the project role.

## Other responses

- `400` — Returned if the request is not valid. The `name` cannot be empty or start or end with whitespace.
- `401` — Returned if the authentication credentials are incorrect or missing.
- `403` — Returned if the user does not have administrative permissions.
- `409` — Returned if a project role with the provided name already exists.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/ec7f275dfee5/schema)