Skip to main content

How to Test PyjamaHR API Calls Using Postman or cURL: Step-by-Step Guide for Career Page Integration

Updated over 3 weeks ago

Executive Summary

PyjamaHR provides a Career Page API that enables you to integrate your custom careers page with the PyjamaHR ATS, allowing seamless job listing display and candidate application flow. Testing API calls using tools like Postman or cURL is essential for developers to validate integration, troubleshoot issues, and ensure a smooth candidate experience. This article provides a comprehensive, actionable guide to testing PyjamaHR API endpoints, with real-world examples, best practices, and troubleshooting tips based on actual customer scenarios.

Detailed Overview

What is the PyjamaHR Career Page API?

The PyjamaHR Career Page API allows organizations to:
- Fetch job listings from PyjamaHR and display them on their own branded careers page.
- Forward candidate applications from their custom website forms directly into PyjamaHR, ensuring all applications are tracked centrally.

Why use the API?
- Maintain full control over your careers page design and user experience.
- Automate the flow of candidate data into PyjamaHR without manual intervention.
- Ensure accurate mapping between jobs and applications.

When to use it?
- When you cannot or do not want to use the default PyjamaHR iframe or hosted careers page.
- When you need to match your careers page to your company’s branding and UX.
- When you want to automate candidate data entry into PyjamaHR from your own forms.

Integration with Other PyjamaHR Features:
- Jobs posted in PyjamaHR can be fetched and displayed on your site.
- Applications submitted via your site can be pushed into PyjamaHR for tracking, review, and workflow management.

Business Impact:
- Streamlines recruitment operations.
- Reduces manual data entry and errors.
- Enhances candidate experience and employer branding.

Comprehensive Step-by-Step Guide

Prerequisites

  • API Documentation Link: PyjamaHR Career Page API Documentation

  • API Token: Provided by PyjamaHR support (example: df11ced0b351e72016eb9625b0946cc267e4f2ae)

  • Postman (download from getpostman.com) or cURL (available in most Unix-based systems or via curl.se)

  • Developer access to your careers page or website

1. Obtain Your API Token

  • Contact PyjamaHR support to receive your unique API token.

  • Example from customer conversations:
    ​ Token- df11ced0b351e72016eb9625b0946cc267e4f2ae

2. Review the API Documentation

3. Testing with Postman

a. Import the API Collection

  • Click "Run in Postman" or import the API documentation link into Postman.

b. Set Up Authorization

  • Go to the "Authorization" tab for each request.

  • Select "Bearer Token" and paste your API token.

c. Fetch Job Listings (GET)

  1. Select the "Get Jobs" endpoint.

  2. Ensure the method is set to GET.

  3. Set the Authorization header:
    - Key: Authorization
    - Value: Bearer <your_token>

  4. Click "Send".

  5. Screenshot Callout:
    ​ Screenshot of Postman with the GET request, Authorization header, and response preview.

d. Submit a Candidate Application (POST)

  1. Select the "Post Application" endpoint.

  2. Set the method to POST.

  3. In the "Body" tab, select "raw" and "JSON".

  4. Enter the required fields (refer to API docs for exact schema).
    - Example:
    ​ json { "job_id": "123456", "candidate_name": "Jane Doe", "email": "[email protected]", "resume_url": "https://yourdomain.com/resume/jane.pdf" }

  5. Set the Authorization header as above.

  6. Click "Send".

  7. Screenshot Callout:
    ​ Screenshot of Postman with the POST request, JSON body, Authorization header, and response.

4. Testing with cURL

a. Fetch Job Listings

curl -X GET "https://api.pyjamahr.com/careers/jobs" \
  -H "Authorization: Bearer <your_token>"

b. Submit a Candidate Application

curl -X POST "https://api.pyjamahr.com/careers/applications" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "123456",
    "candidate_name": "Jane Doe",
    "email": "[email protected]",
    "resume_url": "https://yourdomain.com/resume/jane.pdf"
  }'

c. Interpreting Responses

  • Success: HTTP 200/201 with a JSON response confirming the action.

  • Error: HTTP 4xx/5xx with an error message (see Troubleshooting below).

5. Map Jobs and Applications

  • Ensure the job_id used in application submissions matches the IDs fetched from the "Get Jobs" endpoint.

  • This ensures applications are correctly mapped to the right job in PyjamaHR.

Advanced Usage & Best Practices

Power User Tips

  • Automate Testing: Use Postman Collections with environments to test multiple tokens or endpoints.

  • Version Control: Save your Postman collections and cURL scripts in your code repository for team use.

  • Security: Never expose your API token in public repositories or client-side code.

Optimization Strategies

  • Cache Job Listings: Reduce API calls by caching job data and refreshing periodically.

  • Validate Inputs: Ensure all required fields are present and correctly formatted before submitting applications.

  • Error Logging: Log API responses and errors for debugging and support.

Integration with Other Tools

  • CI/CD Pipelines: Integrate cURL scripts in your deployment workflows to automate testing.

  • Webhooks: If available, use PyjamaHR webhooks for real-time updates (check with support).

Do’s and Don’ts

Do:
- Use the official API documentation for endpoint details.
- Test all endpoints in a staging environment before going live.
- Keep your API token secure.

Don’t:
- Don’t attempt to create jobs in PyjamaHR via API if not supported (see FAQ).
- Don’t hardcode sensitive data in your codebase.

Troubleshooting & Common Issues

Common Error Messages & Solutions

Error Message/Status

Likely Cause

Solution

401 Unauthorized

Invalid or missing token

Double-check your API token and Authorization header.

400 Bad Request

Missing/invalid fields

Ensure all required fields are present and correctly formatted.

404 Not Found

Wrong endpoint or job_id

Verify endpoint URLs and job IDs.

500 Internal Server Error

Server issue

Retry after some time or contact support.

What If Scenarios

  • What if my API token doesn’t work?
    Contact PyjamaHR support for a new token.

  • What if applications aren’t showing up in PyjamaHR?
    Ensure the job_id is valid and matches an active job in your PyjamaHR account.

  • What if I want to create jobs via API?
    As per current capabilities, only fetching jobs and submitting applications are supported.

Recovery Procedures

  • Regenerate your API token if you suspect it’s compromised.

  • Re-test endpoints using Postman or cURL after any changes.

When to Contact Support

  • Persistent 401/403 errors despite correct token.

  • API documentation is unclear or endpoints are missing.

  • Applications are not appearing in PyjamaHR after successful API calls.

Comprehensive FAQ

1. How do I get access to the PyjamaHR API?
Contact PyjamaHR support to receive your API token and documentation link.

2. Can I use the API to create jobs in PyjamaHR?
No, currently you can only fetch jobs and submit applications. Creating jobs via API is not supported.

3. How do I map applications to the correct job?
Use the job_id from the "Get Jobs" endpoint in your application submissions.

4. What authentication method is used?
Bearer Token in the Authorization header.

5. Can I use the API to customize the look of my careers page?
Yes, by fetching jobs and displaying them on your own site, you have full design control.

6. What if I want to keep my existing careers page design?
Use the API to fetch jobs and submit applications without changing your page layout.

7. Can I embed PyjamaHR’s form directly?
Alternatively, you can use the iframe code, but the API is for full customization.

8. What if my API calls are failing?
Check your token, endpoint URLs, and request body. See Troubleshooting above.

9. How do I test API calls before going live?
Use Postman or cURL as described in this article.

10. Can I use the same token for multiple environments?
Check with PyjamaHR support; tokens may be environment-specific.

11. How do I keep my API token secure?
Store it in environment variables or secure vaults; never expose it in client-side code.

12. What if I need to automate resume uploads?
Include a resume_url or file field as per API documentation.

13. How do I handle API version changes?
Monitor the API documentation for updates and adjust your integration accordingly.

Related Features & Next Steps

  • Career Page Integration: Use the API or iframe for different levels of customization.

  • Job Publishing: Manage job visibility via PyjamaHR’s job publishing settings.

  • Candidate Management: All applications submitted via API appear in your PyjamaHR dashboard for further processing.

  • LinkedIn Integration: Control where the Apply button redirects (PyjamaHR careers page or your own).

Recommended Next Steps:
- Review the PyjamaHR Career Page API Documentation.
- Request your API token from support if you haven’t already.
- Set up and test API calls using Postman or cURL as described.
- Explore additional help articles:
- How to Integrate Your Careers Page with PyjamaHR
- Managing Job Visibility and Application Sources
- Troubleshooting API Integrations

Still have questions?
Contact PyjamaHR support with your API token and request details for personalized assistance.

This article is based on real customer scenarios and workflows. If you follow these steps, you’ll be able to confidently test and integrate PyjamaHR’s Career Page API using Postman or cURL, ensuring a seamless candidate experience and streamlined hiring process.

Did this answer your question?