Executive Summary
The PyjamaHR public REST API enables organizations to seamlessly integrate their own career pages and websites with PyjamaHR’s applicant tracking system. With this API, you can fetch job listings, display them on your custom career page, and ensure that candidate applications flow directly into PyjamaHR—streamlining your recruitment process and maintaining your brand’s unique look and feel.
Detailed Overview
What Is the PyjamaHR Public REST API?
The PyjamaHR public REST API is a set of endpoints that allow you to programmatically access job data from your PyjamaHR account. The primary use case is to fetch job listings and display them on your own website or career page, giving you full control over the design and user experience. This API is especially valuable for organizations that want to:
Maintain a fully branded career page without using PyjamaHR’s default iframe or widget.
Automate the flow of job postings from PyjamaHR to their website.
Receive candidate applications directly into PyjamaHR while keeping their own application forms and page layouts.
Key Benefits:
- Full control over your career page’s appearance and behavior.
- Real-time synchronization of job openings.
- Seamless candidate data flow into PyjamaHR.
- No need to rely on iframes or embedded widgets if you prefer a custom solution.
When and Why to Use the API
You want to display jobs on your own website and style them with custom CSS.
You need to automate job listing updates without manual copy-paste.
You want to keep your application process on your own site but still leverage PyjamaHR for candidate management.
You require integration with other tools or workflows (e.g., n8n, Zapier) for advanced automation.
Integration with Other PyjamaHR Features
Careers Page: The API is an alternative to the default PyjamaHR careers page or iframe. Use it if you want more control.
Candidate Management: Applications submitted via your custom page can be routed into PyjamaHR for tracking and workflow management.
Job Publishing: Jobs created in PyjamaHR can be fetched and displayed anywhere via the API.
Step-by-Step Guide: Using the PyjamaHR Public REST API
Prerequisites
API Access: Available only on custom/enterprise plans. Contact support if you’re unsure about your eligibility.
API Token: Required for authentication. Provided by PyjamaHR support or your account manager.
Developer Resources: You’ll need a developer to implement the API integration on your website.
1. Obtain Your API Token
Contact PyjamaHR support or your account manager.
Example token format:
81ee3eba0ddabf93b7cf91727ee929db4194fa44
Security Note: Keep your API token confidential.
2. Access the API Documentation
Official documentation: PyjamaHR API Docs (Postman)
Review available endpoints, parameters, and response formats.
3. Fetch Job Listings
Endpoint:
GET /public/jobs
Headers: Include your API token as specified in the documentation.
Example Request:
http GET https://api.pyjamahr.com/public/jobs Authorization: Bearer <your-token>
Response: JSON array of job objects with details like title, location, description, and application URL.
4. Display Jobs on Your Website
Parse the API response and render job listings using your preferred frontend framework (React, Vue, plain HTML, etc.).
Custom Styling: Apply your own CSS for full branding control.
Screenshot Suggestion: Show a before/after of a default PyjamaHR careers page vs. a custom-styled page using the API.
5. Handle Candidate Applications
Default Flow: The API provides job data and application URLs that direct candidates to PyjamaHR’s application form.
Custom Flow: If you want to use your own application form, discuss with PyjamaHR support—posting candidate data via API is not generally available as per current documentation and conversations.
6. Keep Job Listings Updated
Schedule regular API calls (e.g., every hour) to sync new, updated, or closed jobs.
Remove jobs from your site when they’re no longer open in PyjamaHR.
7. Advanced: Integrate with Automation Tools
Use tools like n8n or Zapier to trigger workflows when new jobs are posted or updated.
Example: Send a Slack notification when a new job is published.
Advanced Usage & Best Practices
Power User Tips
Cache API Responses: To reduce load and improve performance, cache job data and refresh at intervals.
Error Handling: Implement robust error handling for failed API calls (e.g., fallback messages, retry logic).
Security: Never expose your API token in client-side code. Always proxy API requests through your backend.
Optimization Strategies
Custom Filtering: Use API parameters to filter jobs by location, department, or status before displaying.
SEO Optimization: Render job listings server-side for better search engine indexing.
Accessibility: Ensure your custom job listings are accessible (ARIA labels, keyboard navigation).
Integration with Other Tools
Website Builders: Integrate with WordPress, Webflow, or custom CMS using server-side scripts.
Analytics: Track job views and application clicks using Google Analytics or similar tools.
Do’s and Don’ts
Do:
- Use the API for fetching jobs and displaying them with your own design.
- Keep your API token secure.
- Contact support for advanced use cases or if you need to post candidate data.
Don’t:
- Attempt to POST jobs or candidates unless explicitly enabled in your plan (most plans only support fetching jobs).
- Expose your API token in frontend JavaScript.
- Expect to download all candidate data or resumes via the public API (not supported as of now).
Troubleshooting & Common Issues
Common Error Messages & Solutions
CORS Errors:
Issue: “CORS Error” when calling the API from frontend code.
Solution: Always make API calls from your backend server, not directly from the browser. If you must call from the frontend, request PyjamaHR support to whitelist your domain (may not be available for all plans).
Invalid Token:
Issue: “Unauthorized” or “Invalid token” error.
Solution: Double-check your API token and ensure it’s included in the request headers.
No Jobs Returned:
Issue: API returns an empty list.
Solution: Ensure you have open jobs in PyjamaHR. Only published jobs are returned.
API Not Available:
Issue: “Currently, we do not have APIs available for users.”
Solution: API access is only available on certain plans (typically custom/enterprise). Contact support to upgrade or enable access.
What If Scenarios
What if I want to POST jobs or candidates via API?
This is only available on custom plans. Most customers can only fetch jobs. Contact your account manager for upgrade options.
What if I need to download all candidate data or resumes?
This is not supported via the public API. You can only download resumes individually from the Talent Pool in the PyjamaHR UI.
What if my API integration breaks after a PyjamaHR update?
Check the API documentation for changes. Contact support if endpoints or responses have changed.
When to Contact Support
You need your API token or documentation link.
You want to enable POST endpoints (jobs or candidates).
You encounter persistent errors not covered above.
You need your domain whitelisted for CORS.
Comprehensive FAQ
1. Who can access the PyjamaHR public REST API?
API access is available only to customers on custom or enterprise plans. Contact support to check your eligibility.
2. What endpoints are available?
The main public endpoint is for fetching job listings. POST endpoints (for jobs or candidates) are only available on select plans.
3. Where do I find the API documentation?
PyjamaHR API Docs (Postman)
4. How do I get my API token?
Contact PyjamaHR support or your account manager.
5. Can I use the API to post jobs or candidates?
Not by default. This is only enabled for custom/enterprise plans.
6. Can I download all candidate data or resumes via API?
No, this is not supported. You can only download resumes individually from the Talent Pool UI.
7. How do I avoid CORS errors?
Make API calls from your backend server, not directly from the browser. If you need frontend access, request domain whitelisting (not always available).
8. Can I customize the look of my job listings?
Yes! That’s the main benefit of using the API—you have full control over the design and CSS.
9. How often should I sync job listings?
Best practice is to fetch jobs every hour or whenever your site is updated.
10. What if I want to automate workflows (e.g., with n8n or Zapier)?
You can use the API with these tools to trigger actions when new jobs are posted.
11. Can I use the API to fetch invoices, download all candidates, or access other data?
No, the public API is limited to job listings. Other data is not available via API at this time.
12. What if my API token is compromised?
Contact PyjamaHR support immediately to revoke and reissue your token.
Related Features & Next Steps
Related PyjamaHR Features:
- Careers Page Integration (iframe)
- Talent Pool (for managing candidates)
- LinkedIn and job board integrations
Recommended Next Steps:
- Review your current plan and upgrade if you need broader API access.
- Work with your developer to implement the API following the official documentation.
- Set up regular syncs and error monitoring for your integration.
- Explore automation tools for advanced workflows.
Helpful Links:
- PyjamaHR API Documentation
- Contact PyjamaHR Support
- Careers Page Integration Guide
Summary Table: What You Can and Cannot Do with the PyjamaHR Public REST API
Action | Supported? | Notes |
Fetch job listings | Yes | Main use case; fully supported on eligible plans |
Display jobs on your own website | Yes | Full control over design and layout |
Post jobs via API | Limited | Only on custom/enterprise plans; contact support |
Submit candidate applications via API | Limited | Only on custom/enterprise plans; contact support |
Download all candidate data/resumes | No | Not supported via API; use Talent Pool UI for individual downloads |
Fetch invoices or other data | No | Not supported via API |
Avoid CORS errors | Yes | Use backend server or request domain whitelisting |
Still have questions?
Contact PyjamaHR support for personalized assistance or to request additional API capabilities for your organization.