> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Falasefemi2/companyflow/llms.txt
> Use this file to discover all available pages before exploring further.

# List Roles

> Retrieve a paginated list of roles for a company

Get a paginated list of all roles within a company. Supports search and pagination. Requires Super Admin or HR Manager permissions.

## Path Parameters

<ParamField path="company_id" type="string" required>
  The unique identifier of the company
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination

  **Example:** `1`
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Number of items per page

  **Example:** `20`
</ParamField>

<ParamField query="search" type="string">
  Search roles by name

  **Example:** `"Developer"`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  Paginated list of roles

  <Expandable title="Pagination Object">
    <ResponseField name="roles" type="array">
      Array of role objects

      <Expandable title="Role Object">
        <ResponseField name="id" type="string">
          Unique identifier for the role
        </ResponseField>

        <ResponseField name="company_id" type="string">
          The company this role belongs to
        </ResponseField>

        <ResponseField name="name" type="string">
          Name of the role
        </ResponseField>

        <ResponseField name="description" type="string">
          Description of the role
        </ResponseField>

        <ResponseField name="is_system_role" type="boolean">
          Whether this is a system-defined role
        </ResponseField>

        <ResponseField name="permissions_cache" type="string[]">
          Array of cached permission strings
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp of when the role was created
        </ResponseField>

        <ResponseField name="updated_at" type="string">
          ISO 8601 timestamp of when the role was last updated
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of roles matching the query
    </ResponseField>

    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="page_size" type="integer">
      Number of items per page
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.companyflow.com/companies/{company_id}/roles?page=1&page_size=20&search=Developer" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    page: '1',
    page_size: '20',
    search: 'Developer'
  });

  const response = await fetch(
    `https://api.companyflow.com/companies/{company_id}/roles?${params}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.companyflow.com/companies/{company_id}/roles"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  params = {
      "page": 1,
      "page_size": 20,
      "search": "Developer"
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "data": {
      "roles": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "company_id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Senior Developer",
          "description": "Senior-level software development position",
          "is_system_role": false,
          "permissions_cache": ["employees:read", "employees:write"],
          "created_at": "2024-01-15T10:30:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        },
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "company_id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Junior Developer",
          "description": "Entry-level software development position",
          "is_system_role": false,
          "permissions_cache": ["employees:read"],
          "created_at": "2024-01-16T14:20:00Z",
          "updated_at": "2024-01-16T14:20:00Z"
        }
      ],
      "total": 2,
      "page": 1,
      "page_size": 20
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "message": "unauthorized"
  }
  ```
</ResponseExample>