1526 lines
45 KiB
JSON
1526 lines
45 KiB
JSON
{
|
|
"openapi": "3.0.0",
|
|
"info": {
|
|
"title": "Migrant Mobile API",
|
|
"description": "Comprehensive API endpoints for the Migrant Mobile Application, covering worker registration, password login, token authentication, profile management, and interactive job offer responses.",
|
|
"version": "1.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "/api",
|
|
"description": "Local development API prefix"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/workers/register": {
|
|
"post": {
|
|
"tags": [
|
|
"Worker/Auth"
|
|
],
|
|
"summary": "Register Worker & Upload Documents (Unified API)",
|
|
"description": "Performs worker registration and uploads their passport/visa documents in a single, robust multipart form request. Generates and returns a secure stateless bearer token upon success. Password is required (min 6 characters).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"phone",
|
|
"salary",
|
|
"password",
|
|
"passport_file"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Amina Al-Masry",
|
|
"description": "Full legal name of the worker. (REQUIRED)"
|
|
},
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509998888",
|
|
"description": "Contact mobile phone number (must be unique). (REQUIRED)"
|
|
},
|
|
"salary": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"example": 1500.00,
|
|
"description": "Desired minimum monthly salary in AED. (REQUIRED)"
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "securepassword123",
|
|
"description": "Secret password for subsequent mobile logins (min 6 chars). (REQUIRED)"
|
|
},
|
|
"passport_file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "Physical scan or image of the Passport (Max 10MB). (REQUIRED)"
|
|
},
|
|
"skills": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "integer"
|
|
},
|
|
"example": [6, 8],
|
|
"description": "Optional array of Skill IDs (can be sent as comma-separated string e.g. '6,8' or json '[6,8]' in multipart)."
|
|
},
|
|
"visa_file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "Optional physical scan or image of the Visa (Max 10MB)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Worker registered and authenticated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Worker registered and authenticated successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"worker": {
|
|
"$ref": "#/components/schemas/Worker"
|
|
},
|
|
"token": {
|
|
"type": "string",
|
|
"example": "abc123xyz456...secureToken..."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation error details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": false
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Validation error."
|
|
},
|
|
"errors": {
|
|
"type": "object",
|
|
"properties": {
|
|
"phone": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"example": [
|
|
"This mobile number is already registered."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/login": {
|
|
"post": {
|
|
"tags": [
|
|
"Worker/Auth"
|
|
],
|
|
"summary": "Authenticate Worker",
|
|
"description": "Validates worker credentials (mobile phone number and password) and generates a secure, stateless Bearer token for api access.",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"phone",
|
|
"password"
|
|
],
|
|
"properties": {
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509998888",
|
|
"description": "Registered mobile phone number."
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "securepassword123",
|
|
"description": "Secret account password."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Worker logged in successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Worker logged in successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"worker": {
|
|
"$ref": "#/components/schemas/Worker"
|
|
},
|
|
"token": {
|
|
"type": "string",
|
|
"example": "abc123xyz456...secureToken..."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "Unauthorized access.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": false
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Invalid mobile number or password."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/profile": {
|
|
"get": {
|
|
"tags": [
|
|
"Worker/Profile"
|
|
],
|
|
"summary": "Get Profile details",
|
|
"description": "Retrieves the authenticated worker's profile details including their selected job category, connected skills, and uploaded documents.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Worker profile details retrieved.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"worker": {
|
|
"$ref": "#/components/schemas/Worker"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/profile/update": {
|
|
"post": {
|
|
"tags": [
|
|
"Worker/Profile"
|
|
],
|
|
"summary": "Update Profile details",
|
|
"description": "Allows workers to customize and complete their profiles by updating age, nationality, desired salary, bio, availability, experience, religion, categories, and master skills list.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Amina Al-Masry"
|
|
},
|
|
"age": {
|
|
"type": "integer",
|
|
"example": 28
|
|
},
|
|
"nationality": {
|
|
"type": "string",
|
|
"example": "Egypt"
|
|
},
|
|
"salary": {
|
|
"type": "number",
|
|
"example": 1800.00
|
|
},
|
|
"availability": {
|
|
"type": "string",
|
|
"example": "Immediate"
|
|
},
|
|
"experience": {
|
|
"type": "string",
|
|
"example": "4 Years"
|
|
},
|
|
"religion": {
|
|
"type": "string",
|
|
"example": "Muslim"
|
|
},
|
|
"bio": {
|
|
"type": "string",
|
|
"example": "Highly certified housekeeper and babysitter with cooking experience."
|
|
},
|
|
"category_id": {
|
|
"type": "integer",
|
|
"example": 8
|
|
},
|
|
"skills": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "integer"
|
|
},
|
|
"example": [6, 8]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Profile updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Profile updated successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"worker": {
|
|
"$ref": "#/components/schemas/Worker"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/offers": {
|
|
"get": {
|
|
"tags": [
|
|
"Worker/Offers"
|
|
],
|
|
"summary": "View Received Job Offers",
|
|
"description": "Returns a list of all custom job/hiring offers received by the worker from different employers (e.g. Work Date, location, salaries, and notes).",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of job offers retrieved.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"offers": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/JobOffer"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/offers/{id}/respond": {
|
|
"post": {
|
|
"tags": [
|
|
"Worker/Offers"
|
|
],
|
|
"summary": "Accept or Reject Job Offer",
|
|
"description": "Responds to a pending job offer. If accepted, the job offer status becomes 'accepted' and the worker's status is automatically changed to 'Hired', which reflects immediately in the Employer panel.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The Job Offer ID reference.",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"accepted",
|
|
"rejected"
|
|
],
|
|
"example": "accepted",
|
|
"description": "Response action (accepted or rejected)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Job offer response saved successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "Job offer successfully accepted."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"offer": {
|
|
"$ref": "#/components/schemas/JobOffer"
|
|
},
|
|
"worker_status": {
|
|
"type": "string",
|
|
"example": "Hired"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/conversations": {
|
|
"get": {
|
|
"tags": [
|
|
"Worker/Conversations"
|
|
],
|
|
"summary": "Get Conversations List (Worker)",
|
|
"description": "Retrieves all active conversations for the authenticated worker.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conversations list retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/conversations/{id}/messages": {
|
|
"get": {
|
|
"tags": [
|
|
"Worker/Conversations"
|
|
],
|
|
"summary": "Get Conversation Messages (Worker)",
|
|
"description": "Retrieves message history for a conversation and marks incoming employer messages as read.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Messages retrieved successfully."
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Worker/Conversations"
|
|
],
|
|
"summary": "Send Reply Message (Worker)",
|
|
"description": "Sends a reply message from the worker to the employer.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"example": "Yes, I am available."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Message sent successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/register": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Register Sponsor (Alias)",
|
|
"description": "Legacy route matching the simplified sponsor registration (Name, Email, Phone).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"email",
|
|
"phone"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Ahmad Bin Ahmed",
|
|
"description": "Sponsor's full name"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com",
|
|
"description": "Sponsor's contact email address"
|
|
},
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509990001",
|
|
"description": "Sponsor's mobile phone number"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Sponsor registered successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sponsors/register": {
|
|
"post": {
|
|
"tags": [
|
|
"Sponsor/Auth"
|
|
],
|
|
"summary": "Register Sponsor",
|
|
"description": "Registers a new sponsor profile with basic info (Name, Email, Phone).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"email",
|
|
"phone"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Ahmad Bin Ahmed",
|
|
"description": "Sponsor's full name"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com",
|
|
"description": "Sponsor's contact email address"
|
|
},
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509990001",
|
|
"description": "Sponsor's mobile phone number"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Sponsor registered successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/verify": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Verify Sponsor Email OTP",
|
|
"description": "Verifies the email address with the OTP verification code (Step 2).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"otp"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"otp": {
|
|
"type": "string",
|
|
"example": "111111",
|
|
"description": "6-digit OTP code"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Email verified successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sponsors/verify": {
|
|
"post": {
|
|
"tags": [
|
|
"Sponsor/Auth"
|
|
],
|
|
"summary": "Verify Sponsor Email OTP (Sponsor Prefix)",
|
|
"description": "Verifies the email address with the OTP verification code (Step 2).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"otp"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"otp": {
|
|
"type": "string",
|
|
"example": "111111",
|
|
"description": "6-digit OTP code"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Email verified successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/payment": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Sponsor Subscription Payment",
|
|
"description": "Submits a successful plan selection and PayTabs payment confirmation (Step 3).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"plan_id",
|
|
"amount_aed",
|
|
"paytabs_transaction_id"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"plan_id": {
|
|
"type": "string",
|
|
"example": "premium"
|
|
},
|
|
"amount_aed": {
|
|
"type": "number",
|
|
"example": 199.00
|
|
},
|
|
"paytabs_transaction_id": {
|
|
"type": "string",
|
|
"example": "TXN998877"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Subscription payment confirmed."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sponsors/payment": {
|
|
"post": {
|
|
"tags": [
|
|
"Sponsor/Auth"
|
|
],
|
|
"summary": "Sponsor Subscription Payment (Sponsor Prefix)",
|
|
"description": "Submits a successful plan selection and PayTabs payment confirmation (Step 3).",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"plan_id",
|
|
"amount_aed",
|
|
"paytabs_transaction_id"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"plan_id": {
|
|
"type": "string",
|
|
"example": "premium"
|
|
},
|
|
"amount_aed": {
|
|
"type": "number",
|
|
"example": 199.00
|
|
},
|
|
"paytabs_transaction_id": {
|
|
"type": "string",
|
|
"example": "TXN998877"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Subscription payment confirmed."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/password": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Create Sponsor Account Password",
|
|
"description": "Configures and finalizes the portal login password to complete registration (Step 4). Returns bearer token.",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"password",
|
|
"password_confirmation"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "Password@123"
|
|
},
|
|
"password_confirmation": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "Password@123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Password set and registration finalized successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sponsors/password": {
|
|
"post": {
|
|
"tags": [
|
|
"Sponsor/Auth"
|
|
],
|
|
"summary": "Create Sponsor Account Password (Sponsor Prefix)",
|
|
"description": "Configures and finalizes the portal login password to complete registration (Step 4). Returns bearer token.",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"password",
|
|
"password_confirmation"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "Password@123"
|
|
},
|
|
"password_confirmation": {
|
|
"type": "string",
|
|
"format": "password",
|
|
"example": "Password@123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Password set and registration finalized successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/plans": {
|
|
"get": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Get Available Subscription Plans",
|
|
"description": "Returns details (price, features) of subscription packages available to sponsors.",
|
|
"security": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Subscription plans list retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/sponsors/plans": {
|
|
"get": {
|
|
"tags": [
|
|
"Sponsor/Auth"
|
|
],
|
|
"summary": "Get Available Subscription Plans (Sponsor Prefix)",
|
|
"description": "Returns details (price, features) of subscription packages available to sponsors.",
|
|
"security": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Subscription plans list retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/login": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Auth"
|
|
],
|
|
"summary": "Authenticate Employer",
|
|
"description": "Validates employer email and password and returns a stateless Bearer token.",
|
|
"security": [],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"email",
|
|
"password"
|
|
],
|
|
"properties": {
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"example": "Password@123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Employer logged in successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/conversations": {
|
|
"get": {
|
|
"tags": [
|
|
"Employer/Conversations"
|
|
],
|
|
"summary": "Get Conversations List (Employer)",
|
|
"description": "Retrieves all active candidate conversations for the authenticated employer.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conversations list retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/conversations/{id}/messages": {
|
|
"get": {
|
|
"tags": [
|
|
"Employer/Conversations"
|
|
],
|
|
"summary": "Get Conversation Messages (Employer)",
|
|
"description": "Retrieves message history for a conversation and marks incoming worker messages as read.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Messages retrieved successfully."
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Conversations"
|
|
],
|
|
"summary": "Send Reply Message (Employer)",
|
|
"description": "Sends a reply message from the employer to the worker.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"example": "When can you start?"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Message sent successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/conversations/start": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Conversations"
|
|
],
|
|
"summary": "Start Conversation with Worker",
|
|
"description": "Starts or retrieves a conversation with the specified worker ID.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"worker_id"
|
|
],
|
|
"properties": {
|
|
"worker_id": {
|
|
"type": "integer",
|
|
"example": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conversation started successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/workers/announcements": {
|
|
"get": {
|
|
"tags": [
|
|
"Worker/CharityEvents"
|
|
],
|
|
"summary": "Get Charity Events (Worker)",
|
|
"description": "Allows workers to retrieve the list of active charity events, food drives, and medical support programs scheduled in Dubai.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of charity events retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/announcements": {
|
|
"get": {
|
|
"tags": [
|
|
"Employer/CharityEvents"
|
|
],
|
|
"summary": "Get Posted Charity Events (Employer)",
|
|
"description": "Allows employers/sponsors to retrieve the list of charity events they have published.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of posted charity events retrieved successfully."
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Employer/CharityEvents"
|
|
],
|
|
"summary": "Publish Charity Event (Employer)",
|
|
"description": "Allows employers/sponsors to publish a new community charity event or drive to all workers in Dubai, triggering instant push notifications and morning-of reminders.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"title",
|
|
"content",
|
|
"provided_items",
|
|
"event_date",
|
|
"event_time",
|
|
"location_details",
|
|
"location_pin"
|
|
],
|
|
"properties": {
|
|
"title": {
|
|
"type": "string",
|
|
"example": "Free Dental Checkup Camp"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"example": "Emirates Charity is providing free professional dental screening, cleanings, and educational packages for domestic helpers."
|
|
},
|
|
"provided_items": {
|
|
"type": "string",
|
|
"example": "Free Dental screening, cleanings, and wellness kits"
|
|
},
|
|
"event_date": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"example": "2026-06-15"
|
|
},
|
|
"event_time": {
|
|
"type": "string",
|
|
"example": "9:00 AM - 4:00 PM"
|
|
},
|
|
"location_details": {
|
|
"type": "string",
|
|
"example": "Al Quoz Community Hall, Dubai"
|
|
},
|
|
"location_pin": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"example": "https://maps.app.goo.gl/xyz"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Charity event created and notifications scheduled successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/announcements/{id}": {
|
|
"delete": {
|
|
"tags": [
|
|
"Employer/CharityEvents"
|
|
],
|
|
"summary": "Delete Charity Event (Employer)",
|
|
"description": "Allows employers/sponsors to delete a previously published charity event.",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Charity event deleted successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/profile": {
|
|
"get": {
|
|
"tags": [
|
|
"Employer/Profile"
|
|
],
|
|
"summary": "Get Profile details (Employer)",
|
|
"description": "Retrieves the authenticated employer's profile details including their selected company name, phone, language preference, and notification settings.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Employer profile details retrieved successfully."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/employers/profile/update": {
|
|
"post": {
|
|
"tags": [
|
|
"Employer/Profile"
|
|
],
|
|
"summary": "Update Profile details (Employer)",
|
|
"description": "Allows employers to update their profile details (company name, phone number, name, email, language preference, and notification settings) and change their account password.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"email",
|
|
"phone",
|
|
"company_name",
|
|
"language",
|
|
"notifications"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Ahmad"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"example": "ahmad@example.com"
|
|
},
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509990001"
|
|
},
|
|
"company_name": {
|
|
"type": "string",
|
|
"example": "Ahmad Tech Ltd"
|
|
},
|
|
"language": {
|
|
"type": "string",
|
|
"enum": [
|
|
"English",
|
|
"Arabic"
|
|
],
|
|
"example": "English"
|
|
},
|
|
"notifications": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"current_password": {
|
|
"type": "string",
|
|
"example": "Password@123"
|
|
},
|
|
"new_password": {
|
|
"type": "string",
|
|
"example": "NewSecurePassword@123"
|
|
},
|
|
"new_password_confirmation": {
|
|
"type": "string",
|
|
"example": "NewSecurePassword@123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Profile updated successfully."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"bearerFormat": "JWT"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"Worker": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "integer",
|
|
"example": 136
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Amina Al-Masry"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"example": "worker.971509998888@migrant.com"
|
|
},
|
|
"phone": {
|
|
"type": "string",
|
|
"example": "+971509998888"
|
|
},
|
|
"nationality": {
|
|
"type": "string",
|
|
"example": "Egypt"
|
|
},
|
|
"age": {
|
|
"type": "integer",
|
|
"example": 28
|
|
},
|
|
"salary": {
|
|
"type": "string",
|
|
"example": "1500.00"
|
|
},
|
|
"availability": {
|
|
"type": "string",
|
|
"example": "Immediate"
|
|
},
|
|
"experience": {
|
|
"type": "string",
|
|
"example": "4 Years"
|
|
},
|
|
"religion": {
|
|
"type": "string",
|
|
"example": "Muslim"
|
|
},
|
|
"bio": {
|
|
"type": "string",
|
|
"example": "Certified infant caregiver and housekeeper with excellent cooking skills."
|
|
},
|
|
"category_id": {
|
|
"type": "integer",
|
|
"example": 7
|
|
},
|
|
"verified": {
|
|
"type": "boolean",
|
|
"example": false
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"example": "active"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"example": "2026-05-20T14:54:26.000000Z"
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"example": "2026-05-20T14:54:26.000000Z"
|
|
},
|
|
"category": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "integer",
|
|
"example": 7
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"example": "General Helper"
|
|
}
|
|
}
|
|
},
|
|
"skills": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "integer",
|
|
"example": 6
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"example": "Cleaning"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"documents": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkerDocument"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"WorkerDocument": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "integer",
|
|
"example": 15
|
|
},
|
|
"worker_id": {
|
|
"type": "integer",
|
|
"example": 136
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"example": "passport"
|
|
},
|
|
"number": {
|
|
"type": "string",
|
|
"example": "P345892"
|
|
},
|
|
"issue_date": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"example": "2024-05-20"
|
|
},
|
|
"expiry_date": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"example": "2034-05-20"
|
|
},
|
|
"ocr_accuracy": {
|
|
"type": "number",
|
|
"example": 98.5
|
|
},
|
|
"file_path": {
|
|
"type": "string",
|
|
"example": "uploads/documents/1716200000_passport_my_file.jpg"
|
|
}
|
|
}
|
|
},
|
|
"JobOffer": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "integer",
|
|
"example": 1
|
|
},
|
|
"employer_id": {
|
|
"type": "integer",
|
|
"example": 2
|
|
},
|
|
"worker_id": {
|
|
"type": "integer",
|
|
"example": 136
|
|
},
|
|
"work_date": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"example": "2026-06-01"
|
|
},
|
|
"location": {
|
|
"type": "string",
|
|
"example": "Dubai Marina, Silverene Towers"
|
|
},
|
|
"salary": {
|
|
"type": "string",
|
|
"example": "2500.00"
|
|
},
|
|
"notes": {
|
|
"type": "string",
|
|
"example": "Require housekeeping support starting from June 1st."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"example": "pending"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"example": "2026-05-20T15:23:44.000000Z"
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"example": "2026-05-20T15:23:44.000000Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|