> ## Documentation Index
> Fetch the complete documentation index at: https://developers.partoo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Custom Role

> This endpoint enables you to create custom roles for organizations within your scope.




## OpenAPI

````yaml /assets/openapi/openapi-bundled.yaml post /custom_role
openapi: 3.1.0
info:
  title: Partoo Rest API
  version: v2
  license:
    name: © Copyright Partoo
    url: https://www.partoo.co/en/gtu-api/
  x-logo:
    url: >-
      https://partoo-client-images.s3.amazonaws.com/logo-partoo-restapi-white.png
  description: >
    ## Introduction

    The Partoo Rest API allows you to automate all the actions that are possible
    to do in the Partoo Web Application.


    The Partoo Rest API can be used for many different purposes:
      - Create/update/delete your businesses & users if you are a client.
      - Create/subscribe/manage organizations, businesses & users if you are a reseller.
      - Retrieve data on businesses you have access to if you are a publisher.
      - ...
servers:
  - url: https://api.partoo.co/v2
    description: Production server
  - url: https://api.sandbox.partoo.co/v2
    description: Sandbox server (dev environment for clients & partners)
security:
  - ApiKeyAuth: []
paths:
  /custom_role:
    post:
      tags:
        - Custom Roles
      summary: Create Custom Role
      description: >
        This endpoint enables you to create custom roles for organizations
        within your scope.
      operationId: createCustomRole
      parameters:
        - $ref: '#/components/parameters/query_org_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomRoleCreationBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomRoleCreationResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  parameters:
    query_org_id:
      in: query
      name: org_id
      schema:
        type: integer
      required: false
      description: >
        Organization ID. Only `PROVIDER` users can specify a different
        organization. If not provided, defaults to your own organization.
  schemas:
    CustomRoleCreationBody:
      description: Custom role creation payload.
      type: object
      required:
        - name
        - api_id
        - permissions
      properties:
        name:
          type: string
          description: >-
            Name of the Custom Role. Cannot contain any of the following
            characters: `,;/\|<>`.
          minLength: 1
          maxLength: 100
          pattern: ^[^,;\/\\|<>]{1,100}$
          example: My Custom Role
        api_id:
          type: string
          description: >-
            Unique identifier. Cannot contain any of the following characters:
            `,;/\|<>`.
          minLength: 1
          maxLength: 100
          pattern: ^[^,;\/\\|<>]{1,100}$
          example: my_custom_role
        description:
          type: string
          description: >-
            Description of the Custom Role. Cannot contain any of the following
            characters: `,;/\|<>`.
          minLength: 1
          maxLength: 200
          pattern: ^[^,;\/\\|<>]{1,200}$
          example: This Custom Role is just an example for our API documentation
        permissions:
          description: >-
            List of permission names. (Use GET `/api/v2/permissions` to get a
            list of all available permissions for your organization.)
          type: array
          items:
            type: string
          example:
            - business_edit
            - business_edit_name
            - review_read
        org_id:
          description: >-
            Organization ID (optional). Specify if you have access to more than
            one organization.
          oneOf:
            - $ref: '#/components/schemas/OrgId'
            - type: 'null'
    CustomRoleCreationResponse:
      description: Response returned when a custom role is successfully created.
      type: object
      properties:
        status:
          description: Request status
          type: string
          enum:
            - success
        api_id:
          description: API identifier of the created custom role.
          type: string
          example: my_custom_role
    OrgId:
      description: Unique identifier of an organization in Partoo.
      type: integer
      example: 42
  responses:
    '401':
      description: You are not authenticated
      content:
        application/json:
          schema:
            description: Error that occurs when you are not authenticated
            type: object
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  authentication:
                    type: string
                    default: User not authenticated
    '403':
      description: |
        You are not allowed to perform this action
      content:
        application/json:
          schema:
            description: >
              Error that occurs when you are authenticated but you are trying to
              perform an action you are not allowed to perform
            type: object
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  authorization:
                    type: string
                    default: Operation not allowed
    '404':
      description: Resource does not exist
      content:
        application/json:
          schema:
            description: >-
              Error that occcurs when you are trying to reach a resource that
              does not exist
            type: object
            properties:
              errors:
                type: object
                description: The detail of the error encountered
                properties:
                  json:
                    type: string
                    default: Resource not found
  securitySchemes:
    ApiKeyAuth:
      description: >
        The authentication system on Partoo API is using API Key that should be
        put in the header of the request (the name of the header is `x-APIKey`).
        An api_key is linked to a user. This user's role will give you different
        access level to the API features.
      type: apiKey
      in: header
      name: x-APIKey

````