Skip to main content

Creating or Updating Candidates via API in PyjamaHR: The Complete Integration Guide

Updated over 3 weeks ago

Executive Summary

PyjamaHR’s API enables you to automatically create or update candidate profiles directly from your custom career page or external systems, streamlining your hiring pipeline and eliminating manual data entry. This guide covers everything you need to know to set up, optimize, and troubleshoot candidate creation and updates via API, ensuring seamless integration with your existing workflows and maximum control over your candidate database.

Detailed Overview

What Is the Candidate API and Why Use It?

The PyjamaHR Candidate API allows your development team to programmatically add or update candidate profiles in your ATS. This is especially valuable for organizations that want to:

  • Automate resume flow from their own career page or third-party forms into PyjamaHR.

  • Maintain a custom-designed career page while ensuring all applications are captured in the ATS.

  • Reduce manual imports (e.g., CSV uploads) and avoid data silos.

  • Map candidates to specific jobs for accurate tracking and reporting.

Key Business Benefits:
- Centralizes all candidate data in PyjamaHR, regardless of the source.
- Enables full customization of your career page and application forms.
- Supports advanced workflows, such as assigning candidates to jobs or the Talent Pool.

How Does It Integrate with Other PyjamaHR Features?

  • Job Mapping: Candidates can be linked to specific jobs using job IDs.

  • Talent Pool: Candidates can be added to the general pool if not mapped to a job.

  • Source Tracking: You can specify the source for each candidate, enabling reporting and filtering.

  • User Access: Only users with the correct permissions (not external recruiters) can create jobs; candidate creation via API is open to authorized integrations.

Step-by-Step Guide: Creating or Updating Candidates via API

Prerequisites

  • API Access Token: Obtain from PyjamaHR support or your admin (see Postman documentation link).

  • Developer Resources: Share the API documentation and token with your developer.

  • Job IDs: If mapping candidates to specific jobs, ensure you have the correct job IDs from PyjamaHR.

1. Obtain API Documentation and Token

  • Contact PyjamaHR Support or your account manager for the latest API documentation and a secure access token.

  • Example token (for illustration): df11ced0b351e72016eb9625b0946cc267e4f2ae

  • API Documentation Link

Screenshot callout: Show where to find/generate the API token in the PyjamaHR admin panel (if available).

2. Review the Candidate Creation/Update Endpoint

  • The API provides endpoints for creating and updating candidates.

  • Required fields typically include: name, email, phone, resume (file or link), and optionally, job_id, source, etc.

  • Optional fields: industry, department (these can be left null if not used).

Screenshot callout: Example API request body from the documentation.

3. Build Your Integration

  • POST /candidates: To create a new candidate.

  • PUT /candidates/{id}: To update an existing candidate.

  • Include all relevant candidate data in the request body.

  • To map a candidate to a job, include the job_id field.

  • To add to the Talent Pool, omit the job_id.

Example Use Case:
- A candidate applies on your custom career page.
- Your backend collects the form data and resume.
- Your system sends a POST request to the PyjamaHR API with the candidate details and the relevant job_id.

4. Test the Integration

  • Use Postman or a similar tool to test candidate creation and updates.

  • Check that candidates appear in the correct job pipeline or Talent Pool in PyjamaHR.

  • Verify all fields (including optional ones) are mapped correctly.

Screenshot callout: Candidate profile in PyjamaHR after successful API submission.

5. Go Live

  • Deploy your integration to production.

  • Monitor for errors and confirm that all candidates are being captured as expected.

Advanced Usage & Best Practices

Power User Tips

  • Custom Source Tracking: Always set the source field to distinguish between API, career page, or manual entries. This enables easy filtering and reporting.

  • Bulk Imports: For large volumes, consider batching API requests or using CSV import as a fallback.

  • Error Handling: Implement robust error handling to capture and log API failures (e.g., invalid data, missing fields).

Optimization Strategies

  • Maintain Your Career Page Design: Use the API to keep your existing career page UI, while still capturing all applications in PyjamaHR.

  • Job Mapping: Always use the correct job_id to ensure candidates are routed to the right job pipeline.

  • Field Validation: Validate all required fields before sending data to the API to avoid failed submissions.

Do’s and Don’ts

Do:
- Share the API documentation and token only with trusted developers.
- Test thoroughly in a staging environment before going live.
- Use the API for all external candidate sources to centralize your data.

Don’t:
- Don’t expose your API token publicly.
- Don’t rely on manual CSV imports if automation is possible.
- Don’t assign job creation to external recruiters (they can only be assigned to jobs, not create them).

Troubleshooting & Common Issues

Common Issues and Solutions

1. Candidates Not Appearing in PyjamaHR
- Check: Is the API request returning a success response?
- Solution: Verify the API token, endpoint URL, and required fields.

2. Industry or Department Fields Are Null
- Explanation: These fields are optional. If not specified, they will be null.
- Solution: No action needed unless your workflow requires these fields.

3. Candidates Not Mapped to Jobs
- Check: Was the correct job_id included in the API request?
- Solution: Retrieve the correct job ID from PyjamaHR and include it in your API call.

4. API Authentication Errors
- Check: Is the access token valid and not expired?
- Solution: Request a new token from PyjamaHR support if needed.

5. Large Resume Files Fail to Upload
- Check: Is the file size within API limits?
- Solution: Convert large resumes to .txt or compress before uploading.

6. External Recruiters Unable to Create Jobs
- Explanation: Only admins or users with the right permissions can create jobs. External recruiters can only be assigned to jobs.

What If Scenarios

  • What if I want to update an existing candidate?

  • Use the PUT endpoint with the candidate’s unique ID.

  • What if I want to add candidates to the Talent Pool only?

  • Omit the job_id field in your API request.

When to Contact Support

  • Persistent API errors not resolved by documentation.

  • Issues with API token generation or permissions.

  • Unexpected data mapping or missing candidates.

Comprehensive FAQ

  1. Can I use the API to add candidates from my own career page?
    - Yes, this is the primary use case for the Candidate API.

  2. Do I have to use the PyjamaHR career page or iframe?
    - No, you can maintain your own design and use the API to send candidates to PyjamaHR.

  3. Can I map candidates to specific jobs?
    - Yes, include the job_id in your API request.

  4. What if I don’t want to map candidates to a job?
    - Candidates will be added to the Talent Pool.

  5. Are industry and department fields required?
    - No, they are optional and can be left null.

  6. Can external recruiters create jobs via API?
    - No, only authorized users can create jobs; external recruiters can only be assigned to jobs.

  7. How do I track which recruiter added a candidate?
    - Use the source field and check the candidate’s timeline in PyjamaHR.

  8. What happens if I upload a large resume file?
    - Large files may fail; convert to .txt or compress before uploading.

  9. Can I import candidates via CSV instead of API?
    - Yes, but API integration is recommended for automation.

  10. Can I push job postings from my career page to PyjamaHR?

    • No, jobs must be created in PyjamaHR first, then mapped to your career page.

  11. Can I use a unique email address for each job post to receive candidates?

    • No, this is not supported.

  12. How do I get my API token?

    • Contact PyjamaHR support or your admin.

  13. How do I troubleshoot missing candidates?

    • Check API logs, validate required fields, and confirm job IDs.

  14. Can I customize the candidate fields sent via API?

    • Yes, as per the API documentation.

  15. How do I ensure all candidates are tracked efficiently?

    • Always use the correct job mapping and source tracking in your API calls.

Related Features & Next Steps

  • Job API: For posting and managing jobs in PyjamaHR.

  • Talent Pool Management: For handling unassigned candidates.

  • User Access Management: Ensure correct permissions for API integrations.

  • Career Page Integration: Use iframe or API as per your design needs.

Recommended Articles:
- Career Page Integration
- Understanding Access Types
- Managing the Talent Pool

Still have questions?
If you encounter issues not covered here, contact PyjamaHR Support with your API request details and error logs for prompt assistance.

This article is based on real customer scenarios and is updated regularly to reflect the latest best practices and platform capabilities.

Did this answer your question?