Comprehensive guide to the PihuPulse API for developers
The PihuPulse API allows you to programmatically access and manage your recruitment data, automate screening processes, and integrate with your existing tools and workflows. Our RESTful API uses standard HTTP methods and returns JSON responses.
The base URL for all API requests is:
https://api.pihupulse.com/v1
This documentation covers the latest version (v1) of the PihuPulse API. If you're using an older version, some features may not be available or may work differently.
All API requests must be authenticated using an API key. You can generate an API key from your PihuPulse dashboard under Settings → API.
Include your API key in the request headers:
Authorization: Bearer YOUR_API_KEY
Keep your API key secure and never expose it in client-side code. If you believe your API key has been compromised, you should immediately regenerate it from your dashboard.
curl -X GET "https://api.pihupulse.com/v1/candidates" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
To ensure the stability of our service, the PihuPulse API implements rate limiting. The limits vary based on your subscription plan:
| Plan | Rate Limit | Burst Limit |
|---|---|---|
| Starter | 100 requests/minute | 150 requests |
| Professional | 300 requests/minute | 450 requests |
| Enterprise | 1000 requests/minute | 1500 requests |
When you exceed your rate limit, the API will return a 429 Too Many Requests response. The response headers include information about your current rate limit status:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1620000000
The PihuPulse API uses conventional HTTP response codes to indicate the success or failure of an API request:
Error responses include a JSON object with details about what went wrong:
{
"error": {
"code": "invalid_request",
"message": "The candidate ID is invalid or not found",
"status": 404,
"details": {
"candidate_id": "c12345"
}
}
}| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or missing required parameters |
| 401 | unauthorized | Authentication failed or API key is missing |
| 403 | forbidden | You don't have permission to access this resource |
| 404 | not_found | The requested resource doesn't exist |
| 429 | rate_limited | You've exceeded your rate limit |
Returns a paginated list of candidates in your account.
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number (default: 1) |
| limit | integer | Number of results per page (default: 20, max: 100) |
| status | string | Filter by status (active, archived, all) |
{
"data": [
{
"id": "c12345",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"status": "active",
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T10:30:00Z"
},
{
"id": "c12346",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"phone": "+1987654321",
"status": "active",
"created_at": "2023-01-16T14:20:00Z",
"updated_at": "2023-01-16T14:20:00Z"
}
],
"meta": {
"current_page": 1,
"total_pages": 5,
"total_count": 98,
"per_page": 20
}
}Returns detailed information about a specific candidate.
{
"data": {
"id": "c12345",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"status": "active",
"resume_url": "https://storage.pihupulse.com/resumes/c12345.pdf",
"skills": ["JavaScript", "React", "Node.js"],
"experience_years": 5,
"education": [
{
"institution": "University of Technology",
"degree": "Bachelor of Computer Science",
"year": 2018
}
],
"screenings": [
{
"id": "s67890",
"status": "completed",
"score": 85,
"completed_at": "2023-01-20T15:45:00Z"
}
],
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-20T15:45:00Z"
}
}Creates a new candidate in your account.
{
"name": "Alex Johnson",
"email": "alex.johnson@example.com",
"phone": "+1122334455",
"resume_url": "https://example.com/resumes/alex_johnson.pdf"
}{
"data": {
"id": "c12347",
"name": "Alex Johnson",
"email": "alex.johnson@example.com",
"phone": "+1122334455",
"status": "active",
"resume_url": "https://storage.pihupulse.com/resumes/c12347.pdf",
"created_at "active",
"resume_url": "https://storage.pihupulse.com/resumes/c12347.pdf",
"created_at": "2023-01-22T09:15:00Z",
"updated_at": "2023-01-22T09:15:00Z"
}
}Returns a paginated list of screenings in your account.
{
"data": [
{
"id": "s67890",
"candidate_id": "c12345",
"template_id": "t54321",
"status": "completed",
"score": 85,
"started_at": "2023-01-20T15:00:00Z",
"completed_at": "2023-01-20T15:45:00Z"
},
{
"id": "s67891",
"candidate_id": "c12346",
"template_id": "t54321",
"status": "pending",
"score": null,
"started_at": null,
"completed_at": null
}
],
"meta": {
"current_page": 1,
"total_pages": 3,
"total_count": 42,
"per_page": 20
}
}Creates a new screening for a candidate.
{
"candidate_id": "c12347",
"template_id": "t54321",
"job_title": "Senior Frontend Developer",
"send_invitation": true
}Returns a list of screening templates in your account.
{
"data": [
{
"id": "t54321",
"name": "Frontend Developer",
"description": "Screening for frontend development skills",
"duration_minutes": 30,
"question_count": 15,
"created_at": "2022-12-10T08:30:00Z",
"updated_at": "2023-01-05T14:20:00Z"
},
{
"id": "t54322",
"name": "Backend Developer",
"description": "Screening for backend development skills",
"duration_minutes": 45,
"question_count": 20,
"created_at": "2022-12-15T10:45:00Z",
"updated_at": "2023-01-10T16:30:00Z"
}
]
}Returns a detailed report for a completed screening.
{
"data": {
"screening_id": "s67890",
"candidate_id": "c12345",
"candidate_name": "John Doe",
"template_id": "t54321",
"template_name": "Frontend Developer",
"score": 85,
"completion_time_minutes": 38,
"completed_at": "2023-01-20T15:45:00Z",
"skill_scores": [
{
"skill": "JavaScript",
"score": 90,
"max_score": 100
},
{
"skill": "React",
"score": 85,
"max_score": 100
},
{
"skill": "CSS",
"score": 80,
"max_score": 100
}
],
"summary": "John demonstrated strong JavaScript and React skills. His CSS knowledge is good but could be improved. Overall, he shows a solid understanding of frontend development concepts.",
"strengths": [
"Problem-solving approach",
"Code organization",
"React component architecture"
],
"areas_for_improvement": [
"CSS animations",
"Responsive design patterns"
],
"recommendation": "Recommended for next interview stage"
}
}To make integration easier, we provide official client libraries for several popular programming languages:
Our JavaScript SDK works in both Node.js and browser environments.
Our Ruby gem makes integration with Ruby applications seamless.
Our PHP library supports PHP 7.4 and above.
Can't find an SDK for your preferred language? Our API follows RESTful principles and can be used with any HTTP client. Check out our community libraries or contact us for support.
Webhooks allow you to receive real-time notifications when events occur in your PihuPulse account. You can configure webhooks in your dashboard under Settings → Webhooks.
| Event | Description |
|---|---|
| candidate.created | Triggered when a new candidate is created |
| screening.created | Triggered when a new screening is created |
| screening.started | Triggered when a candidate starts a screening |
| screening.completed | Triggered when a screening is completed |
| report.generated | Triggered when a screening report is generated |
Each webhook includes a JSON payload with information about the event:
{
"event": "screening.completed",
"created_at": "2023-01-20T15:45:00Z",
"data": {
"screening_id": "s67890",
"candidate_id": "c12345",
"template_id": "t54321",
"score": 85,
"completed_at": "2023-01-20T15:45:00Z"
}
}To verify that a webhook came from PihuPulse, we include a signature in the X-PihuPulse-Signature header. You should validate this signature before processing the webhook.
// Node.js example
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret);
const calculatedSignature = hmac.update(payload).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(calculatedSignature, 'hex'),
Buffer.from(signature, 'hex')
);
}