How to create, manage, and publish hiring roles for your organization on Sureshake.

Recruiter Guide

This guide explains how to create, manage, and publish hiring roles for your organization on Sureshake.

Overview

As an entity team member with manage_hiring_roles permission, you can:

Create role drafts with job details and requirements
Define problem specifications and evaluation rubrics
Publish roles to make them visible to candidates
Close roles when you're done accepting applications
View and manage all roles for your organization

Prerequisites

Before posting a role, ensure you have:

Entity membership — You must be a team member of the organization
Hiring permission — You need manage_hiring_roles permission
Entity setup — Your organization (entity) must be created and verified

Creating a Role Draft

Prepare Role Information

Gather the following information before creating a role:

Field	Required	Description
Title	Yes	Job title (e.g., "Senior Backend Engineer")
Description	No	Detailed job description (up to 5000 characters)
Location	No	Physical location (e.g., "San Francisco, CA")
Remote Policy	No	`remote`, `hybrid`, or `onsite`
Salary Range	No	Min/max salary with currency and period
Visibility	No	`public`, `unlisted`, or `private` (default: `private`)

Create the Role

curl -X POST "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "your-entity-uuid",
    "title": "Senior Backend Engineer",
    "description": "We are looking for an experienced backend engineer...",
    "location": "San Francisco, CA",
    "remotePolicy": "hybrid",
    "salaryRange": {
      "min": 150000,
      "max": 200000,
      "currency": "USD",
      "period": "yearly"
    },
    "visibility": "private"
  }'

New roles are always created as draft status. You must explicitly publish them to start accepting applications.

Adding Problem Specifications

Problem specifications define what candidates should demonstrate in their applications.

Structure

{
  "problemSpecs": [
    {
      "id": "ps-1",
      "prompt": "Describe a complex distributed system you've designed",
      "successCriteria": "Clear explanation of trade-offs and scalability considerations",
      "orderIndex": 0
    },
    {
      "id": "ps-2",
      "prompt": "How would you handle data consistency in a microservices architecture?",
      "orderIndex": 1
    }
  ]
}

Adding to a Role

Include problemSpecs when creating or updating a role:

curl -X PUT "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "your-entity-uuid",
    "roleId": "role-uuid",
    "problemSpecs": [
      {
        "id": "ps-1",
        "prompt": "Describe your experience with API design",
        "successCriteria": "RESTful principles, versioning strategy",
        "orderIndex": 0
      }
    ]
  }'

Defining an Evaluation Rubric

The rubric helps standardize candidate evaluation across reviewers.

Structure

{
  "rubric": {
    "version": 1,
    "dimensions": [
      {
        "id": "dim-1",
        "name": "Technical Skills",
        "description": "Depth of technical knowledge and practical experience",
        "weight": 0.4,
        "scaleMin": 1,
        "scaleMax": 5
      },
      {
        "id": "dim-2",
        "name": "Communication",
        "description": "Clarity of written and verbal communication",
        "weight": 0.3,
        "scaleMin": 1,
        "scaleMax": 5
      },
      {
        "id": "dim-3",
        "name": "Problem Solving",
        "description": "Approach to complex problems",
        "weight": 0.3,
        "scaleMin": 1,
        "scaleMax": 5
      }
    ]
  }
}

Weights should sum to 1.0 for proper score calculation.

Publishing a Role

Once your role is ready, publish it to start accepting applications.

Requirements Before Publishing

Role must have a title
Role must be in draft status
Recommended: Add problem specifications and rubric

Publish Command

curl -X POST "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "your-entity-uuid",
    "roleId": "role-uuid"
  }'

What Happens:

Status changes from draft to published
publishedAt timestamp is recorded
Role becomes visible based on its visibility setting:
- public: Appears in public job board search
- unlisted: Accessible via direct link
- private: Only visible to entity team members

Managing Role Visibility

Visibility Options

Visibility	Public Search	Direct Link	Entity Members
`public`	Yes	Yes	Yes
`unlisted`	No	Yes	Yes
`private`	No	No	Yes

Changing Visibility

curl -X PUT "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "your-entity-uuid",
    "roleId": "role-uuid",
    "visibility": "public"
  }'

Closing a Role

When you're done accepting applications, close the role.

curl -X POST "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "your-entity-uuid",
    "roleId": "role-uuid"
  }'

What Happens:

Status changes from published to closed
closesAt timestamp is recorded
Role no longer accepts new applications
Existing applications remain accessible

Listing Your Organization's Roles

View all roles for your organization (including drafts and closed):

curl -X GET "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles?status=published&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters

Parameter	Type	Default	Description
`status`	string	all	Filter by `draft`, `published`, or `closed`
`limit`	number	20	Results per page (1-100)
`offset`	number	0	Pagination offset

Role Lifecycle

DRAFT ─────→ PUBLISHED ─────→ CLOSED
  │              │               │
  │              │               │
Create        Publish          Close
Update        Accept Apps      No new apps
              AI Matching      Archive

Reviewing Applications

List Applications for a Role

curl -X GET "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}/applications" \
  -H "Authorization: Bearer $TOKEN"

View Application Details

curl -X GET "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/applications/{applicationId}" \
  -H "Authorization: Bearer $TOKEN"

Update Application Status

curl -X PUT "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/applications/{applicationId}/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "reviewing"
  }'

Creating Evaluations

Score candidates against your rubric dimensions:

curl -X POST "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/applications/{applicationId}/evaluations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scores": [
      {
        "dimensionId": "dim-1",
        "score": 4,
        "notes": "Strong technical background with relevant experience"
      },
      {
        "dimensionId": "dim-2",
        "score": 5,
        "notes": "Excellent communication in problem spec responses"
      }
    ],
    "overallNotes": "Strong candidate, recommend for interview"
  }'

Once submitted, evaluations are immutable. This ensures a fair and consistent evaluation process.

Publishing Feedback

Share structured feedback with candidates:

curl -X POST "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/applications/{applicationId}/feedback" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "strengths": ["Technical skills", "Problem solving approach"],
    "gaps": ["Domain expertise in payments"],
    "recommendation": "consider",
    "notes": "Strong candidate overall, would benefit from more payments experience",
    "publishToCandidate": true
  }'

AI-Powered Matching

Get ranked candidates for your role:

curl -X GET "https://api.sureshake.com/api/v1/entities/{entityId}/hiring/roles/{roleId}/matches" \
  -H "Authorization: Bearer $TOKEN"

The response includes match scores and explanations for each candidate.

Best Practices

Writing Effective Role Descriptions

Be specific — Clearly state responsibilities and requirements
Include growth — Mention career development opportunities
Be honest — Accurately represent the role and team
Use structure — Break into sections (About, Responsibilities, Requirements)

Designing Good Problem Specifications

Open-ended — Allow candidates to demonstrate depth
Relevant — Tie to actual job responsibilities
Clear criteria — Define what "good" looks like
Reasonable scope — Respect candidates' time

Building Fair Rubrics

Multiple dimensions — Avoid single-metric evaluation
Clear descriptions — Reduce evaluator subjectivity
Balanced weights — Reflect actual job priorities
Consistent scales — Use same min/max across dimensions

Troubleshooting

"FORBIDDEN: You do not have permission"

Cause: Missing manage_hiring_roles permission Solution: Contact your entity admin to grant hiring permissions

"BAD_REQUEST: Cannot publish role without title"

Cause: Role is missing required fields Solution: Update the role to add a title before publishing

"CONFLICT: Role status does not allow this action"

Cause: Trying to publish a closed role or close a draft Solution: Check current status; only draft → published and published → closed transitions are allowed

Recruiter Guide

On this page