🚀 Job Submission API

Overview

This API allows recruiters, colleagues, and connections to submit job opportunities directly. It's designed to be simple, open, and easy to integrate into your workflows.

🎯 Interactive API Explorer

Try out the API right here in your browser!

📚 API Endpoints

POST/api/jobs/

Submit a new job opportunity for review.

Request Body

{
  "title": "Senior Software Engineer",
  "company": "Example Corp",
  "url": "https://example.com/careers/senior-engineer",
  "description": "Looking for a Django expert with 5+ years experience...",
  "submitted_by": "recruiter@example.com"
}

Parameters

Field	Type	Required	Description
title	string	Yes	Job title or position name
company	string	Yes	Company or organization name
url	string (URL)	Yes	Link to the job posting
description	string	No	Additional notes or context
submitted_by	string (email)	Yes	Email address of submitter

Success Response (201 Created)

{
  "message": "Job submission received successfully! Thank you for thinking of me.",
  "data": {
    "title": "Senior Software Engineer",
    "company": "Example Corp",
    "url": "https://example.com/careers/senior-engineer",
    "description": "Looking for a Django expert...",
    "submitted_by": "recruiter@example.com"
  }
}

Error Response (400 Bad Request)

{
  "title": ["This field is required."],
  "url": ["Enter a valid URL."]
}

---

GET/api/jobs/

Retrieve all submitted job opportunities.

Success Response (200 OK)

[
  {
    "id": 1,
    "title": "Senior Software Engineer",
    "company": "Tech Startup",
    "url": "https://example.com/jobs/123",
    "description": "Looking for Django/React expertise",
    "submitted_by": "recruiter@example.com",
    "submitted_at": "2024-01-15T10:30:00Z",
    "status": "pending"
  },
  {
    "id": 2,
    "title": "Full Stack Developer",
    "company": "Another Company",
    "url": "https://another.com/jobs/456",
    "description": "Remote position",
    "submitted_by": "friend@example.com",
    "submitted_at": "2024-01-14T09:15:00Z",
    "status": "pending"
  }
]

---

GET/api/jobs/{id}/

Retrieve a specific job submission by ID.

Path Parameters

Parameter	Type	Description
id	integer	The unique identifier of the job submission

Success Response (200 OK)

{
  "id": 1,
  "title": "Senior Software Engineer",
  "company": "Tech Startup",
  "url": "https://example.com/jobs/123",
  "description": "Looking for Django/React expertise",
  "submitted_by": "recruiter@example.com",
  "submitted_at": "2024-01-15T10:30:00Z",
  "status": "pending"
}

Error Response (404 Not Found)

{
  "error": "Job submission not found"
}

📦 Data Models

JobSubmission

Field	Type	Description
id	integer	Unique identifier (auto-generated)
title	string	Job title
company	string	Company name
url	string	Job posting URL
description	string	Optional additional details
submitted_by	string	Email of submitter
submitted_at	datetime	Timestamp of submission (auto-generated)
status	string	Current status (read-only)

Status Values

💻 Code Examples

cURL

curl -X POST https://noconsonants.com/api/jobs/ \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "company": "Tech Startup",
    "url": "https://example.com/jobs/123",
    "description": "Looking for Django/React expertise",
    "submitted_by": "recruiter@example.com"
  }'

Python (httpx)

import httpx

url = "https://noconsonants.com/api/jobs/"
data = {
    "title": "Senior Software Engineer",
    "company": "Tech Startup",
    "url": "https://example.com/jobs/123",
    "description": "Looking for Django/React expertise",
    "submitted_by": "recruiter@example.com"
}

response = httpx.post(url, json=data)
print(response.json())

JavaScript (fetch)

fetch('https://noconsonants.com/api/jobs/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Senior Software Engineer',
    company: 'Tech Startup',
    url: 'https://example.com/jobs/123',
    description: 'Looking for Django/React expertise',
    submitted_by: 'recruiter@example.com'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Node.js (axios)

const axios = require('axios');

async function submitJob() {
  try {
    const response = await axios.post('https://noconsonants.com/api/jobs/', {
      title: 'Senior Software Engineer',
      company: 'Tech Startup',
      url: 'https://example.com/jobs/123',
      description: 'Looking for Django/React expertise',
      submitted_by: 'recruiter@example.com'
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

submitJob();

✨ Best Practices

• Be Specific: Include detailed descriptions when possible to help understand the opportunity
• Valid URLs: Ensure job posting URLs are accessible and direct to the actual position
• Add Context: Use the description field to explain why the role might be a good fit
• Legitimate Only: Only submit real, open positions from trustworthy sources
• Respect the Service: While there's no rate limiting, please don't abuse the API

⚠️ Error Handling & Limitations

HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful (GET requests)
201	Created	Job submission created successfully
400	Bad Request	Invalid data or missing required fields
404	Not Found	Requested resource doesn't exist
500	Server Error	Something went wrong on the server

Rate Limiting

Error Response Format

All error responses follow a consistent format. Validation errors return field-specific messages:

{
  "field_name": ["Error message for this field"],
  "another_field": ["Another error message"]
}

General errors return:

{
  "error": "Error message describing what went wrong"
}