API

Documentation

Version 1.0

Candidates API

The Candidates API allows job seekers to manage their profiles, search for jobs, and track their applications on the AutoTechJobs platform.

GET

/candidates/profile

Retrieve the profile information for the authenticated candidate.

Example Request

curl -X GET   "https://api.autotechjobs.co.uk/v1/candidates/profile"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"

Example Response

{
  "data": {
    "id": "cand_789012",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+44 7123 456789",
    "location": "Manchester, UK",
    "headline": "Senior React Developer with 7+ years of experience",
    "summary": "Passionate React developer with expertise in building scalable web applications...",
    "experience": [
      {
        "title": "Senior Frontend Developer",
        "company": "Web Solutions Ltd",
        "location": "Manchester, UK",
        "start_date": "2022-03",
        "end_date": null,
        "current": true,
        "description": "Leading the frontend development team..."
      },
      {
        "title": "Frontend Developer",
        "company": "Tech Innovations",
        "location": "London, UK",
        "start_date": "2018-06",
        "end_date": "2022-02",
        "current": false,
        "description": "Developed responsive web applications..."
      }
    ],
    "education": [
      {
        "institution": "University of Manchester",
        "degree": "BSc Computer Science",
        "field": "Computer Science",
        "start_date": "2015-09",
        "end_date": "2018-06",
        "description": "First Class Honours"
      }
    ],
    "skills": [
      "React",
      "TypeScript",
      "JavaScript",
      "HTML",
      "CSS",
      "Redux",
      "Node.js",
      "GraphQL"
    ],
    "resume_url": "https://api.autotechjobs.co.uk/v1/candidates/resume",
    "website": "https://janesmith.dev",
    "github": "https://github.com/janesmith",
    "linkedin": "https://linkedin.com/in/janesmith",
    "created_at": "2023-05-10T09:15:00Z",
    "updated_at": "2025-03-15T14:30:00Z"
  }
}
PUT

/candidates/profile

Update the profile information for the authenticated candidate.

Request Body

The request body can include any of the profile fields you want to update. All fields are optional.

Example Request

curl -X PUT   "https://api.autotechjobs.co.uk/v1/candidates/profile"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "headline": "Senior React & TypeScript Developer with 8+ years of experience",
    "summary": "Updated professional summary with recent achievements...",
    "location": "Remote, UK",
    "skills": ["React", "TypeScript", "JavaScript", "HTML", "CSS", "Redux", "Node.js", "GraphQL", "Next.js", "Testing Library"]
  }'

Example Response

{
  "data": {
    "id": "cand_789012",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "+44 7123 456789",
    "location": "Remote, UK",
    "headline": "Senior React & TypeScript Developer with 8+ years of experience",
    "summary": "Updated professional summary with recent achievements...",
    "experience": [...],
    "education": [...],
    "skills": [
      "React",
      "TypeScript",
      "JavaScript",
      "HTML",
      "CSS",
      "Redux",
      "Node.js",
      "GraphQL",
      "Next.js",
      "Testing Library"
    ],
    "resume_url": "https://api.autotechjobs.co.uk/v1/candidates/resume",
    "website": "https://janesmith.dev",
    "github": "https://github.com/janesmith",
    "linkedin": "https://linkedin.com/in/janesmith",
    "created_at": "2023-05-10T09:15:00Z",
    "updated_at": "2025-04-10T20:32:13Z"
  }
}
GET

/candidates/applications

Retrieve all job applications for the authenticated candidate.

Query Parameters

ParameterTypeDescription
pageintegerPage number for pagination (default: 1)
limitintegerNumber of results per page (default: 20, max: 100)
statusstringFilter by application status: pending, reviewed, contacted, rejected, hired (default: all)
sortstringSort by: applied_at, updated_at (default: applied_at)
orderstringSort order: asc or desc (default: desc)

Example Request

curl -X GET   "https://api.autotechjobs.co.uk/v1/candidates/applications?status=pending"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"

Example Response

{
  "data": [
    {
      "id": "app_123456",
      "job": {
        "id": "job_123456",
        "title": "Senior React Developer",
        "company": "Tech Innovations Ltd",
        "location": "London, UK",
        "type": "full-time",
        "salary": {
          "min": 60000,
          "max": 80000,
          "currency": "GBP",
          "period": "year"
        }
      },
      "cover_letter": "I am writing to express my interest in the Senior React Developer position...",
      "status": "pending",
      "applied_at": "2025-04-05T14:30:00Z",
      "updated_at": "2025-04-05T14:30:00Z"
    },
    // More applications...
  ],
  "meta": {
    "pagination": {
      "total": 5,
      "pages": 1,
      "page": 1,
      "limit": 20
    }
  }
}
POST

/candidates/jobs/:id/apply

Apply for a specific job listing.

Path Parameters

ParameterTypeDescription
idstringJob ID

Request Body

FieldTypeRequiredDescription
cover_letterstringYesCover letter for the application
resume_idstringNoID of the resume to use (if not provided, the default resume will be used)
custom_questionsobjectNoAnswers to custom questions for the job (if required)

Example Request

curl -X POST   "https://api.autotechjobs.co.uk/v1/candidates/jobs/job_123456/apply"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "cover_letter": "I am writing to express my interest in the Senior React Developer position at Tech Innovations Ltd. With over 7 years of experience in React development...",
    "custom_questions": {
      "availability": "I can start immediately",
      "salary_expectations": "£70,000 - £80,000 per annum"
    }
  }'

Example Response

{
  "data": {
    "id": "app_789012",
    "job": {
      "id": "job_123456",
      "title": "Senior React Developer",
      "company": "Tech Innovations Ltd"
    },
    "status": "pending",
    "applied_at": "2025-04-10T20:32:13Z",
    "updated_at": "2025-04-10T20:32:13Z"
  }
}

Additional Endpoints

The Candidates API also includes the following endpoints:

  • GET /candidates/jobs/saved - Get saved job listings
  • POST /candidates/jobs/:id/save - Save a job listing
  • DELETE /candidates/jobs/:id/save - Remove a saved job listing
  • POST /candidates/resume - Upload a new resume
  • GET /candidates/resume - Get the current resume
  • GET /candidates/job-alerts - Get job alerts
  • POST /candidates/job-alerts - Create a new job alert

Next Steps