NHS Jobs Portal API Documentation

Complete API reference for the NHS Jobs Portal. Access endpoints for job listings, applications, employer management, and user authentication.

AI/Agent Integration Resources

OpenAPI Spec JSON Schemas TypeScript Types

Authentication

POST

/api/auth/register

Body Parameters

Name	Type	Description
email*	string	Valid email address. Must be unique.
password*	string	Password with minimum 8 characters. Must contain uppercase, lowercase, and numbers.
name*	string	Full name of the user.
userType*	string	Either 'jobseeker' or 'employer'.

Responses

Success (201)

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "jobseeker"
    }
  },
  "message": "Registration successful"
}

Error (409)

{
  "success": false,
  "error": "Email already registered"
}

POST

/api/auth/login

Authenticate with email and password. Returns JWT access token (15 min) and refresh token (7 days).

Body Parameters

Name	Type	Description
email*	string	Registered email address.
password*	string	Account password.

Responses

Success (200)

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "jobseeker",
      "subscriptionStatus": "active"
    }
  },
  "message": "Login successful"
}

Error (401)

{
  "success": false,
  "error": "Invalid email or password"
}

POST

/api/auth/refresh

Refresh expired access token using refresh token. Returns new access and refresh tokens.

Body Parameters

Name	Type	Description
refreshToken*	string	Valid refresh token from login or previous refresh.

Responses

Success (200)

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc..."
  },
  "message": "Token refreshed successfully"
}

Error (401)

{
  "success": false,
  "error": "Invalid or expired refresh token"
}

POST

/api/auth/logout

Logout current user. Invalidates tokens on the server.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Logged out successfully"
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

User Profile

GET

/api/auth/me

Get current authenticated user's profile information.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "jobseeker",
    "createdAt": "2024-01-15T10:30:00Z",
    "subscriptionStatus": "active"
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/jobseekers/profile

Get detailed user profile with preferences and settings.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "bio": "Healthcare professional",
    "location": "London, UK",
    "preferences": {
      "jobAlerts": true,
      "emailNotifications": true
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/jobseekers/profile

Update jobseeker profile. Requires 'intent' parameter with value 'update-profile'. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'update-profile'.
profile*	object	Profile object containing fields: firstName, lastName, email, phone, location, specialty, currentRole, experience, preferredLocation, locationRadius, employmentTypes, salaryMin, salaryMax.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "intent": "update-profile",
    "profile": {
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

POST

/api/jobseekers/saved

Save a job listing for the current user. Add a job to the user's saved/bookmarked jobs list.

Body Parameters

Name	Type	Description
listingId*	string	UUID of the job listing to save.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "listingId": "uuid",
    "title": "Nurse",
    "company": "NHS Trust",
    "savedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Job saved successfully"
}

Error (400)

{
  "success": false,
  "error": "Already saved"
}

Employers API

GET

/api/employers/profile

Get employer profile information including company details and contact information.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "profile": {
      "name": "John Doe",
      "jobTitle": "HR Manager"
    },
    "company": {
      "name": "NHS Trust",
      "industry": "Healthcare",
      "size": "1000+"
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/employers/profile

Update employer profile. Requires 'intent' parameter. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'update-profile'.
profile	object	Profile data containing name, jobTitle, etc.
companyName	string	Company name.
industry	string	Industry type.
companySize	string	Company size.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Profile updated successfully"
}

Error (429)

{
  "success": false,
  "error": "Rate limit exceeded"
}

GET

/api/employers/jobs

Get employer's job listings with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "uuid",
        "title": "Nurse",
        "company": "NHS Trust",
        "status": "active"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/employers/jobs

Create new job listing. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
title*	string	Job title.
description*	string	Job description.
department	string	Department.
contractType	string	Contract type (permanent, temporary, contract).
salary	object	Salary object with min, max, currency.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (201)

{
  "success": true,
  "message": "Job listing created successfully",
  "data": {
    "id": "uuid"
  }
}

Error (429)

{
  "success": false,
  "error": "Rate limit exceeded"
}

GET

/api/employers/applications

Get applications for employer's job listings with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "applications": [
      {
        "id": "uuid",
        "jobId": "uuid",
        "jobTitle": "Nurse",
        "status": "pending"
      }
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 20,
      "totalPages": 5
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/employers/team

Get employer team members with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "team": [
      {
        "id": "uuid",
        "name": "Jane Doe",
        "email": "[email protected]",
        "role": "Recruiter"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "totalPages": 1
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/employers/team

Add team member. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'add-member'.
name*	string	Team member name.
email*	string	Team member email.
role	string	Team member role.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Team member added successfully"
}

Error (429)

{
  "success": false,
  "error": "Rate limit exceeded"
}

GET

/api/employers/settings

Get employer settings.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "email": "[email protected]",
    "company": {
      "name": "NHS Trust"
    },
    "contact": {
      "name": "John Doe"
    },
    "preferences": {}
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/employers/settings

Update employer settings. Requires 'intent' parameter. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'update-profile' or 'update-notifications'.
companyName	string	Company name for update-profile intent.
industry	string	Industry for update-profile intent.
emailAlerts	boolean	Email alerts preference for update-notifications intent.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Settings updated successfully"
}

Error (429)

{
  "success": false,
  "error": "Rate limit exceeded"
}

DELETE

/api/employers/settings

Reset employer settings to defaults. Rate limited to 10 requests per 15 minutes per IP.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Settings reset to defaults successfully",
  "data": {
    "settings": {
      "notifications": {},
      "preferences": {}
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

DELETE

/api/employers/profile

Soft delete employer account. Rate limited to 10 requests per 15 minutes per IP.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Account deleted successfully"
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/employers/jobs/:id

Get specific job listing details by ID.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "job": {
      "id": "uuid",
      "title": "Nurse",
      "description": "Job description",
      "company": "NHS Trust",
      "location": "London, UK",
      "status": "active"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

PUT

/api/employers/jobs/:id

Update individual job listing. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
title	string	Job title.
description	string	Job description.
department	string	Department.
contractType	string	Contract type.
salary	object	Salary object.
status	string	Job status (active, inactive, closed).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Job listing updated successfully",
  "data": {
    "id": "uuid"
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

DELETE

/api/employers/jobs/:id

Archive (soft delete) job listing. Rate limited to 10 requests per 15 minutes per IP.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Job listing archived successfully",
  "data": {
    "id": "uuid"
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

GET

/api/employers/applications/:id

Get specific application details by ID.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "application": {
      "id": "uuid",
      "jobId": "uuid",
      "applicantEmail": "[email protected]",
      "jobTitle": "Nurse",
      "status": "pending"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

PUT

/api/employers/applications/:id

Update application status. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
status*	string	New status (pending, review, interview, accepted, rejected, withdrawn).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Application status updated successfully",
  "data": {
    "id": "uuid",
    "status": "review"
  }
}

Error (400)

{
  "success": false,
  "error": "Invalid status"
}

DELETE

/api/employers/applications/:id

Withdraw application. Rate limited to 10 requests per 15 minutes per IP.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Application withdrawn successfully",
  "data": {
    "id": "uuid"
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

POST

/api/auth/register-employer

Body Parameters

Name	Type	Description
email*	string	Valid email address. Must be unique.
password*	string	Password with minimum 8 characters.
name*	string	Full name of the user.
companyName*	string	Company name.
industry	string	Industry type.
companySize	string	Company size.

Responses

Success (201)

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "user": {
      "id": "uuid",
      "email": "[email protected]",
      "role": "EMPLOYER"
    }
  },
  "message": "Registration successful"
}

Error (429)

{
  "success": false,
  "error": "Rate limit exceeded"
}

GET

/api/employers/analytics

Get overall employer analytics including job counts and application statistics.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "jobs": {
      "total": 50,
      "active": 35,
      "draft": 15
    },
    "applications": {
      "total": 200,
      "pending": 50,
      "review": 75,
      "interview": 30,
      "accepted": 40,
      "rejected": 5
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/employers/jobs/:id/analytics

Get individual job performance metrics including application counts and conversion rate.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "jobId": "uuid",
    "title": "Nurse",
    "views": 500,
    "applications": {
      "total": 25,
      "pending": 10,
      "review": 8,
      "interview": 4,
      "accepted": 3
    },
    "conversionRate": 5
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

GET

/api/employers/applications/stats

Get application statistics with filters by status, time period, and job.

Body Parameters

Name	Type	Description
status	string	Filter by application status.
startDate	string	Filter by start date (ISO format).
endDate	string	Filter by end date (ISO format).
jobId	string	Filter by job ID.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "total": 100,
    "byStatus": {
      "pending": 30,
      "review": 40,
      "interview": 20,
      "accepted": 10
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/employers/jobs/batch

Batch create up to 100 job listings. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
jobs*	array	Array of job objects with title, description, department, contractType, salary.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Batch created: 90 jobs succeeded, 10 failed",
  "data": {
    "created": [
      {
        "id": "uuid",
        "title": "Nurse"
      }
    ],
    "failed": [
      {
        "job": {},
        "error": "title is required"
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "error": "Maximum 100 jobs per batch request"
}

PUT

/api/employers/jobs/batch

Batch update up to 100 job listings. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
jobs*	array	Array of job objects with id and fields to update.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Batch updated: 95 jobs succeeded, 5 failed",
  "data": {
    "updated": [
      {
        "id": "uuid"
      }
    ],
    "failed": [
      {
        "job": {},
        "error": "Job listing not found"
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "error": "Maximum 100 jobs per batch request"
}

GET

/api/employers/applications/export

Export application data to CSV format.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/employers/applications/:id/interview

Schedule an interview for a specific application.

Body Parameters

Name	Type	Description
scheduledAt*	string	Interview date and time (ISO format).
location*	string	Interview location or meeting link.
interviewer*	string	Name of the interviewer.
notes	string	Additional interview notes.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Interview scheduled successfully",
  "data": {
    "applicationId": "uuid",
    "interview": {
      "scheduledAt": "2024-02-01T10:00:00Z",
      "location": "Room 101",
      "interviewer": "John Doe"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

PUT

/api/employers/applications/:id/interview

Update interview details for a specific application.

Body Parameters

Name	Type	Description
scheduledAt	string	Updated interview date and time.
location	string	Updated interview location.
interviewer	string	Updated interviewer.
status	string	Interview status (scheduled, completed, cancelled).
outcome	string	Interview outcome (pass, fail, pending).
notes	string	Updated interview notes.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Interview updated successfully",
  "data": {
    "applicationId": "uuid",
    "interview": {
      "status": "completed",
      "outcome": "pass"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

GET

/api/employers/interviews

Get all scheduled interviews for the employer's jobs.

Body Parameters

Name	Type	Description
status	string	Filter by interview status.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "interviews": [
      {
        "applicationId": "uuid",
        "jobId": "uuid",
        "jobTitle": "Nurse",
        "applicantName": "Jane Doe",
        "applicantEmail": "[email protected]",
        "status": "pending",
        "interview": {
          "scheduledAt": "2024-02-01T10:00:00Z",
          "location": "Room 101"
        }
      }
    ],
    "total": 25
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/employers/jobs/:id/duplicate

Duplicate a job listing to create a copy.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Job duplicated successfully",
  "data": {
    "id": "uuid",
    "title": "Nurse (Copy)"
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

POST

/api/employers/jobs/:id/renew

Extend an expired job listing's deadline.

Body Parameters

Name	Type	Description
durationDays	number	Number of days to extend (default: 30).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Job renewed successfully",
  "data": {
    "id": "uuid",
    "status": "active",
    "applicationDeadline": "2024-03-01T00:00:00Z"
  }
}

Error (404)

{
  "success": false,
  "error": "Job listing not found"
}

GET

/api/employers/organization

Get organization details.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "organizationId": "352",
    "company": {
      "name": "NHS Trust",
      "description": "Healthcare provider",
      "website": "https://example.com",
      "industry": "Healthcare",
      "size": "1000+"
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/employers/organization

Update organization profile.

Body Parameters

Name	Type	Description
name	string	Organization name.
description	string	Organization description.
website	string	Organization website.
logo	string	Organization logo URL.
industry	string	Industry type.
size	string	Organization size.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Organization updated successfully",
  "data": {
    "company": {
      "name": "NHS Trust"
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/employers/team/:id/permissions

Get team member permissions.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "userId": "uuid",
    "role": "EMPLOYER",
    "permissions": {
      "jobs": {
        "create": true,
        "update": true,
        "delete": false
      },
      "applications": {
        "view": true,
        "update": true
      }
    }
  }
}

Error (403)

{
  "success": false,
  "error": "Team member not in your organization"
}

PUT

/api/employers/team/:id/permissions

Update team member permissions (Admin only).

Body Parameters

Name	Type	Description
permissions	object	Permissions object.
role	string	Team member role.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Team member permissions updated successfully",
  "data": {
    "userId": "uuid",
    "permissions": {},
    "role": "EMPLOYER"
  }
}

Error (403)

{
  "success": false,
  "error": "Team member not in your organization"
}

GET

/api/employers/jobs/export

Export job listings to CSV format.

Body Parameters

Name	Type	Description
format	string	Export format (only csv supported).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

Error (400)

{
  "success": false,
  "error": "Only CSV format is supported"
}

POST

/api/employers/applications/batch

Batch update up to 100 application statuses.

Body Parameters

Name	Type	Description
applications*	array	Array of application objects with id and status.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Batch updated: 95 applications succeeded, 5 failed",
  "data": {
    "updated": [
      {
        "id": "uuid",
        "status": "review"
      }
    ],
    "failed": [
      {
        "appUpdate": {},
        "error": "Application not found"
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "error": "Maximum 100 applications per batch request"
}

POST

/api/employers/applications/:id/contact

Send email to applicant.

Body Parameters

Name	Type	Description
subject*	string	Email subject.
message*	string	Email message content.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Email queued for sending",
  "data": {
    "to": "[email protected]",
    "subject": "Interview Invitation"
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

Job Listings

GET

/api/listings

Search and retrieve job listings with filtering, pagination, and sorting options.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).
search	string	Search term for job title or description.
location	string	Filter by location (city or region).
contractType	string	Filter by contract type (permanent, temporary, contract).
salary_min	number	Minimum salary filter.
salary_max	number	Maximum salary filter.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "uuid",
        "title": "Nurse",
        "company": "NHS Trust",
        "location": "London",
        "salary": {
          "min": 28000,
          "max": 35000
        },
        "contractType": "permanent",
        "postedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1250
    }
  }
}

Error (400)

{
  "success": false,
  "error": "Invalid filter parameters"
}

GET

/api/listings/:id

Get detailed information about a specific job listing.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "Senior Nurse",
    "company": "NHS Trust",
    "description": "We are looking for an experienced nurse...",
    "location": "London",
    "salary": {
      "min": 35000,
      "max": 42000
    },
    "contractType": "permanent",
    "requirements": [
      "RN License",
      "5+ years experience"
    ],
    "benefits": [
      "Competitive salary",
      "Pension scheme"
    ],
    "applicationDeadline": "2024-02-15"
  }
}

Error (404)

{
  "success": false,
  "error": "Listing not found"
}

POST

/api/listings/search

Advanced search with full-text search capabilities and complex filters.

Body Parameters

Name	Type	Description
query*	string	Full-text search query.
filters	object	Complex filter object with location, salary, contract type, etc.
sort	string	Sort by: 'relevance', 'date', 'salary', 'distance'.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "uuid",
        "title": "Nurse",
        "relevance": 0.95
      }
    ],
    "total": 450
  }
}

Error (400)

{
  "success": false,
  "error": "Invalid search query"
}

PATCH

/api/listings/:id

Partially update a specific job listing. Merges provided fields with existing data.

Body Parameters

Name	Type	Description
meta*	object	Partial listing metadata to update. Merged with existing meta.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes
X-API-Key	<apiKey>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "uuid": "uuid",
    "meta": {
      "listing": {
        "title": "Updated Title"
      }
    }
  },
  "message": "Listing updated successfully"
}

Error (404)

{
  "success": false,
  "error": "Listing not found"
}

POST

/api/listings/:id/restore

Restore a soft-deleted job listing back to active status.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes
X-API-Key	<apiKey>	No

Responses

Success (200)

{
  "success": true,
  "message": "Listing restored successfully"
}

Error (404)

{
  "success": false,
  "error": "Listing not found or not deleted"
}

POST

/api/listings/:id/archive

Archive a job listing by setting status to 'archived' with timestamp.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes
X-API-Key	<apiKey>	No

Responses

Success (200)

{
  "success": true,
  "message": "Listing archived successfully"
}

Error (404)

{
  "success": false,
  "error": "Listing not found"
}

PUT

/api/listings/batch

Batch update multiple job listings. Limited to 100 listings per request.

Body Parameters

Name	Type	Description
array*	array	Array of listing update objects with uuid and meta fields.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes
X-API-Key	<apiKey>	No

Responses

Success (200)

{
  "success": true,
  "data": [
    {
      "success": true,
      "uuid": "uuid",
      "index": 0
    }
  ],
  "message": "Batch update completed: 1/1 successful"
}

Error (400)

{
  "success": false,
  "error": "Batch update requires an array of listings"
}

Applications

GET

/api/jobseekers/applications

Get list of job applications submitted by the current user with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "applications": [
      {
        "id": "uuid",
        "listingId": "uuid",
        "jobTitle": "Nurse",
        "status": "pending",
        "appliedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 50,
      "page": 1,
      "limit": 20,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/jobseekers/applications

Submit a job application for a specific listing. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
listingId*	string	UUID of the job listing.
coverLetter	string	Optional cover letter text.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "listingId": "uuid",
    "status": "pending",
    "appliedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Application submitted successfully"
}

Error (400)

{
  "success": false,
  "error": "Already applied to this position"
}

GET

/api/jobseekers/applications/:id

Get details of a specific application.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "application": {
      "id": "uuid",
      "jobId": "uuid",
      "jobTitle": "Nurse",
      "status": "pending",
      "appliedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

PUT

/api/jobseekers/applications/:id

Update application status.

Body Parameters

Name	Type	Description
status	string	New status (pending, in-progress, completed, rejected).
statusColor	string	CSS classes for status display.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Application updated successfully",
  "data": {
    "application": {
      "id": "uuid",
      "status": "completed"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

DELETE

/api/jobseekers/applications/:id

Delete a specific application.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Application deleted successfully",
  "data": {
    "id": "uuid"
  }
}

Error (404)

{
  "success": false,
  "error": "Application not found"
}

Bookmarks

GET

/api/jobseekers/bookmarks

Get list of bookmarked job listings with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "bookmarks": {
      "savedJobs": [
        {
          "id": "uuid",
          "title": "Nurse",
          "company": "NHS Trust",
          "savedAt": "2024-01-15T10:30:00Z"
        }
      ]
    },
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 20,
      "totalPages": 2,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/jobseekers/bookmarks

Bookmark a job listing for later viewing. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
listingId*	string	UUID of the job listing to bookmark.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (201)

{
  "success": true,
  "message": "Listing bookmarked successfully"
}

Error (400)

{
  "success": false,
  "error": "Already bookmarked"
}

GET

/api/jobseekers/bookmarks/:id

Get details of a specific bookmark.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "bookmark": {
      "type": "job",
      "id": "uuid"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Bookmark not found"
}

PUT

/api/jobseekers/bookmarks/:id

Update bookmark notes.

Body Parameters

Name	Type	Description
notes	string	Notes for the bookmark.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Bookmark updated successfully"
}

Error (404)

{
  "success": false,
  "error": "Bookmark not found"
}

DELETE

/api/jobseekers/bookmarks/:id

Remove a specific bookmark.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Bookmark removed successfully",
  "data": {
    "id": "uuid",
    "type": "job"
  }
}

Error (404)

{
  "success": false,
  "error": "Bookmark not found"
}

Documents

GET

/api/jobseekers/documents

Get list of user's uploaded documents (CVs, cover letters, etc.) with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "uuid",
        "type": "cv",
        "title": "My CV",
        "uploadedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "limit": 20,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/jobseekers/documents

Upload or manage documents. Requires 'intent' parameter. Intents: 'upload-document', 'update-document', 'delete-document', 'set-default'. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'upload-document', 'update-document', 'delete-document', or 'set-default'.
type	string	Document type for upload-document intent: 'cv', 'cover-letter', 'certification', 'other'.
title	string	Document title for upload-document or update-document intents.
content	string	Document content for upload-document or update-document intents.
fileName	string	File name for upload-document intent.
documentId	string	Document ID for update-document, delete-document, or set-default intents.
isDefault	boolean	Set as default for document type for update-document or set-default intents.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Document uploaded successfully",
  "data": {
    "document": {
      "id": "uuid",
      "type": "cv",
      "title": "My CV"
    }
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

GET

/api/jobseekers/documents/:id

Get details of a specific document.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "document": {
      "id": "uuid",
      "type": "cv",
      "title": "My CV"
    }
  }
}

Error (404)

{
  "success": false,
  "error": "Document not found"
}

PUT

/api/jobseekers/documents/:id

Update document details.

Body Parameters

Name	Type	Description
title	string	Document title.
content	string	Document content.
isDefault	boolean	Set as default for document type.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Document updated successfully"
}

Error (404)

{
  "success": false,
  "error": "Document not found"
}

DELETE

/api/jobseekers/documents/:id

Delete a specific document.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Document deleted successfully"
}

Error (404)

{
  "success": false,
  "error": "Document not found"
}

Notifications

GET

/api/jobseekers/notifications

Get user notifications with pagination.

Body Parameters

Name	Type	Description
page	number	Page number (default: 1).
limit	number	Results per page (default: 20, max: 100).

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": "uuid",
        "type": "application",
        "message": "Application received",
        "read": false
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 20,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/jobseekers/notifications/:id

Mark notification as read. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
read	boolean	Read status.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Notification updated successfully"
}

Error (404)

{
  "success": false,
  "error": "Notification not found"
}

DELETE

/api/jobseekers/notifications/:id

Delete a notification.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Notification deleted successfully"
}

Error (404)

{
  "success": false,
  "error": "Notification not found"
}

Analytics & Activity

GET

/api/jobseekers/analytics

Get user analytics including application stats, bookmark counts, and profile completion.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "analytics": {
      "applications": {
        "total": 10,
        "pending": 3
      },
      "bookmarks": {
        "savedJobs": 25
      },
      "profile": {
        "completion": 75
      }
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/jobseekers/activity

Get user activity timeline with pagination.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "activities": [
      {
        "type": "application",
        "action": "applied",
        "description": "Applied for Nurse",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 50
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

Data Export

GET

/api/jobseekers/export/applications

Export application history in JSON or CSV format.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "applications": [
      {
        "id": "uuid",
        "jobTitle": "Nurse",
        "status": "pending"
      }
    ]
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

GET

/api/jobseekers/export/profile

Export profile data in JSON or CSV format.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "profile": {
      "uuid": "uuid",
      "email": "[email protected]",
      "profile": {
        "name": "John Doe"
      }
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

Onboarding & Recommendations

GET

/api/jobseekers/onboarding

Get onboarding status and progress.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "onboardingComplete": true,
  "onboarding": {
    "steps": []
  }
}

Error (500)

{
  "success": false,
  "error": "Internal server error"
}

POST

/api/jobseekers/onboarding

Handle onboarding actions. Uses FormData instead of JSON body. Actions: 'capture_email', 'track_step', 'update_preferences'. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
action*	string	Action type: 'capture_email', 'track_step', or 'update_preferences'.
email	string	Email address for capture_email action.
source	string	Source of email capture for capture_email action: 'apply', 'save', 'search'.
step	string	Onboarding step name for track_step action.
actionType	string	Step action type for track_step: 'viewed', 'completed', 'skipped'.
preferences	string	JSON string of preferences for update_preferences action.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "message": "Email captured for guest user",
  "isGuest": true
}

Error (400)

{
  "success": false,
  "error": "Invalid action"
}

GET

/api/jobseekers/recommendations

Get personalized job recommendations based on user preferences.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "uuid": "uuid",
        "title": "Nurse",
        "relevanceScore": 85
      }
    ],
    "total": 100
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

Billing & Subscriptions

GET

/api/jobseekers/billing

Get billing information, subscription status, and available plans.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "billing": {
      "subscription": {
        "tier": "premium",
        "status": "active",
        "expiresAt": "2024-02-15T00:00:00Z",
        "autoRenew": true
      },
      "billingHistory": [],
      "plans": [
        {
          "id": "basic",
          "name": "Basic",
          "price": 0
        },
        {
          "id": "premium",
          "name": "Premium",
          "price": 29.99
        }
      ],
      "paymentMethods": []
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

POST

/api/jobseekers/billing

Create subscription, cancel subscription, update payment method, or upgrade plan. Requires 'intent' parameter. Rate limited to 10 requests per 15 minutes per IP.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'create-subscription', 'cancel-subscription', 'update-payment-method', or 'upgrade-plan'.
planId	string	Plan ID for create-subscription or upgrade-plan intents.
paymentMethodId	string	Payment method ID for create-subscription or update-payment-method intents.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Billing action completed successfully",
  "data": {
    "intent": "create-subscription",
    "subscription": {
      "tier": "premium",
      "status": "active"
    }
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

Dashboard

GET

/api/jobseekers/dashboard

Get personalized dashboard content with recommendations, activity, and stats. Works for both authenticated and guest users.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "dashboard": {
      "isGuest": false,
      "subscriptionStatus": {
        "tier": "premium",
        "isActive": true
      },
      "recommendations": [
        {
          "id": "uuid",
          "title": "Nurse",
          "company": "NHS Trust"
        }
      ],
      "recentActivity": [
        {
          "type": "application",
          "title": "Applied to Nurse",
          "timestamp": "2024-01-15T10:30:00Z"
        }
      ],
      "stats": {
        "applicationsCount": 5,
        "bookmarksCount": 10,
        "recommendationsCount": 5
      }
    }
  }
}

Error (500)

{
  "success": false,
  "error": "Internal server error"
}

POST

/api/jobseekers/dashboard

Generate personalized content via AI or track dashboard actions. Requires 'intent' parameter.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'generate-personalized-content' or 'track-dashboard-action'.
specialty	string	Healthcare specialty for personalized content generation.
careerGoals	string	Career goals for personalized content generation.
experience	string	Experience level for personalized content generation.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Dashboard action completed successfully",
  "data": {
    "intent": "generate-personalized-content",
    "personalizedContent": {
      "headline": "Find Your Perfect Healthcare Career"
    }
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

Search

GET

/api/jobseekers/search

Search for jobs with personalized filters. Works for both authenticated and guest users. Supports query parameters for filtering and pagination.

Body Parameters

Name	Type	Description
q	string	Search query for job title, description, or company.
location	string	Filter by location (city or region).
type	string	Filter by contract type (permanent, temporary, contract).
salaryMin	number	Minimum salary filter.
salaryMax	number	Maximum salary filter.
page	number	Page number (default: 1).
limit	number	Results per page (default: 10, max: 20).
sort	string	Sort by: 'postedAt', 'salary', 'title', 'location'.
order	string	Sort order: 'asc' or 'desc' (default: 'desc').

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	No

Responses

Success (200)

{
  "success": true,
  "data": {
    "search": {
      "jobs": [
        {
          "id": "uuid",
          "title": "Nurse",
          "company": "NHS Trust",
          "location": {
            "city": "London",
            "region": "Greater London"
          },
          "type": "permanent",
          "salary": {
            "min": 28000,
            "max": 35000
          },
          "isBookmarked": false
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 10,
        "total": 125,
        "totalPages": 13,
        "hasNext": true,
        "hasPrev": false
      }
    }
  }
}

Error (500)

{
  "success": false,
  "error": "Internal server error"
}

POST

/api/jobseekers/search

Save search preferences, update search preferences, or delete saved searches. Requires 'intent' parameter.

Body Parameters

Name	Type	Description
intent*	string	Action type: 'save-search', 'update-search-preferences', or 'delete-search'.
name	string	Search name for save-search intent.
query	string	Search query for save-search intent.
location	string	Location filter for save-search intent.
contractType	string	Contract type filter for save-search intent.
emailAlerts	boolean	Enable email alerts for saved search.
preferredLocation	string	Preferred location for update-search-preferences intent.
employmentTypes	array	Preferred employment types for update-search-preferences intent.
searchId	string	Search ID for delete-search intent.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Search action completed successfully",
  "data": {
    "intent": "save-search",
    "savedSearches": [
      {
        "id": "uuid",
        "name": "Nurse jobs in London",
        "query": "nurse",
        "location": "London"
      }
    ]
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

Settings

GET

/api/jobseekers/settings

Get current user settings. Supports jobseeker, employer, and employer-team roles.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "data": {
    "settings": {
      "id": 1,
      "uuid": "uuid",
      "email": "[email protected]",
      "profile": {
        "name": "John Doe",
        "bio": "Experienced nurse"
      },
      "preferences": {
        "notifications": {
          "email": true,
          "jobAlerts": false
        },
        "jobPreferences": {
          "preferredLocation": "London"
        }
      },
      "bookmarks": {
        "savedJobs": [],
        "savedSearches": []
      }
    }
  }
}

Error (401)

{
  "success": false,
  "error": "Unauthorized"
}

PUT

/api/jobseekers/settings

Update user settings. Requires 'intent' parameter. Jobseeker intents: 'update-profile', 'update-notifications', 'update-privacy', 'update-job-preferences'. Employer intents: 'update-profile', 'update-notifications', 'update-contact', 'update-employer-profile'.

Body Parameters

Name	Type	Description
intent*	string	Action type based on user role.
profile	object	Profile data for update-profile intent.
email	boolean	Email notification preference for update-notifications intent.
jobAlerts	boolean	Job alerts preference for update-notifications intent.
showProfile	boolean	Show profile preference for update-privacy intent.
preferredLocation	string	Preferred location for update-job-preferences intent.
employmentTypes	array	Preferred employment types for update-job-preferences intent.

Headers

Name	Value	Required
Authorization	Bearer <accessToken>	Yes

Responses

Success (200)

{
  "success": true,
  "message": "Settings updated successfully",
  "data": {
    "intent": "update-profile"
  }
}

Error (400)

{
  "success": false,
  "error": "Intent is required"
}

Error Handling

ALL

All Endpoints

Standard error response format used across all API endpoints. Always check the 'success' field and 'error' message for debugging.

Responses

Success (400)

{
  "success": false,
  "error": "Bad Request - Invalid parameters",
  "details": {
    "field": "email",
    "message": "Invalid email format"
  }
}

Error (500)

{
  "success": false,
  "error": "Internal Server Error - Please try again later"
}

Menu

Navigation

Legal

NHS Jobs Portal API Documentation

AI/Agent Integration Resources

Authentication

/api/auth/register

Body Parameters

Responses

/api/auth/login

Body Parameters

Responses

/api/auth/refresh

Body Parameters

Responses

/api/auth/logout

Headers

Responses

User Profile

/api/auth/me

Headers

Responses

/api/jobseekers/profile

Headers

Responses

/api/jobseekers/profile

Body Parameters

Headers

Responses

/api/jobseekers/saved

Body Parameters

Headers

Responses

Employers API

/api/employers/profile

Headers

Responses

/api/employers/profile

Body Parameters

Headers

Responses

/api/employers/jobs

Body Parameters

Headers

Responses

/api/employers/jobs

Body Parameters

Headers

Responses

/api/employers/applications

Body Parameters

Headers

Responses

/api/employers/team

Body Parameters

Headers

Responses

/api/employers/team

Body Parameters

Headers

Responses

/api/employers/settings

Headers

Responses

/api/employers/settings

Body Parameters

Headers

Responses

/api/employers/settings

Headers

Responses

/api/employers/profile

Headers

Responses

/api/employers/jobs/:id

Headers

Responses

/api/employers/jobs/:id

Body Parameters

Headers