Find Roles

Search for roles by specific criteria. This endpoint allows you to query roles by customer role ID or name.

Endpoint

POST /v1/workspaces/{workspaceId}/role/find

Authentication

Requires Bearer token authentication. See Authentication for details on obtaining an access token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The ID of your workspace

Request Body

At least one search criterion must be provided.

Field	Type	Required	Description
`customerRoleId`	string	No	Search by your custom role identifier
`name`	string	No	Search by role name (partial match supported)

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Sales Manager",
      "description": "Access to sales-related content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    }
  ],
  "total": 1
}

Field	Type	Description
`roles`	array	Array of matching role objects
`total`	number	Total number of matching roles

Examples

Find by Customer Role ID

Search for a role using your custom identifier:

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "sales-manager"
  }'

Response:

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales Manager",
      "description": "Access to sales content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    }
  ],
  "total": 1
}

Find by Name

Search for roles by name (supports partial matching):

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Manager"
  }'

Response:

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales Manager",
      "description": "Access to sales content",
      "customerRoleId": "sales-manager",
      "createdAt": "2025-11-11T10:00:00Z",
      "updatedAt": "2025-11-11T10:00:00Z"
    },
    {
      "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
      "name": "Product Manager",
      "description": "Access to product information",
      "customerRoleId": "product-manager",
      "createdAt": "2025-11-10T14:00:00Z",
      "updatedAt": "2025-11-10T14:00:00Z"
    }
  ],
  "total": 2
}

Combine Search Criteria

Search using multiple criteria (results match ALL criteria):

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/find' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "sales-manager",
    "name": "Sales"
  }'

No Results

When no roles match the criteria:

{
  "roles": [],
  "total": 0
}

Error Responses

400 Bad Request

No search criteria provided:

{
  "error": "Bad Request",
  "message": "At least one search criterion required"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "Failed to search roles"
}

Notes

Search Behavior

Customer Role ID: Exact match only
Name: Partial match, case-insensitive
Multiple criteria: Results must match ALL provided criteria (AND logic)

Use Cases

This endpoint is useful when:

You know the customer role ID but need the Sharely UUID
You want to search for roles by name pattern
You need to verify if a role exists before creating it

Alternative Endpoints

For exact UUID lookup: Use Get Role
For exact customer role ID lookup: Use Get by Customer Role ID
For listing all roles: Use List Roles

Related Endpoints

List Roles - Get all roles
Get by Customer Role ID - Direct lookup by custom ID
Get Role - Get by UUID

Use Cases

Verify Role Exists

Check if a role exists before creating:

async function roleExists(workspaceId, customerRoleId) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/find`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'sk-sharely-your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ customerRoleId })
    }
  );
 
  const { total } = await response.json();
  return total > 0;
}

Search and Display

Search for roles matching a pattern:

async function searchRoles(workspaceId, searchTerm) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/find`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'sk-sharely-your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: searchTerm })
    }
  );
 
  const { roles } = await response.json();
  return roles;
}