Skip to content

API Docs

Jump to bottom
Kamrul Hasan Tusher edited this page Sep 12, 2025 · 1 revision

Career Sync API Endpoints Documentation

This document outlines the API endpoints required for the Career Sync platform based on the user stories.

Base URL

https://api.careersync.com/v1

Authentication

Most endpoints require authentication using Bearer tokens for company managers.

Authorization: Bearer <access_token>

Public Endpoints (Job Seekers)

Jobs

GET /jobs

Get all public job postings with optional filtering and searching.

Query Parameters:

  • search (string, optional): Search by keywords in title/description
  • location (string, optional): Filter by job location
  • company_id (string, optional): Filter by specific company
  • page (integer, optional): Page number for pagination (default: 1)
  • limit (integer, optional): Number of items per page (default: 20)

Response:

{
  "data": [
    {
      "id": "job_123",
      "title": "Senior Software Engineer",
      "description": "We are looking for...",
      "requirements": "5+ years experience...",
      "location": "New York, NY",
      "company": {
        "id": "company_456",
        "name": "TechCorp Inc.",
        "description": "Leading software company",
        "logo": "https://example.com/logo.jpg"
      },
      "application_method": {
        "type": "email", // or "external"
        "value": "jobs@techcorp.com" // or external URL
      },
      "published": true,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 98,
    "items_per_page": 20
  }
}

GET /jobs/{job_id}

Get detailed information about a specific job posting.

Response:

{
  "data": {
    "id": "job_123",
    "title": "Senior Software Engineer",
    "description": "We are looking for...",
    "requirements": "5+ years experience...",
    "location": "New York, NY",
    "company": {
      "id": "company_456",
      "name": "TechCorp Inc.",
      "description": "Leading software company",
      "logo": "https://example.com/logo.jpg"
    },
    "application_method": {
      "type": "email",
      "value": "jobs@techcorp.com"
    },
    "published": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Companies

GET /companies/{company_id}

Get public information about a specific company.

Response:

{
  "data": {
    "id": "company_456",
    "name": "TechCorp Inc.",
    "description": "Leading software company specializing in...",
    "logo": "https://example.com/logo.jpg",
    "website": "https://techcorp.com",
    "location": "New York, NY"
  }
}

Authentication Endpoints

POST /auth/register

Register a new company manager account.

Request Body:

{
  "email": "manager@company.com",
  "password": "securepassword123",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "My Company Inc."
}

Response:

{
  "data": {
    "user": {
      "id": "user_123",
      "email": "manager@company.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "company": {
      "id": "company_456",
      "name": "My Company Inc."
    },
    "access_token": "jwt_token_here",
    "refresh_token": "refresh_token_here"
  }
}

POST /auth/login

Login with existing credentials.

Request Body:

{
  "email": "manager@company.com",
  "password": "securepassword123"
}

Response:

{
  "data": {
    "user": {
      "id": "user_123",
      "email": "manager@company.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "company": {
      "id": "company_456",
      "name": "My Company Inc."
    },
    "access_token": "jwt_token_here",
    "refresh_token": "refresh_token_here"
  }
}

POST /auth/refresh

Refresh access token using refresh token.

Request Body:

{
  "refresh_token": "refresh_token_here"
}

Response:

{
  "data": {
    "access_token": "new_jwt_token_here",
    "refresh_token": "new_refresh_token_here"
  }
}

Protected Endpoints (Company Managers)

Company Management

GET /companies/me

Get current user's company information.

Headers: Authorization: Bearer <token>

Response:

{
  "data": {
    "id": "company_456",
    "name": "My Company Inc.",
    "description": "We are a leading company in...",
    "logo": "https://example.com/logo.jpg",
    "website": "https://mycompany.com",
    "location": "San Francisco, CA"
  }
}

PUT /companies/me

Update current user's company information.

Headers: Authorization: Bearer <token>

Request Body:

{
  "name": "Updated Company Name",
  "description": "Updated company description...",
  "logo": "https://example.com/new-logo.jpg",
  "website": "https://updatedcompany.com",
  "location": "Austin, TX"
}

Response:

{
  "data": {
    "id": "company_456",
    "name": "Updated Company Name",
    "description": "Updated company description...",
    "logo": "https://example.com/new-logo.jpg",
    "website": "https://updatedcompany.com",
    "location": "Austin, TX"
  }
}

Job Management

GET /companies/:company_id/jobs

Get all job postings for a specific company.

Path Parameters:

  • company_id (string, required): The company ID

Headers: Authorization: Bearer <token> (required if accessing private company data)

Query Parameters:

  • status (string, optional): Filter by status ('published', 'draft', 'all')
  • page (integer, optional): Page number for pagination
  • limit (integer, optional): Number of items per page

Response:

{
  "data": [
    {
      "id": "job_123",
      "title": "Senior Software Engineer",
      "description": "We are looking for...",
      "requirements": "5+ years experience...",
      "location": "New York, NY",
      "application_method": {
        "type": "email",
        "value": "jobs@company.com"
      },
      "published": true,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_items": 12,
    "items_per_page": 20
  }
}

POST /companies/:company_id/jobs

Create a new job posting for a specific company.

Path Parameters:

  • company_id (string, required): The company ID

Headers: Authorization: Bearer <token>

Request Body:

{
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced...",
  "requirements": "5+ years of experience in...",
  "location": "Remote",
  "application_method": {
    "type": "email",
    "value": "careers@company.com"
  },
  "published": false
}

Response:

{
  "data": {
    "id": "job_789",
    "title": "Senior Software Engineer",
    "description": "We are looking for an experienced...",
    "requirements": "5+ years of experience in...",
    "location": "Remote",
    "application_method": {
      "type": "email",
      "value": "careers@company.com"
    },
    "published": false,
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

GET /companies/:company_id/jobs/:job_id

Get a specific job posting for a specific company.

Path Parameters:

  • company_id (string, required): The company ID
  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token> (required if accessing private job data)

Response:

{
  "data": {
    "id": "job_123",
    "title": "Senior Software Engineer",
    "description": "We are looking for...",
    "requirements": "5+ years experience...",
    "location": "New York, NY",
    "application_method": {
      "type": "email",
      "value": "jobs@company.com"
    },
    "published": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

PUT /companies/:company_id/jobs/:job_id

Update a specific job posting for a specific company.

Path Parameters:

  • company_id (string, required): The company ID
  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Request Body:

{
  "title": "Updated Job Title",
  "description": "Updated job description...",
  "requirements": "Updated requirements...",
  "location": "Updated Location",
  "application_method": {
    "type": "external",
    "value": "https://company.com/apply"
  },
  "published": true
}

Response:

{
  "data": {
    "id": "job_123",
    "title": "Updated Job Title",
    "description": "Updated job description...",
    "requirements": "Updated requirements...",
    "location": "Updated Location",
    "application_method": {
      "type": "external",
      "value": "https://company.com/apply"
    },
    "published": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T16:45:00Z"
  }
}

DELETE /companies/:company_id/jobs/:job_id

Delete a specific job posting for a specific company.

Path Parameters:

  • company_id (string, required): The company ID
  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Response:

{
  "message": "Job posting deleted successfully"
}

PATCH /companies/:company_id/jobs/:job_id/publish

Publish or unpublish a job posting for a specific company.

Path Parameters:

  • company_id (string, required): The company ID
  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Request Body:

{
  "published": true
}

Response:

{
  "data": {
    "id": "job_123",
    "published": true,
    "updated_at": "2024-01-15T17:00:00Z"
  }
}

GET /companies/me/jobs

Get all job postings for the current user's company (convenience endpoint).

Headers: Authorization: Bearer <token>

Query Parameters:

  • status (string, optional): Filter by status ('published', 'draft', 'all')
  • page (integer, optional): Page number for pagination
  • limit (integer, optional): Number of items per page

Response:

{
  "data": [
    {
      "id": "job_123",
      "title": "Senior Software Engineer",
      "description": "We are looking for...",
      "requirements": "5+ years experience...",
      "location": "New York, NY",
      "application_method": {
        "type": "email",
        "value": "jobs@company.com"
      },
      "published": true,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_items": 12,
    "items_per_page": 20
  }
}

POST /companies/me/jobs

Create a new job posting for the current user's company (convenience endpoint).

Headers: Authorization: Bearer <token>

Request Body:

{
  "title": "Senior Software Engineer",
  "description": "We are looking for an experienced...",
  "requirements": "5+ years of experience in...",
  "location": "Remote",
  "application_method": {
    "type": "email",
    "value": "careers@company.com"
  },
  "published": false
}

Response:

{
  "data": {
    "id": "job_789",
    "title": "Senior Software Engineer",
    "description": "We are looking for an experienced...",
    "requirements": "5+ years of experience in...",
    "location": "Remote",
    "application_method": {
      "type": "email",
      "value": "careers@company.com"
    },
    "published": false,
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}

GET /companies/me/jobs/:job_id

Get a specific job posting owned by the current user's company (convenience endpoint).

Path Parameters:

  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Response:

{
  "data": {
    "id": "job_123",
    "title": "Senior Software Engineer",
    "description": "We are looking for...",
    "requirements": "5+ years experience...",
    "location": "New York, NY",
    "application_method": {
      "type": "email",
      "value": "jobs@company.com"
    },
    "published": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

PUT /companies/me/jobs/:job_id

Update a specific job posting owned by the current user's company (convenience endpoint).

Path Parameters:

  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Request Body:

{
  "title": "Updated Job Title",
  "description": "Updated job description...",
  "requirements": "Updated requirements...",
  "location": "Updated Location",
  "application_method": {
    "type": "external",
    "value": "https://company.com/apply"
  },
  "published": true
}

Response:

{
  "data": {
    "id": "job_123",
    "title": "Updated Job Title",
    "description": "Updated job description...",
    "requirements": "Updated requirements...",
    "location": "Updated Location",
    "application_method": {
      "type": "external",
      "value": "https://company.com/apply"
    },
    "published": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T16:45:00Z"
  }
}

DELETE /companies/me/jobs/:job_id

Delete a specific job posting owned by the current user's company (convenience endpoint).

Path Parameters:

  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Response:

{
  "message": "Job posting deleted successfully"
}

PATCH /companies/me/jobs/:job_id/publish

Publish or unpublish a job posting owned by the current user's company (convenience endpoint).

Path Parameters:

  • job_id (string, required): The job ID

Headers: Authorization: Bearer <token>

Request Body:

{
  "published": true
}

Response:

{
  "data": {
    "id": "job_123",
    "published": true,
    "updated_at": "2024-01-15T17:00:00Z"
  }
}

Error Responses

All endpoints return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

Common HTTP Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (invalid/missing token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 422 - Unprocessable Entity (business logic errors)
  • 500 - Internal Server Error

Rate Limiting

  • Public endpoints: 100 requests per minute per IP
  • Authenticated endpoints: 1000 requests per minute per user
  • Rate limit headers included in responses:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

CORS Support

The API supports CORS for web applications with appropriate headers configured for development and production domains.

Clone this wiki locally