API

Documentation

Version 1.0

Applications API

The Applications API provides endpoints for managing job applications on the AutoTechJobs platform. This API can be used by both employers and candidates to interact with applications.

GET

/applications/:id

Retrieve detailed information about a specific application. This endpoint is accessible to both the employer who posted the job and the candidate who applied.

Path Parameters

ParameterTypeDescription
idstringApplication ID

Example Request

curl -X GET   "https://api.autotechjobs.co.uk/v1/applications/app_123456"   -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"
    },
    "candidate": {
      "id": "cand_789012",
      "name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+44 7123 456789",
      "location": "Manchester, UK"
    },
    "cover_letter": "I am writing to express my interest in the Senior React Developer position...",
    "resume_url": "https://api.autotechjobs.co.uk/v1/applications/app_123456/resume",
    "status": "pending",
    "custom_questions": {
      "availability": "I can start immediately",
      "salary_expectations": "£70,000 - £80,000 per annum"
    },
    "notes": [
      {
        "id": "note_123",
        "content": "Candidate has excellent React experience",
        "created_by": "usr_456",
        "created_at": "2025-04-06T10:15:00Z"
      }
    ],
    "timeline": [
      {
        "action": "applied",
        "timestamp": "2025-04-05T14:30:00Z",
        "actor": "candidate"
      },
      {
        "action": "reviewed",
        "timestamp": "2025-04-06T10:15:00Z",
        "actor": "employer"
      }
    ],
    "applied_at": "2025-04-05T14:30:00Z",
    "updated_at": "2025-04-06T10:15:00Z"
  }
}
PUT

/applications/:id/status

Update the status of an application. This endpoint is only accessible to employers.

Path Parameters

ParameterTypeDescription
idstringApplication ID

Request Body

FieldTypeRequiredDescription
statusstringYesNew application status: pending, reviewed, contacted, rejected, hired
notestringNoOptional note about the status change
notify_candidatebooleanNoWhether to notify the candidate about the status change (default: false)

Example Request

curl -X PUT   "https://api.autotechjobs.co.uk/v1/applications/app_123456/status"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "status": "contacted",
    "note": "Scheduled initial phone interview for next Tuesday",
    "notify_candidate": true
  }'

Example Response

{
  "data": {
    "id": "app_123456",
    "job": {
      "id": "job_123456",
      "title": "Senior React Developer"
    },
    "candidate": {
      "id": "cand_789012",
      "name": "Jane Smith"
    },
    "status": "contacted",
    "timeline": [
      {
        "action": "applied",
        "timestamp": "2025-04-05T14:30:00Z",
        "actor": "candidate"
      },
      {
        "action": "reviewed",
        "timestamp": "2025-04-06T10:15:00Z",
        "actor": "employer"
      },
      {
        "action": "status_changed",
        "timestamp": "2025-04-10T20:32:13Z",
        "actor": "employer",
        "details": {
          "from": "pending",
          "to": "contacted",
          "note": "Scheduled initial phone interview for next Tuesday"
        }
      }
    ],
    "applied_at": "2025-04-05T14:30:00Z",
    "updated_at": "2025-04-10T20:32:13Z"
  }
}
POST

/applications/:id/notes

Add a note to an application. This endpoint is only accessible to employers.

Path Parameters

ParameterTypeDescription
idstringApplication ID

Request Body

FieldTypeRequiredDescription
contentstringYesContent of the note
visibilitystringNoVisibility of the note: private (employer only) or shared (employer and candidate). Default: private

Example Request

curl -X POST   "https://api.autotechjobs.co.uk/v1/applications/app_123456/notes"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "content": "Candidate has strong React experience and good communication skills. Would be a good fit for the team.",
    "visibility": "private"
  }'

Example Response

{
  "data": {
    "id": "note_456",
    "application_id": "app_123456",
    "content": "Candidate has strong React experience and good communication skills. Would be a good fit for the team.",
    "visibility": "private",
    "created_by": "usr_456",
    "created_at": "2025-04-10T20:32:13Z"
  }
}
DELETE

/applications/:id

Withdraw an application. This endpoint is only accessible to candidates who submitted the application.

Path Parameters

ParameterTypeDescription
idstringApplication ID

Query Parameters

ParameterTypeDescription
reasonstringOptional reason for withdrawing the application

Example Request

curl -X DELETE   "https://api.autotechjobs.co.uk/v1/applications/app_123456?reason=Accepted%20another%20offer"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"

Example Response

{
  "data": {
    "id": "app_123456",
    "status": "withdrawn",
    "withdrawn_at": "2025-04-10T20:32:13Z",
    "reason": "Accepted another offer"
  }
}

Additional Endpoints

The Applications API also includes the following endpoints:

  • GET /applications/:id/resume - Get the resume for an application
  • GET /applications/:id/timeline - Get the full timeline for an application
  • POST /applications/:id/messages - Send a message related to an application
  • GET /applications/:id/messages - Get messages related to an application
  • POST /applications/:id/schedule-interview - Schedule an interview for an application

Next Steps