HRwise.ai API Documentation

Welcome to HRwise.ai API

The HRwise.ai API provides programmatic access to your HR data, succession planning, and employee analytics. This RESTful API uses standard HTTP methods and returns JSON responses.

Base URL

https://api.hrwise.ai

Authentication

All API requests require JWT authentication using Bearer tokens.

Authentication Flow:

Exchange API Key for JWT Tokens: Call POST /api/v1/token/ with your API key(can be obtained from Hrwise account/settings/api_keys) to receive access and refresh tokens
Use Access Token: Include the access token in the Authorization header for all API calls: Authorization: Bearer <access_token>
Refresh When Expired: When your access token expires (after 24 hours), use the refresh token to get new tokens via POST /api/v1/token/refresh/

# Step 1: Exchange API key for JWT tokens
curl -X POST https://api.hrwise.ai/api/v1/token/ \
     -H "Content-Type: application/json" \
     -d '{"api_key": "hrw_your_api_key_here"}'

# Step 2: Use access token in subsequent requests
curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
     https://api.hrwise.ai/api/v1/employees/

# Step 3: Refresh token when expired
curl -X POST https://api.hrwise.ai/api/v1/token/refresh/ \
     -H "Content-Type: application/json" \
     -d '{"refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."}'
            

⚠️ Important:

Access tokens expire after 24 hours
Refresh tokens expire after 7 days
Store your tokens securely - never expose them in client-side code
Each token refresh generates new access and refresh tokens (the old refresh token is blacklisted)

Rate Limiting

Rate Limit: 1000 requests per hour per company

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per hour
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Response Format

All responses are returned in JSON format with a consistent structure:

// Success Response
{
  "success": true,
  "data": {
    "id": 123,
    "employee_id": "EMP001",
    "full_name": "John Doe",
    ...
  }
}

// Error Response
{
  "success": false,
  "error": {
    "code": "EMPLOYEE_NOT_FOUND",
    "message": "No employee found with identifier: EMP999"
  }
}
            

HTTP Status Codes

Status Code	Description
200	Success - Request completed successfully
201	Created - Resource created successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing authentication token
404	Not Found - Resource does not exist
500	Internal Server Error - Something went wrong on our end

Support

For API support, questions, or to report issues, please contact us at info@hrwise.ai

📋 Endpoints

Authentication
POST /api/v1/token/ - Exchange API Key for Tokens
POST /api/v1/token/refresh/ - Refresh Access Token
Employee Management
GET /api/v1/employees/ - List Employees
GET /api/v1/employees/{identifier}/ - Get Employee Details
POST /api/v1/invite-to-hrwise/ - Invite Employee to Platform
Succession Planning
GET /api/v1/successors/ - List Successors by Position
GET /api/v1/successors/{identifier}/ - Get Successor Details
GET /api/v1/bench-strength/ - Get Bench Strength Table

POST

/api/v1/token/

Exchange API key for JWT access and refresh tokens

▼

Description

Exchange your API key for JWT access and refresh tokens. This is the first step in the authentication flow. The access token is used for all subsequent API calls, while the refresh token is used to obtain new access tokens when they expire.

Request Body

Field	Type	Required	Description
api_key	string	Required	Your HRwise.ai API key (format: `hrw_xxxxxxxxxxxxx`)

Example Request

curl -X POST "https://api.hrwise.ai/api/v1/token/" \
     -H "Content-Type: application/json" \
     -d '{
       "api_key": "hrw_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
     }'
                    

Response

200 OK Success

{
  "success": true,
  "data": {
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "company": {
      "id": 123,
      "name": "Acme Corporation"
    }
  }
}
                        

Response Fields

Field	Description
access	JWT access token (valid for 24 hours)
refresh	JWT refresh token (valid for 7 days)
token_type	Token type (always "Bearer")
expires_in	Access token expiration time in seconds (86400 = 24 hours)
company	Your company information

Error Responses

400 Bad Request Missing API key

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required in request body"
  }
}
                        

401 Unauthorized Invalid API key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}
                        

Security Best Practices:

Never expose your API key or tokens in client-side code
Store tokens securely (encrypted storage, environment variables, secrets manager)
Implement token refresh logic to handle expiration gracefully
Rotate your API key regularly for enhanced security

POST

/api/v1/token/refresh/

Refresh access token using refresh token

▼

Description

Use your refresh token to obtain a new access token and refresh token. This should be called when your access token expires (after 24 hours). The old refresh token will be blacklisted after a successful refresh.

Request Body

Field	Type	Required	Description
refresh	string	Required	Your current refresh token

Example Request

curl -X POST "https://api.hrwise.ai/api/v1/token/refresh/" \
     -H "Content-Type: application/json" \
     -d '{
       "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
     }'
                    

Response

200 OK Success

{
  "success": true,
  "data": {
    "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_in": 86400
  }
}
                        

Error Responses

401 Unauthorized Invalid or expired refresh token

{
  "success": false,
  "error": {
    "code": "INVALID_REFRESH_TOKEN",
    "message": "Token is invalid or expired"
  }
}
                        

Important: Each successful token refresh generates new access AND refresh tokens. The old refresh token is automatically blacklisted and cannot be reused. Always update your stored tokens after a successful refresh.

Token Lifecycle Example

# Day 1: Get initial tokens
POST /api/v1/token/
→ access_token_1 (expires in 24h), refresh_token_1 (expires in 7 days)

# Day 2: Access token expired, refresh it
POST /api/v1/token/refresh/ with refresh_token_1
→ access_token_2 (expires in 24h), refresh_token_2 (expires in 7 days)
# refresh_token_1 is now blacklisted

# Day 3: Access token expired, refresh again
POST /api/v1/token/refresh/ with refresh_token_2
→ access_token_3 (expires in 24h), refresh_token_3 (expires in 7 days)
# refresh_token_2 is now blacklisted

# Day 8: Refresh token expired, get new tokens with API key
POST /api/v1/token/ with api_key
→ access_token_4 (expires in 24h), refresh_token_4 (expires in 7 days)
                    

GET

/api/v1/employees/

Retrieve a paginated list of employees

▼

Description

Returns a paginated list of employees for your company. Supports filtering by active status, department, high performer status, and attrition risk.

Authentication

Requires JWT Bearer token in Authorization header

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Query Parameters

Parameter	Type	Required	Description
is_active	boolean	Optional	Filter by active status. Values: `true` or `false`
department	string	Optional	Filter by department name (case-insensitive)
is_high_performer	boolean	Optional	Filter high performers. Values: `true` or `false`
at_risk	boolean	Optional	Filter employees at risk (attrition score > 70). Values: `true`
page	integer	Optional	Page number for pagination (default: 1)
page_size	integer	Optional	Number of items per page (default: 50, max: 100)

Example Request

curl -X GET "https://api.hrwise.ai/api/v1/employees/?is_active=true&page=1&page_size=50" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
                    

Response

200 OK Success

{
  "success": true,
  "data": {
    "count": 150,
    "next": "https://api.hrwise.ai/api/v1/employees/?page=2&page_size=50",
    "previous": null,
    "page": 1,
    "page_size": 50,
    "total_pages": 3,
    "results": [
      {
        "id": 123,
        "employee_id": "EMP001",
        "full_name": "John Doe",
        "email": "john.doe@company.com",
        "phone": "+1234567890",
        "company": 1,
        "department": {
          "id": 5,
          "name": "Engineering"
        },
        "position": "Senior Software Engineer",
        "position_start_date": "2020-01-15",
        "hire_date": "2018-03-01",
        "education": "Bachelor's in Computer Science",
        "certifications": ["AWS Certified", "Scrum Master"],
        "no_of_trainings": 12,
        "gender": "Male",
        "recruitment_channel": "LinkedIn",
        "age": 32,
        "previous_year_rating": 4.5,
        "length_of_service": 6.8,
        "awards_won": 2,
        "avg_training_score": 87.5,
        "performance_score": 92.3,
        "status": "ready for promotion",
        "attrition_risk_score": 25.5,
        "extra_data": {},
        "last_analyzed": "2024-01-15T10:30:00Z",
        "is_high_performer": true,
        "high_performer_date": "2023-06-01T00:00:00Z",
        "onboarded": true,
        "is_active": true,
        "seniority_level": "Senior",
        "evaluation_history": [],
        "current_progress_score": 85.0,
        "skill_gaps": ["Cloud Architecture", "Team Leadership"],
        "role_fit_score": "90",
        "created": "2018-03-01T09:00:00Z",
        "modified": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
                        

Error Responses

401 Unauthorized Invalid or missing token

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Authentication credentials were not provided"
  }
}
                        

GET

/api/v1/employees/{identifier}/

Get detailed information about a specific employee

▼

Description

Retrieve detailed information about a specific employee. The identifier can be the employee's ID, employee_id, or email address.

Authentication

Requires JWT Bearer token in Authorization header

Path Parameters

Parameter	Type	Required	Description
identifier	string	Required	Employee identifier: can be `id` (integer), `employee_id` (string), or `email`

Query Parameters

Parameter	Type	Required	Description
query	string	Optional	Specify what data to return. Valid values: `skill_gaps`, `progress`, `trainings`, `tasks`, `mentorships`. If omitted, returns full employee details.

Example Requests

# Get full employee details by employee_id
curl -X GET "https://api.hrwise.ai/api/v1/employees/EMP001/" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

# Get employee skill gaps by email
curl -X GET "https://api.hrwise.ai/api/v1/employees/john.doe@company.com/?query=skill_gaps" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

# Get employee trainings by ID
curl -X GET "https://api.hrwise.ai/api/v1/employees/123/?query=trainings" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
                    

Response - Full Employee Details

200 OK Success (without query parameter)

{
  "success": true,
  "data": {
    "id": 123,
    "employee_id": "EMP001",
    "full_name": "John Doe",
    "email": "john.doe@company.com",
    // ... (same structure as list endpoint)
  }
}
                        

Response - Skill Gaps (query=skill_gaps)

200 OK Success

{
  "success": true,
  "data": {
    "skill_gaps": [
      "Cloud Architecture",
      "Team Leadership",
      "Strategic Planning"
    ]
  }
}
                        

Response - Progress Score (query=progress)

200 OK Success

{
  "success": true,
  "data": {
    "progress_score": 85.5
  }
}
                        

Response - Trainings (query=trainings)

200 OK Success

{
  "success": true,
  "data": {
    "trainings": [
      {
        "id": 1,
        "employee_name": "John Doe",
        "skill_name": "Cloud Architecture",
        "course_name": "AWS Solutions Architect",
        "start_date": "2024-01-01",
        "completion_date": "2024-03-15",
        "provider": "Coursera",
        "status": "completed",
        "rating": 5,
        "feedback": "Excellent course",
        "evidence": "https://api.hrwise.ai/media/certificates/cert123.pdf",
        "department": "Engineering",
        "manager_rating": 4
      }
    ]
  }
}
                        

Response - Tasks (query=tasks)

200 OK Success

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": 1,
        "employee_name": "John Doe",
        "department": "Engineering",
        "source": "Jira",
        "project_name": "Migration Project",
        "scope": "Lead cloud migration",
        "status": "completed",
        "rating": 5,
        "feedback": "Excellent execution",
        "evidence": "https://api.hrwise.ai/media/reports/report123.pdf",
        "manager_rating": 5,
        "external_id": "JIRA-12345"
      }
    ]
  }
}
                        

Response - Mentorships (query=mentorships)

200 OK Success

{
  "success": true,
  "data": {
    "mentorships": [
      {
        "id": 1,
        "employee_name": "John Doe",
        "mentor_name": "Jane Smith",
        "area_of_support": "Leadership Development",
        "status": "active",
        "feedback": "Great progress",
        "evidence": "https://api.hrwise.ai/media/mentorship/notes123.pdf",
        "department": "Engineering",
        "rating": 5,
        "manager_rating": 4
      }
    ]
  }
}
                        

Error Responses

400 Bad Request Invalid query parameter

{
  "success": false,
  "error": {
    "code": "INVALID_QUERY_PARAMETER",
    "message": "Query must be one of: skill_gaps, progress, trainings, tasks, mentorships",
    "provided": "invalid_query"
  }
}
                        

404 Not Found Employee not found

{
  "success": false,
  "error": {
    "code": "EMPLOYEE_NOT_FOUND",
    "message": "No employee found with identifier: EMP999"
  }
}
                        

POST

/api/v1/invite-to-hrwise/

Invite an employee to the HRwise platform

▼

Description

Creates or updates an employee record and sends an invitation email to access the HRwise platform. If the employee already exists, their information will be updated.

Authentication

Requires JWT Bearer token in Authorization header

Request Body

Field	Type	Required	Description
email	string	Required	Employee's email address (must be valid email format)
first_name	string	Required	Employee's first name
last_name	string	Required	Employee's last name
department_name	string	Required	Department name (must exist in your company)
position	string	Required	Employee's job position/title

Example Request

curl -X POST "https://api.hrwise.ai/api/v1/invite-to-hrwise/" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
     -H "Content-Type: application/json" \
     -d '{
       "email": "jane.smith@company.com",
       "first_name": "Jane",
       "last_name": "Smith",
       "department_name": "Engineering",
       "position": "Software Engineer"
     }'
                    

Response

201 Created Success - Employee created and invitation sent

{
  "success": true,
  "data": {
    "message": "Employee created and invitation sent successfully",
    "employee_id": 456,
    "email": "jane.smith@company.com",
    "user_created": true,
    "employee_created": true,
    "invitation_sent": true
  }
}
                        

Error Responses

400 Bad Request Missing or invalid fields

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required"
  }
}

// Or
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}

// Or
{
  "success": false,
  "error": {
    "code": "DEPARTMENT_NOT_FOUND",
    "message": "Department 'Marketing' does not exist in your company",
    "detail": "Please create the department first"
  }
}

// Or
{
  "success": false,
  "error": {
    "code": "EMAIL_ALREADY_REGISTERED",
    "message": "A user with this email already exists in another company"
  }
}
                        

Note: If an employee already exists with the same email, their information (name, department, position) will be updated, and a new invitation will be sent.

GET

/api/v1/successors/

Get successors grouped by position with bench strength metrics

▼

Description

Returns all succession planning data grouped by position/role. Each position includes the current role holder, all successors, and a calculated bench strength index (BSI) score.

Authentication

Requires JWT Bearer token in Authorization header

Query Parameters

Parameter	Type	Required	Description
department	string	Optional	Filter by department name (case-insensitive)
readiness_level	string	Optional	Filter by readiness level. Valid values: `ready_now`, `<6_months`, `6-12_months`, `12-24_months`, `>24_months`

Bench Strength Index (BSI)

The BSI is calculated using the following weighted factors:

Readiness (35%): How soon successors will be ready
Successor Utilization (20%): How many roles each successor is assigned to
Attrition Risk (20%): Risk of successors leaving the company
Data Freshness (10%): How recently successor data was updated
Source Diversity (15%): Mix of internal vs cross-department successors

BSI scores range from 0-100, where higher scores indicate stronger succession coverage.

Example Request

curl -X GET "https://api.hrwise.ai/api/v1/successors/?department=Engineering" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
                    

Response

200 OK Success

{
  "success": true,
  "data": [
    {
      "current_role_holder": {
        "id": 123,
        "full_name": "John Doe",
        "email": "john.doe@company.com",
        "department": "Engineering",
        "position": "Senior Engineer"
      },
      "successors": [
        {
          "id": 1,
          "employee_name": "Jane Smith",
          "current_position": "Engineer",
          "department": "Engineering",
          "role_to_succeed": "Senior Engineer",
          "expected_readiness": "ready_now",
          "predecessor_name": "John Doe",
          "fit_score_display": "85",
          "initial_gaps": ["Team Leadership"],
          "updated_gaps": [],
          "progress_status": {
            "status": "on_track",
            "predicted_readiness": null
          },
          "initial_fit": "75",
          "updated_fit": "85",
          "employee": 456
        }
      ],
      "bench_strength": 82.5
    }
  ]
}
                        

Note: The fields initial_gaps and initial_fit represent the original assessment, while updated_gaps and updated_fit show current progress.

GET

/api/v1/successors/{identifier}/

Get detailed information about a specific successor

▼

Description

Retrieve detailed information about a specific successor record. The identifier can be the successor's ID, employee's ID, employee_id, or email address.

Authentication

Requires JWT Bearer token in Authorization header

Path Parameters

Parameter	Type	Required	Description
identifier	string	Required	Can be: `successor.id` (integer), `employee.id` (integer), `employee.employee_id` (string), or `employee.email`

Example Request

# By successor ID
curl -X GET "https://api.hrwise.ai/api/v1/successors/1/" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."

# By employee email
curl -X GET "https://api.hrwise.ai/api/v1/successors/jane.smith@company.com/" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
                    

Response

200 OK Success

{
  "success": true,
  "data": {
    "id": 1,
    "employee_name": "Jane Smith",
    "current_position": "Engineer",
    "department": "Engineering",
    "role_to_succeed": "Senior Engineer",
    "expected_readiness": "ready_now",
    "predecessor_name": "John Doe",
    "fit_score_display": "85",
    "initial_gaps": ["Team Leadership"],
    "updated_gaps": [],
    "progress_status": {
      "status": "on_track",
      "predicted_readiness": null
    },
    "initial_fit": "75",
    "updated_fit": "85",
    "employee": 456,
    "notes": "Shows strong leadership potential",
    "current_role_holder": {
      "id": 123,
      "full_name": "John Doe",
      "email": "john.doe@company.com",
      "department": "Engineering",
      "position": "Senior Engineer"
    }
  }
}
                        

Error Responses

404 Not Found Successor not found

{
  "success": false,
  "error": {
    "code": "SUCCESSOR_NOT_FOUND",
    "message": "No active successor found with identifier: 999"
  }
}
                        

Note: If an employee has multiple successor records, the first active one will be returned when searching by employee identifier.

GET

/api/v1/bench-strength/

Get comprehensive bench strength analytics table

▼

Description

Returns a comprehensive bench strength analysis table showing succession metrics for all positions. Includes readiness distribution, internal vs external successor ratios, and bench strength index scores.

Authentication

Requires JWT Bearer token in Authorization header

Query Parameters

Parameter	Type	Required	Description
department	string	Optional	Filter by department name (case-insensitive)

Example Request

curl -X GET "https://api.hrwise.ai/api/v1/bench-strength/?department=Engineering" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..."
                    

Response

200 OK Success

{
  "success": true,
  "data": [
    {
      "role": "Senior Engineer",
      "current_holder": "John Doe",
      "department": "Engineering",
      "total_successors": 3,
      "ready_now_count": 1,
      "less_6_months_count": 1,
      "six_12_months_count": 1,
      "twelve_24_months_count": 0,
      "more_24_months_count": 0,
      "internal_percentage": "67%",
      "external_percentage": "33%",
      "bench_strength_index": 82.5
    },
    {
      "role": "Engineering Manager",
      "current_holder": "Jane Smith",
      "department": "Engineering",
      "total_successors": 2,
      "ready_now_count": 0,
      "less_6_months_count": 1,
      "six_12_months_count": 1,
      "twelve_24_months_count": 0,
      "more_24_months_count": 0,
      "internal_percentage": "100%",
      "external_percentage": "0%",
      "bench_strength_index": 65.8
    }
  ]
}
                        

Response Field Descriptions

Field	Description
role	Position/role title being analyzed
current_holder	Name of the person currently in this role
department	Department name
total_successors	Total number of identified successors for this role
ready_now_count	Number of successors ready immediately
less_6_months_count	Number of successors ready in less than 6 months
six_12_months_count	Number of successors ready in 6-12 months
twelve_24_months_count	Number of successors ready in 12-24 months
more_24_months_count	Number of successors ready in more than 24 months
internal_percentage	Percentage of successors from the same department
external_percentage	Percentage of successors from other departments
bench_strength_index	Overall bench strength score (0-100) based on weighted factors

Interpreting BSI Scores:

80-100: Excellent succession coverage
60-79: Good succession coverage with minor gaps
40-59: Moderate succession coverage, improvement needed
0-39: Weak succession coverage, immediate attention required