Hiring API Reference

Complete API reference for the Sureshake hiring system. All endpoints are available via both TRPC (for internal clients) and REST (via OpenAPI).

Base URL: https://api.sureshake.com/api/v1

Authentication

All endpoints require authentication via Bearer token:

curl -H "Authorization: Bearer $TOKEN" https://api.sureshake.com/api/v1/...

Access Levels

Level	Description
Public	No authentication required
Authenticated	Any logged-in user
Entity Member	Must be team member of the entity
Entity Admin	Must have `manage_hiring_roles` permission

Role Management

Search Public Roles

Search and browse published public roles.

GET /hiring/roles

Access: Public

Query Parameters:

Parameter	Type	Default	Description
`search`	string	-	Search in title and description
`location`	string	-	Filter by location
`remotePolicy`	enum	-	`remote`, `hybrid`, or `onsite`
`entityId`	uuid	-	Filter by entity
`limit`	number	20	Results per page (1-100)
`offset`	number	0	Pagination offset

Get Role Details

GET /hiring/roles/{roleId}

Access: Authenticated (public/unlisted roles) or Entity Member (private roles)

Create Role

POST /entities/{entityId}/hiring/roles

Access: Entity Admin (manage_hiring_roles permission)

Request Body:

{
  "title": "string (required)",
  "description": "string | null",
  "location": "string | null",
  "remotePolicy": "remote | hybrid | onsite | null",
  "salaryRange": {
    "min": "number",
    "max": "number",
    "currency": "string",
    "period": "yearly | monthly | hourly"
  },
  "visibility": "public | unlisted | private",
  "problemSpecs": [...],
  "rubric": {...}
}

Update Role

PUT /entities/{entityId}/hiring/roles/{roleId}

Access: Entity Admin

Publish Role

POST /entities/{entityId}/hiring/roles/{roleId}/publish

Access: Entity Admin

Role must be in draft status and have a title to publish.

Close Role

POST /entities/{entityId}/hiring/roles/{roleId}/close

Access: Entity Admin

List Entity Roles

GET /entities/{entityId}/hiring/roles

Access: Entity Member

Bookmarks

Add Bookmark

POST /hiring/roles/{roleId}/bookmark

Remove Bookmark

DELETE /hiring/roles/{roleId}/bookmark

List Bookmarks

GET /hiring/roles/bookmarks

Applications (Candidate)

Apply to Role

POST /hiring/roles/{roleId}/apply

Access: Authenticated

Request Body:

{
  "coverLetter": "string | null",
  "portfolioItemIds": ["uuid"],
  "answers": [
    {
      "problemSpecId": "string",
      "content": "string"
    }
  ]
}

List My Applications

GET /hiring/applications/mine

Get Application

GET /hiring/applications/{applicationId}

Withdraw Application

POST /hiring/applications/{applicationId}/withdraw

Applications (Recruiter)

List Applications for Role

GET /entities/{entityId}/hiring/roles/{roleId}/applications

Access: Entity Member (with review_applications permission)

Get Application Detail

GET /entities/{entityId}/hiring/applications/{applicationId}

Update Application Status

PUT /entities/{entityId}/hiring/applications/{applicationId}/status

Request Body:

{
  "status": "reviewing | evaluated | hired | rejected"
}

Valid Transitions:

submitted → reviewing
reviewing → evaluated
evaluated → hired or rejected

Record Outcome

POST /entities/{entityId}/hiring/applications/{applicationId}/outcome

Request Body:

{
  "decision": "hired | rejected | withdrawn",
  "startDate": "ISO8601 | null",
  "notes": "string | null"
}

AI Matching

Get Recommended Roles

GET /hiring/roles/recommended

Access: Authenticated

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	20	Max results (1-50)
`minScore`	number	0	Minimum match score (0-1)
`includePreferred`	boolean	true	Include preferred skills
`includeNiceToHave`	boolean	false	Include nice-to-have skills

Get Candidate Matches

GET /entities/{entityId}/hiring/roles/{roleId}/matches

Access: Entity Member

Get Match Details

GET /hiring/roles/{roleId}/match

Access: Authenticated

Get My Skills

GET /hiring/my-skills

Get Role Skills

GET /hiring/roles/{roleId}/skills

Feedback

Create Feedback

POST /entities/{entityId}/hiring/applications/{applicationId}/feedback

Request Body:

{
  "overallScore": "number (1-5)",
  "dimensionScores": [
    {
      "dimensionId": "string",
      "score": "number",
      "comments": "string | null"
    }
  ],
  "strengths": ["string"],
  "gaps": ["string"],
  "recommendation": "strong_yes | yes | consider | no | strong_no"
}

Get Feedback

GET /entities/{entityId}/hiring/applications/{applicationId}/feedback

Common Schemas

Salary Range

{
  "min": "number",
  "max": "number",
  "currency": "string (ISO 4217)",
  "period": "yearly | monthly | hourly"
}

Problem Specification

{
  "id": "string",
  "prompt": "string (max 1000 chars)",
  "successCriteria": "string | null",
  "orderIndex": "number"
}

Evaluation Rubric

{
  "version": "number",
  "dimensions": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "weight": "number (0-1)",
      "scaleMin": "number",
      "scaleMax": "number"
    }
  ]
}

Weights should sum to 1.0 for proper score calculation.

Status Enums

Application Status

Status	Description
`submitted`	Application received
`reviewing`	Under active review
`evaluated`	Evaluation completed
`hired`	Candidate accepted offer
`rejected`	Application declined
`withdrawn`	Candidate withdrew

Role Status

Status	Description
`draft`	Not yet published
`published`	Accepting applications
`closed`	No longer accepting applications

Visibility

Level	Description
`public`	Visible in public search
`unlisted`	Accessible via direct link
`private`	Entity members only

Error Codes

Code	HTTP	Description
`BAD_REQUEST`	400	Invalid input or parameters
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict (e.g., duplicate application)

Example Error Response

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "You have already applied to this role"
  }
}

Rate Limits

Endpoint Category	Rate Limit
Read operations	100 req/min
Write operations	20 req/min
AI Matching	10 req/min

OpenAPI Specification

The complete OpenAPI specification is available at:

Swagger UI: https://api.sureshake.com/api/docs
OpenAPI JSON: https://api.sureshake.com/api/openapi.json

API Reference

On this page