Scripts & APIs

Python SDK

Copy page

Get started with the HRMLESS API using our Python SDK with automatic authentication and token management.

Source Code: https://github.com/hrmless/python-sdk

Available Actions and API Docs

type	action	docs url
GET	client.get_org_id	get-org-id
GET	client.get_org_settings	get-org-settings
PUT	client.update_org_settings	update-org-settings
GET	client.get_positions	get-all-positions
GET	client.get_position_by_id	get-position-by-id
POST	client.create_position	create-position
PUT	client.update_postion	update-position-by-id
DELETE	client.delete_position	delete-position-by-id
GET	client.get_candidates	get-candidates
GET	client.get_candidate_by_id	get-candidate-by-id
POST	client.create_candidate	add-candidates
PUT	client.update_candidate	update-candidates
DELETE	client.delete_candidate	delete-candidate-by-id
GET	client.get_interview	get-candidate-interview
PUT	client.update_interview	get-candidate-interview
GET	client.get_token	used if you want to make an API call that is not built into the SDK

Installation

From GitHub (Recommended)

Clone the examples repository and install dependencies:

Code
 
git clone https://github.com/hrmless/python-sdk.git
cd python-sdk
pip install requests

Configuration

Set your credentials as environment variables:

Code
 
# Copy the example environment file
cp examples.env .env

# Edit .env with your credentials
export USERNAME="your_hrmless_username"
export PASSWORD="your_hrmless_password"

# Load the environment
source .env

Quick Start

Basic Usage

Code
 
from modules.hrmless import HRMLess

# Initialize client (authenticates automatically)
client = HRMLess()

# Get your organization ID
org_id = client.get_org_id()

# List all positions
positions = client.get_positions(org_id)

for position in positions:
    print(f"Position: {position['name']}")

That's it! The client handles all authentication and token refresh automatically.

With Credentials

You can also pass credentials directly:

Code
 
from modules.hrmless import HRMLess

client = HRMLess(
    username="your_username",
    password="your_password"
)

Running Examples

The repository includes a comprehensive example script demonstrating all API functionality:

Code
 
# Make sure your credentials are set
source .env

# Run the examples
python examples.py

This will demonstrate:

• ✅ Authentication (automatic)
• ✅ Organization settings management
• ✅ Position CRUD operations
• ✅ Candidate management
• ✅ Interview scheduling and tracking

API Reference

Authentication

The HRMLess client automatically handles authentication:

Code
 
from modules.hrmless import HRMLess, AuthenticationError

try:
    client = HRMLess()
    print(f"Authenticated as: {client.user_id}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")

Features:

• Automatic login on initialization
• Background token refresh (every ~28 minutes)
• Automatic retry on 401 errors
• Thread-safe token management

Organization

Get Organization ID

Code
 
org_id = client.get_org_id()

Get Organization Settings

Code
 
settings = client.get_org_settings(org_id)
print(f"Organization: {settings['organization_name']}")

Update Organization Settings

Code
 
updated = client.update_org_settings(org_id, {
    "organization_name": "New Company Name",
    "contact_email": "[email protected]"
})

Positions

List All Positions

Code
 
positions = client.get_positions(org_id)

for position in positions:
    print(f"{position['name']} - {position['department']}")

Get Position by ID

Code
 
position = client.get_position_by_id(org_id, position_id)
print(f"Position: {position['name']}")
print(f"Description: {position['description']}")

Create Position

Code
 
new_position = client.create_position(org_id, {
    "name": "Senior Software Engineer",
    "description": "Looking for an experienced software engineer...",
    "department": "Engineering",
    "location": "Remote",
    "employment_type": "Full-time",
    "language": "en"
})

position_id = new_position['id']

Update Position

Code
 
updated = client.update_position(org_id, position_id, {
    "status": "active",
    "description": "Updated job description"
})

Delete Position

Code
 
client.delete_position(org_id, position_id)

Candidates

List Candidates for a Position

Code
 
response = client.get_candidates(org_id, position_id)
candidates = response['items']

for candidate in candidates:
    print(f"{candidate['first_name']} {candidate['last_name']} - {candidate['email']}")

Get Candidate by ID

Code
 
candidate = client.get_candidate_by_id(org_id, position_id, candidate_id)
print(f"Candidate: {candidate['first_name']} {candidate['last_name']}")
print(f"Status: {candidate['status']}")

Add Candidate

Code
 
new_candidate = client.create_candidate(org_id, position_id, {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "status": "new"
})

candidate_id = new_candidate['id']

Update Candidate

Code
 
updated = client.update_candidate(
    org_id, 
    position_id, 
    candidate_id, 
    {
        "status": "screening",
        "notes": "Completed phone screen"
    },
    pop_null=True  # Remove None values
)

Delete Candidate

Code
 
client.delete_candidate(org_id, position_id, candidate_id)

Interviews

Get Interview Details

Code
 
interview = client.get_interview(org_id, position_id, candidate_id)

print(f"Interview link: {interview['interview_link']}")
print(f"Status: {interview['status']}")

Update Interview

Code
 
updated = client.update_interview(
    org_id,
    position_id,
    candidate_id,
    {
        "status": "scheduled",
        "scheduled_time": "2025-11-20T10:00:00Z",
        "notes": "Technical interview"
    }
)

Complete Workflow Example

Here's a complete hiring workflow from creating a position to scheduling an interview:

Code
 
from modules.hrmless import HRMLess, APIError

try:
    # Initialize client
    client = HRMLess()
    org_id = client.get_org_id()
    
    # 1. Create a position
    position = client.create_position(org_id, {
        "name": "Full Stack Developer",
        "description": "We're looking for a talented full stack developer...",
        "department": "Engineering",
        "location": "Remote",
        "employment_type": "Full-time",
        "language": "en"
    })
    print(f"✓ Created position: {position['name']}")
    
    # 2. Add a candidate
    candidate = client.create_candidate(org_id, position['id'], {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone": "+1234567890"
    })
    print(f"✓ Added candidate: {candidate['first_name']} {candidate['last_name']}")
    
    # 3. Get interview link
    interview = client.get_interview(org_id, position['id'], candidate['id'])
    print(f"✓ Interview link: {interview['interview_link']}")
    
    # 4. Update candidate status
    client.update_candidate(org_id, position['id'], candidate['id'], {
        "status": "interview_sent"
    })
    print("✓ Candidate status updated")
    
    print("\n🎉 Hiring workflow complete!")
    
except APIError as e:
    print(f"Error: {e}")
    print(f"Status code: {e.status_code}")

Error Handling

The client uses exceptions for error handling:

Code
 
from modules.hrmless import HRMLess, APIError, AuthenticationError

try:
    client = HRMLess()
    positions = client.get_positions(org_id)
    
except AuthenticationError as e:
    # Authentication failed (invalid credentials)
    print(f"Authentication failed: {e}")
    
except APIError as e:
    # API request failed
    print(f"API error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Response: {e.response}")
    
except Exception as e:
    # Unexpected error
    print(f"Unexpected error: {e}")

Common Error Codes

Code	Meaning	Handling
401	Unauthorized	Automatically retried with token refresh
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
422	Validation Error	Check request data
500	Server Error	Retry later

Advanced Usage

Context Manager

Use the client as a context manager for automatic cleanup:

Code
 
from modules.hrmless import HRMLess

with HRMLess() as client:
    org_id = client.get_org_id()
    positions = client.get_positions(org_id)
    # Cleanup happens automatically

Bulk Import Candidates

Import candidates from a CSV file:

Code
 
import csv
from modules.hrmless import HRMLess

client = HRMLess()
org_id = client.get_org_id()
position_id = "your-position-id"

with open('candidates.csv', 'r') as f:
    reader = csv.DictReader(f)
    for row in reader:
        try:
            candidate = client.create_candidate(org_id, position_id, {
                "first_name": row['first_name'],
                "last_name": row['last_name'],
                "email": row['email'],
                "phone": row['phone']
            })
            print(f"✓ Added: {candidate['first_name']} {candidate['last_name']}")
        except Exception as e:
            print(f"✗ Failed to add {row['email']}: {e}")

Custom Configuration

Configure the client with custom URLs or settings:

Code
 
client = HRMLess(
    username="your_username",
    password="your_password",
    api_url="https://api-nervai.hrmless.com/api/v1",
    oidc_url="https://login.hrmless.com",
    auto_retry=True  # Automatically retry on 401
)

Enable Debugging

Enable logging to see what's happening:

Code
 
import logging

# Enable debug logging
logging.basicConfig(level=logging.INFO)

from modules.hrmless import HRMLess

client = HRMLess()
# You'll see authentication and API request logs

Best Practices

1. Initialize Once, Reuse Everywhere

Code
 
# ✅ Good - Initialize once
client = HRMLess()

positions = client.get_positions(org_id)
candidates = client.get_candidates(org_id, position_id)

# ❌ Bad - Don't create multiple clients
for position in positions:
    client = HRMLess()  # Wasteful!
    candidates = client.get_candidates(org_id, position['id'])

2. Use Context Managers

Code
 
# ✅ Good - Automatic cleanup
with HRMLess() as client:
    data = client.get_positions(org_id)
    
# ❌ Okay but manual
client = HRMLess()
data = client.get_positions(org_id)
# Remember to cleanup if needed

3. Handle Errors Gracefully

Code
 
# ✅ Good - Specific error handling
try:
    position = client.create_position(org_id, data)
except APIError as e:
    if e.status_code == 422:
        print("Validation error: check your data")
    else:
        print(f"API error: {e}")

# ❌ Bad - Too broad
try:
    position = client.create_position(org_id, data)
except:
    print("Something went wrong")

4. Validate Data Before Sending

Code
 
# ✅ Good - Validate first
def create_candidate_safely(client, org_id, position_id, data):
    required_fields = ['first_name', 'last_name', 'email']
    
    for field in required_fields:
        if not data.get(field):
            raise ValueError(f"Missing required field: {field}")
    
    return client.create_candidate(org_id, position_id, data)

Repository Structure

Code
 
public-examples/
├── modules/
│   └── hrmless.py          # Unified API client
├── examples.py             # Comprehensive examples
├── test_client.py          # Quick test script
├── README.md               # Full documentation
├── MIGRATION.md            # Migration guide
└── examples.env            # Environment template

Next Steps

• 📚 Full API Reference - Complete API documentation
• 💬 Support - Get help from our team
• 🐛 Report Issues - Found a bug?

Support

Having trouble? We're here to help!

• Email: [email protected]
• Documentation: https://docs.hrmless.com
• Repository: https://github.com/hrmless/public-examples