Public API Documentation

Access our public APIs to integrate job listings, company information, and job applications into your platform.

Base URL

https://api.hatchbeacon.com/api/v1

All API endpoints are relative to this base URL. Replace https://api.hatchbeacon.com with your actual backend server URL.

API Version: v1 - This is the current stable version of our public API.

Authentication

Most endpoints are public and do not require authentication. However, the Submit Job Application endpoint requires an API key for external integrations.

API Key Authentication with HMAC Signature

To submit job applications via API, you need an API key and must sign each request with an HMAC signature. Three headers are required:

X-API-Key: your-api-key-hereX-Timestamp: 1698765432000X-Signature: hmac-sha256-signature

⚠️ Security Warning

Never expose your Secret Key in frontend code! The secret key must only be used on your backend server. API requests should only be made from server-side code.

Getting API Credentials: Log in to the admin platform, navigate to Settings → API Keys, and create a new key. You'll receive both an API Key and a Secret Key (shown only once).

Rate Limiting

To ensure fair usage and system stability, all public API endpoints are rate limited.

Default Rate Limit

300 requests per minute (average of 5 requests per second)

Applies to: Company info, Job boards, Job listings

Job Applications Rate Limit

60 requests per minute (1 request per second)

Stricter limit to prevent spam and ensure quality submissions

Rate Limit Headers

When rate limited, you'll receive a 429 Too Many Requests response with the following headers:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Requests remaining
X-RateLimit-Reset - Time when limit resets

GET

Get Company Information

/company/:companyId

Retrieve basic information about a company including name, logo, and brand colors.

Parameters

Parameter	Type	Description
`companyId`	string	MongoDB ObjectId of the company

Response

{
  "companyName": "Acme Corp",
  "logo": "https://example.com/logo.png",
  "slogan": "Building the future",
  "primaryColor": "#3B82F6",
  "secondaryColor": "#8B5CF6"
}

GET

Get Job Board by Slug

/job-boards/slug/:slug

Retrieve job board details using its unique slug.

Parameters

Parameter	Type	Description
`slug`	string	URL-friendly identifier for the job board

Response

{
  "_id": "68bdee88b858cd75883621cd",
  "slug": "acme-careers",
  "title": "Acme Careers",
  "companyId": "68bdee88b858cd75883621cd",
  "isActive": true
}

GET

Get Jobs by Job Board

/jobs/job-board/:jobBoardId

Retrieve all published jobs for a specific job board.

Parameters

Parameter	Type	Description
`jobBoardId`	string	MongoDB ObjectId of the job board

Response

[
  {
    "_id": "68ec13ea2a75bad5539d37b8",
    "title": "Senior Backend Engineer",
    "location": "San Francisco, CA (Hybrid)",
    "content": "<p>Job description...</p>",
    "company": {
      "id": "68bdee88b858cd75883621cd",
      "name": "Acme Corp"
    },
    "departments": [
      {
        "id": "68bdee88b858cd75883621ce",
        "name": "Engineering"
      }
    ],
    "slug": "senior-backend-engineer-68ec13ea2a75bad5539d37b8",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
]

GET

Get Job by ID

/jobs/:jobId

Retrieve detailed information about a specific job, including populated job board data.

Parameters

Parameter	Type	Description
`jobId`	string	MongoDB ObjectId of the job

Response

{
  "_id": "68ec13ea2a75bad5539d37b8",
  "title": "Senior Backend Engineer",
  "location": "San Francisco, CA (Hybrid)",
  "content": "<p>Job description...</p>",
  "company": {
    "id": "68bdee88b858cd75883621cd",
    "name": "Acme Corp"
  },
  "jobBoard": {
    "_id": "68bdee88b858cd75883621cd",
    "slug": "acme-careers",
    "title": "Acme Careers",
    "companyId": "68bdee88b858cd75883621cd"
  },
  "departments": [...],
  "slug": "senior-backend-engineer-68ec13ea2a75bad5539d37b8",
  "compensation": {
    "range": "$120,000 - $180,000",
    "equity": true,
    "bonus": true,
    "details": "Comprehensive benefits including health insurance, 401k matching, and unlimited PTO"
  }
}

Compensation Object (Optional)

Field	Type	Description
`range`	string	Salary range (e.g., "$80,000 - $120,000")
`equity`	boolean	Whether equity/stock options are offered
`bonus`	boolean	Whether performance bonus is offered
`details`	string	Additional compensation details and benefits

POST

Submit Job Application

/job-applications

Submit a job application with optional resume file. Requires API Key authentication. Files are scanned for malicious content before processing.

🔑 Authentication Required

This endpoint requires three authentication headers:

X-API-Key - Your API key
X-Timestamp - Current Unix timestamp (ms)
X-Signature - HMAC-SHA256(timestamp, secretKey)

The signature is generated by hashing the timestamp with your secret key using HMAC-SHA256.

Request Body (multipart/form-data)

Field	Type	Required	Description
`jobId`	string	✓	MongoDB ObjectId of the job posting
`firstName`	string	✓	Applicant's first name
`lastName`	string	✓	Applicant's last name
`email`	string	✓	Applicant's email address
`phone`	string		Applicant's phone number
`linkedin`	string		LinkedIn profile URL
`website`	string		Personal website or portfolio URL
`coverLetter`	string		Cover letter text
`resume`	file	✓	Resume file (PDF, DOC, DOCX - Max 5MB)
`source`	string		Application source (e.g., "LinkedIn", "Indeed", "Referral")
`consentDuration`	number		GDPR consent duration in months (default: 12)

Example Request (Node.js)

const crypto = require('crypto');

// Generate timestamp and signature
const timestamp = Date.now().toString();
const signature = crypto
  .createHmac('sha256', process.env.SECRET_KEY)
  .update(timestamp)
  .digest('hex');

// Make request with authentication headers
const formData = new FormData();
formData.append('jobId', '507f1f77bcf86cd799439011');
formData.append('firstName', 'John');
formData.append('lastName', 'Doe');
formData.append('email', 'john.doe@example.com');
formData.append('resume', fileBuffer, 'resume.pdf');

fetch('https://api.hatchbeacon.com/api/v1/job-applications', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature
  },
  body: formData
});

Response (Success)

{
  "id": "507f1f77bcf86cd799439012",
  "jobId": "507f1f77bcf86cd799439011",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "linkedin": "https://linkedin.com/in/johndoe",
  "status": "new",
  "source": "LinkedIn",
  "resumePath": "resumes/507f1f77bcf86cd799439012.pdf",
  "resumeFilename": "resume.pdf",
  "appliedAt": "2025-10-25T21:30:00.000Z",
  "consentGiven": true,
  "consentExpiresAt": "2026-10-25T21:30:00.000Z"
}

Error Responses

401 Unauthorized

Invalid or missing API key

400 Bad Request

Missing required fields, invalid file type, or file size exceeds limit

404 Not Found

Job not found

429 Too Many Requests

Rate limit exceeded (60 requests per minute)

Support

For API support, questions, or to report issues, please contact us at contact@hatchbeacon.com