{ "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, "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": [ 1, 3 ], "description": "Optional array of Skill IDs (can be sent as comma-separated string e.g. '1,3' or json '[1,3]' in multipart)." }, "visa_file": { "type": "string", "format": "binary", "description": "Optional physical scan or image of the Visa (Max 10MB)." }, "language": { "type": "string", "enum": [ "HI", "SW", "TL", "TA" ], "example": "HI", "description": "Preferred interface language (HI=Hindi, SW=Swahili, TL=Tagalog, TA=Tamil)." }, "nationality": { "type": "string", "example": "Egypt", "description": "Nationality of the worker." }, "age": { "type": "integer", "example": 28, "description": "Age of the worker." }, "experience": { "type": "string", "example": "4 Years", "description": "Years of experience." } } } } } }, "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/config": { "get": { "tags": [ "Worker/Auth" ], "summary": "Get Supported Languages and Config", "description": "Returns a list of supported regional languages (Hindi, Swahili, Tagalog, Tamil) for helper onboarding.", "security": [], "responses": { "200": { "description": "Config and supported languages retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "HI" }, "name": { "type": "string", "example": "Hindi (\u0939\u093f\u0928\u094d\u0926\u0940)" } } } } } } } } } } } }, "/workers/send-otp": { "post": { "tags": [ "Worker/Auth" ], "summary": "Send Mobile OTP Verification Code", "description": "Dispatches a mock 6-digit OTP verification code ('111111') to the worker's mobile phone number or email address.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "+971501234567", "description": "Mobile contact phone number or identifier." } } } } } }, "responses": { "200": { "description": "OTP dispatched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Verification code sent. (Dev mock: 111111)" }, "identifier": { "type": "string", "example": "+971501234567" } } } } } } } } }, "/workers/verify-otp": { "post": { "tags": [ "Worker/Auth" ], "summary": "Verify Mobile OTP Code", "description": "Validates the received 6-digit OTP code against the cached record. Sets a 1-hour secure gate allowing profile setup.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "otp" ], "properties": { "phone": { "type": "string", "example": "+971501234567" }, "otp": { "type": "string", "example": "111111", "description": "6-digit OTP received by the worker." } } } } } }, "responses": { "200": { "description": "OTP verified and registration gate unlocked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OTP verified successfully. You may proceed with profile setup." }, "identifier": { "type": "string", "example": "+971501234567" } } } } } }, "422": { "description": "Invalid OTP code or expired session." } } } }, "/workers/setup-profile": { "post": { "tags": [ "Worker/Auth" ], "summary": "Complete Basic Profile Setup", "description": "Saves basic onboarding data (Name, Nationality, Language, Skills) and generates the permanent worker account along with a secure bearer access token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "name", "nationality", "language" ], "properties": { "phone": { "type": "string", "example": "+971501234567" }, "name": { "type": "string", "example": "Rahul Sharma" }, "nationality": { "type": "string", "example": "India" }, "language": { "type": "string", "enum": [ "HI", "SW", "TL", "TA" ], "example": "HI" }, "skills": { "type": "array", "items": { "type": "integer" }, "example": [ 6, 8 ], "description": "Array of skill IDs" } } } } } }, "responses": { "201": { "description": "Account created and profile configured successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Registration complete! Welcome to Migrant." }, "data": { "type": "object", "properties": { "worker": { "$ref": "#/components/schemas/Worker" }, "token": { "type": "string", "example": "abc123xyz456...secureToken..." } } } } } } } } } } }, "/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 }, "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/profile/upload-emirates-id": { "post": { "tags": [ "Worker/Profile" ], "summary": "Upload Emirates ID scan & Secure OCR Extract & Purge physical image (PDPL compliant)", "description": "Accepts an Emirates ID scan file, performs automatic OCR extraction of card fields (Name, ID, Expiry), instantly purges/deletes the physical file image from servers to comply with PDPL privacy regulations, and awards the Verified Badge to the worker.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "emirates_id_file" ], "properties": { "emirates_id_file": { "type": "string", "format": "binary", "description": "Physical scan or image file of the Emirates ID (Max 10MB)." } } } } } }, "responses": { "200": { "description": "Emirates ID verified and physical file safely purged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Emirates ID verified successfully. Your verified badge is now active. Physical file purged for PDPL compliance." }, "ocr_extracted_data": { "type": "object", "properties": { "name": { "type": "string", "example": "Rahul Sharma" }, "emirates_id_number": { "type": "string", "example": "784-1995-1234567-1" }, "expiry_date": { "type": "string", "example": "2029-05-25" } } } } } } } } } } }, "/workers/go-live": { "post": { "tags": [ "Worker/Profile" ], "summary": "Profile Go Live", "description": "Sets the worker status to 'active' and availability to 'Immediate', making the profile searchable on the sponsor/employer marketplace.", "responses": { "200": { "description": "Worker profile is now live and searchable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Your profile is now live! Status set to Active." } } } } } } } } }, "/workers/profile/toggle-availability": { "post": { "tags": [ "Worker/Profile" ], "summary": "Toggle Profile Search Visibility", "description": "Updates worker search visibility based on whether they are still actively seeking a job. 'still_looking' as true makes profile active, false hides it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "still_looking" ], "properties": { "still_looking": { "type": "boolean", "example": true, "description": "Whether the worker is still actively looking for job offers." } } } } } }, "responses": { "200": { "description": "Availability toggled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "still_looking": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "active" } } } } } } } } }, "/workers/profile/mark-hired": { "post": { "tags": [ "Worker/Profile" ], "summary": "Mark Worker as Hired", "description": "Changes the worker's status to 'Hired', which automatically removes them from active marketplace searches.", "responses": { "200": { "description": "Worker marked as Hired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Congratulations! You have been successfully marked as Hired." } } } } } } } } }, "/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": { "multipart/form-data": { "schema": { "type": "object", "properties": { "text": { "type": "string", "example": "Yes, I am available.", "description": "Optional text message content (required if no file is uploaded)." }, "file": { "type": "string", "format": "binary", "description": "Optional file or voice note attachment (Max 10MB). Supports images, documents, and common audio formats." } } } } } }, "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 }, "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 }, "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/forgot-password": { "post": { "tags": [ "Employer/Auth" ], "summary": "Request Password Reset Code", "description": "Validates employer email and sends a 6-digit password reset verification code (OTP).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "example": "ahmad@example.com" } } } } } }, "responses": { "200": { "description": "Password reset verification code sent successfully." }, "404": { "description": "No employer account found with this email." } } } }, "/employers/reset-password": { "post": { "tags": [ "Employer/Auth" ], "summary": "Reset Password with Verification Code", "description": "Verifies the 6-digit OTP code and updates the password for both employer user and sponsor records.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "otp", "password", "password_confirmation" ], "properties": { "email": { "type": "string", "example": "ahmad@example.com" }, "otp": { "type": "string", "example": "111111" }, "password": { "type": "string", "example": "SecureNewPassword@123" }, "password_confirmation": { "type": "string", "example": "SecureNewPassword@123" } } } } } }, "responses": { "200": { "description": "Password reset successfully." }, "400": { "description": "Invalid or expired verification code." } } } }, "/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": { "multipart/form-data": { "schema": { "type": "object", "properties": { "text": { "type": "string", "example": "When can you start?", "description": "Optional text message content (required if no file is uploaded)." }, "file": { "type": "string", "format": "binary", "description": "Optional file or voice note attachment (Max 10MB). Supports images, documents, and common audio formats." } } } } } }, "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.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "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.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "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/dashboard": { "get": { "tags": [ "Employer/Profile" ], "summary": "Get Employer Dashboard stats & recent events", "description": "Retrieves stats including contacted workers count, total hired workers, saved candidates, current plan details, and recent announcements or events.", "responses": { "200": { "description": "Employer dashboard stats retrieved 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", "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." } } } }, "/employers/workers": { "get": { "tags": [ "Employer/Pipeline" ], "summary": "Get Available Workers", "description": "Returns a list of verified workers that are currently available to be hired.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search term matching helper name, nationality, or religion.", "schema": { "type": "string" } }, { "name": "skills", "in": "query", "required": false, "description": "Filter by skills (comma-separated list).", "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "description": "Filter by language.", "schema": { "type": "string" } }, { "name": "nationality", "in": "query", "required": false, "description": "Filter by nationality name.", "schema": { "type": "string" } }, { "name": "availability", "in": "query", "required": false, "description": "Filter by availability status.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Available workers list retrieved successfully." } } } }, "/employers/workers/{id}": { "get": { "tags": [ "Employer/Pipeline" ], "summary": "Get Worker Profile Detail", "description": "Retrieves the complete profile details for a worker, mirroring the web detailed view, along with active conversation details if already started with this employer.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Worker ID reference.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Worker profile details retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "worker": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Jane Doe" }, "nationality": { "type": "string", "example": "Filipino" }, "photo": { "type": "string", "example": "https://images.unsplash.com/photo-1573496359142-b8d87734a5a2?auto=format&fit=crop&q=80&w=200" }, "emirates_id_status": { "type": "string", "example": "Emirates ID Verified" }, "category": { "type": "string", "example": "Domestic Worker" }, "skills": { "type": "array", "items": { "type": "string" }, "example": [ "childcare", "cooking" ] }, "availability_status": { "type": "string", "example": "Active" }, "visa_status": { "type": "string", "example": "Residence Visa" }, "experience": { "type": "string", "example": "5 Years" }, "experience_years": { "type": "integer", "example": 5 }, "salary": { "type": "integer", "example": 2500 }, "religion": { "type": "string", "example": "Christian" }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "English", "Tagalog" ] }, "age": { "type": "integer", "example": 28 }, "verified": { "type": "boolean", "example": true }, "preferred_job_type": { "type": "string", "example": "live-in" }, "bio": { "type": "string", "example": "Experienced and caring domestic worker specialing in childcare and housekeeping..." }, "rating": { "type": "number", "example": 4.3 }, "reviews_count": { "type": "integer", "example": 6 }, "reviews": { "type": "array", "items": { "type": "object" } }, "similar_workers": { "type": "array", "items": { "type": "object" } }, "conversation_id": { "type": "integer", "nullable": true, "example": 4 } } } } } } } } } }, "404": { "description": "Worker profile not found." } } } }, "/employers/candidates": { "get": { "tags": [ "Employer/Pipeline" ], "summary": "Get Candidate Applications and Offers", "description": "Returns all job applications and direct hiring offers connected to the authenticated sponsor account that have achieved 'Hired' status.", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search term matching helper name, nationality, or religion.", "schema": { "type": "string" } }, { "name": "skills", "in": "query", "required": false, "description": "Filter candidates by skills (comma-separated list of skill names, e.g. cooking,driving).", "schema": { "type": "string" } }, { "name": "languages", "in": "query", "required": false, "description": "Filter candidates by languages spoken (comma-separated list of language names, e.g. English,Arabic).", "schema": { "type": "string" } }, { "name": "nationality", "in": "query", "required": false, "description": "Filter candidates by nationality name.", "schema": { "type": "string" } }, { "name": "availability", "in": "query", "required": false, "description": "Filter candidates by availability status.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Employer candidate pipeline retrieved successfully." } } } }, "/employers/candidates/{id}/hire": { "post": { "tags": [ "Employer/Pipeline" ], "summary": "Mark Candidate as Hired", "description": "Transitions the target candidate application, job offer, or helper status to 'Hired'.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The target identifier (Application ID, Offer ID, or Worker ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Candidate successfully status updated to Hired." } } } }, "/employers/shortlist": { "get": { "tags": [ "Employer/Pipeline" ], "summary": "Get Shortlisted Workers", "description": "Returns a list of all workers shortlisted by the authenticated sponsor.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Shortlisted workers retrieved successfully." } } }, "post": { "tags": [ "Employer/Pipeline" ], "summary": "Toggle Worker Shortlist Status", "description": "Toggles (adds or removes) a worker to/from the authenticated sponsor's shortlist.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_id" ], "properties": { "worker_id": { "type": "integer", "example": 1, "description": "Worker ID to shortlist/unshortlist." } } } } } }, "responses": { "200": { "description": "Shortlist status toggled successfully." } } } }, "/employers/payments": { "get": { "tags": [ "Employer/Billing" ], "summary": "Get Payment History", "description": "Retrieves the complete transaction history for the authenticated sponsor/employer, including subscription passes and document vetting receipts.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Employer billing history retrieved successfully." } } } }, "/workers/dashboard/views": { "get": { "tags": [ "Worker/Dashboard" ], "summary": "Get Worker Profile Views Statistics", "description": "Allows authenticated workers to see the total count and detailed list of employers/sponsors who viewed their full profile.", "responses": { "200": { "description": "Profile views statistics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "views_count": { "type": "integer", "example": 5 }, "views_list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "employer_id": { "type": "integer", "example": 2 }, "employer_name": { "type": "string", "example": "Ahmad" }, "company_name": { "type": "string", "example": "Ahmad Tech Ltd" }, "nationality": { "type": "string", "example": "UAE" }, "city": { "type": "string", "example": "Dubai" }, "viewed_at": { "type": "string", "format": "date-time", "example": "2026-06-01T15:10:24.000000Z" }, "viewed_at_formatted": { "type": "string", "example": "2 minutes ago" } } } } } } } } } } } } } }, "/workers/dashboard": { "get": { "tags": [ "Worker/Dashboard" ], "summary": "Get Worker Consolidated Dashboard Data", "description": "Allows authenticated workers to retrieve their dashboard metrics: active status, profile views count, currently working sponsor/employer details, and latest charity events/announcements.", "responses": { "200": { "description": "Worker dashboard details retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "active_status": { "type": "string", "example": "active" }, "count_sponsors_viewed": { "type": "integer", "example": 5 }, "currently_working_sponsor": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 2 }, "name": { "type": "string", "example": "Ahmad" }, "company_name": { "type": "string", "example": "Ahmad Tech Ltd" }, "nationality": { "type": "string", "example": "UAE" }, "city": { "type": "string", "example": "Dubai" }, "email": { "type": "string", "example": "ahmad@example.com" }, "phone": { "type": "string", "example": "+971509990001" }, "hired_at": { "type": "string", "format": "date-time", "example": "2026-06-01T15:10:24.000000Z" }, "hired_at_formatted": { "type": "string", "example": "Jun 01, 2026" } } }, "latest_charity_events_list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "title": { "type": "string", "example": "Free Dental Checkup Camp" }, "body": { "type": "string", "example": "Emirates Charity is providing free screening." }, "type": { "type": "string", "example": "charity" }, "employer_name": { "type": "string", "example": "Emirates Charity" }, "company_name": { "type": "string", "example": "Emirates Charity Foundation" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-06-01T10:00:00.000000Z" }, "time_ago": { "type": "string", "example": "5 hours ago" } } } } } } } } } } } } } }, "/employers/reviews": { "get": { "tags": [ "Employer/Reviews" ], "summary": "Get Reviews Written by Employer", "description": "Retrieves a paginated list of all reviews written by the authenticated employer.", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Number of items per page.", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Reviews retrieved successfully." } } }, "post": { "tags": [ "Employer/Reviews" ], "summary": "Add or Update Worker Review", "description": "Allows employers to submit a review score and description comment for a worker. If the employer has already left a review, this will update it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "worker_id", "rating" ], "properties": { "worker_id": { "type": "integer", "example": 136, "description": "Worker ID being reviewed." }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5, "description": "Review score from 1 to 5." }, "comment": { "type": "string", "example": "Highly professional, punctual and did a great job!", "description": "Optional detailed comment." } } } } } }, "responses": { "201": { "description": "Review added successfully." }, "200": { "description": "Review updated successfully." }, "422": { "description": "Validation error." } } } }, "/employers/reviews/{id}": { "put": { "tags": [ "Employer/Reviews" ], "summary": "Edit Worker Review", "description": "Allows employers to edit their previously created review score and comment by review ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Review ID reference.", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rating" ], "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5, "example": 4, "description": "Updated rating score from 1 to 5." }, "comment": { "type": "string", "example": "Updated feedback comment.", "description": "Updated review comment description." } } } } } }, "responses": { "200": { "description": "Review edited successfully." }, "404": { "description": "Review not found or unauthorized." }, "422": { "description": "Validation error." } } } } }, "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" } } } } } }