Authentication / JWT

This project uses JSON Web Tokens (JWT). Obtain tokens from the login endpoint. Include the access token in requests that require authentication:

# Example header
Authorization: Bearer <ACCESS_TOKEN>

When using curl include the header like:

curl -H "Authorization: Bearer <ACCESS_TOKEN>" https://backend.lyenk.com/api/accounts/users/

User Login

Authenticates a user and returns access and refresh JWT tokens.

Example (curl)

curl -X POST https://backend.lyenk.com/api/accounts/login/ \
  -H "Content-Type: application/json" \
  -d '{"username_or_email":"testuser@lyenk.com","password":"a_strong_password","role":"client"}'
      

Response (success)

{
  "refresh": "",
  "access": "",
  "user": {"id":1, "username":"testuser", "email":"test@lyenk.com", "role":"client"}
}
      

If the user's email is not yet verified, this endpoint returns a 403 Forbidden error and resends the verification email.
On successful login, a security alert email is sent to the user.

Refresh Access Token

When an access token expires, use the refresh token (obtained during login) to get a new access token without needing to re-authenticate.

The default access token lifetime is 30 minutes, and the refresh token lifetime is 24 hours (as per settings.py).

Example (curl)

curl -X POST https://backend.lyenk.com/api/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh":"<REFRESH_TOKEN_FROM_LOGIN>"}'
      

Response (success)

{
  "access": "<NEW_ACCESS_TOKEN>"
}
      

Note: The URL for this endpoint is typically /api/token/refresh/ as provided by `djangorestframework-simplejwt` and needs to be configured in your project's `urls.py`.

User Registration

Register a new client account. A verification token is emailed to the supplied address.

Example (curl)

curl -X POST https://backend.lyenk.com/api/accounts/register/ \
  -H "Content-Type: application/json" \
  -d '{"username":"newclient","email":"new.client@lyenk.com","first_name":"Jane","last_name":"Doe","password":"a_very_secure_password",}'
      

Response (success)

{"message":"Registration successful. Please check your email for a verification link."}

Verify Email

Complete email verification using the token included in the registration email.

curl -X POST https://backend.lyenk.com/api/accounts/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"token":"a1b2c3d4-e5f6-7890-1234-567890abcdef"}'
      

{"message":"Email verified successfully. You can now log in."}

Forgot Password

Request a password reset link by providing username. The reset link is sent to the associated email address.

curl -X POST https://backend.lyenk.com/api/accounts/forgot-password/ \
  -H "Content-Type: application/json" \
  -d '{"username":"user_to_reset"}'
      

{"message":"An email was sent with reset link to the email."}

Returns error if username does not exist or has no associated email.

Reset Password

Submit the token and new password to reset a user's password.

curl -X POST https://backend.lyenk.com/api/accounts/reset-password/ \
  -H "Content-Type: application/json" \
  -d '{"token":"a1b2c3d4-e5f6-7890-1234-567890abcdef","password":"MyNewSecurePassword!123","password2":"MyNewSecurePassword!123"}'
      

{"message":"Password has been reset successfully."}

User Management

Auth: Required. Only users with role admin or superadmin can list users.

Query parameters

?role=service_provider&username=joe&email=lyenk.com

Example (curl - list users)

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://backend.lyenk.com/api/accounts/users/?role=service_provider"
      

Create user

Roles allowed depend on the creator:

• An admin may create users with roles: admin or serviceprovider.
• A superadmin may create users with roles: superadmin or admin.

Example (curl - admin creating a service_provider)

curl -X POST https://backend.lyenk.com/api/accounts/users/ \
  -H "Authorization: Bearer <ADMIN_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"username":"newprovider","email":"new.provider@lyenk.com","first_name":"John","last_name":"Smith","password":"a_very_secure_password","role":"service_provider","service_type":"Plumbing","bio":"20 years experience"}'
      

Response (created)

{"id":12,"username":"newprovider","role":"service_provider","email":"new.provider@lyenk.com"}

Retrieve / Update / Delete

Auth: Required.

• Only users with the role admin or superadmin can retrieve, update, or delete users.
• When updating (PUT/PATCH), only the following fields can be modified: role, first_name, last_name, middle_name, phone_number1, phone_number2, date_of_birth.

Example (curl - update role)

curl -X PATCH https://backend.lyenk.com/api/accounts/users/12/ \
  -H "Authorization: Bearer <ADMIN_OR_SUPERADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'
      

Requests that attempt to create or change roles outside the allowed set will return 403 Forbidden.

User Profile (My Profile)

Auth: Required. Allows authenticated users to view and update their own profile information.

Retrieves the profile of the currently authenticated user.

Updates the profile of the currently authenticated user. The following fields are read-only and cannot be changed: username, email, role.

Updatable Fields (All Users)

first_name, last_name, middle_name, phone_number1, phone_number2, date_of_birth

Additional Fields (Service Providers only)

If the user's role is serviceprovider, the following fields can also be viewed and updated:

service_type, bio, availability (boolean)

Example (curl - update profile)

curl -X PATCH https://backend.lyenk.com/api/accounts/profile/ \
  -H "Authorization: Bearer <USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "phone_number1": "555-123-4567"}'
      

Example Response (Service Provider)

{
    "username": "servicepro",
    "email": "pro@lyenk.com",
    "role": "serviceprovider",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "",
    "phone_number1": "555-000-1111",
    "phone_number2": "",
    "date_of_birth": "1985-05-20",
    "service_type": "Plumbing",
    "bio": "Expert plumber with 15 years of experience.",
    "availability": true
}

List Bookings

List bookings visible to the current user (clients see their own, providers see assigned bookings, admins see all).

Query parameters

?status=pending&provider_id=<uuid>&client_id=<id>&date=2025-10-15

Create Booking

Create a booking with one or multiple services (clients only). A single service agreement file is uploaded once for the entire booking.

Request example (single service)

{
  "service_ids": ["a1b2c3d4-e5f6-7890-1234-567890abcdef"],
  "booking_date_time": "2025-10-15T14:30:00Z",
  "event_opening_date": "2025-10-15",
  "event_closing_date": "2025-10-15",
  "location": "123 Main St, Apt 4",
  "notes": "Please call on arrival",
  "agreement_file": ""
}

Request example (multiple services)

{
  "service_ids": ["a1b2c3d4-e5f6-7890-1234-567890abcdef", "b2c3d4e5-f6g7-8901-2345-678901bcdef2"],
  "booking_date_time": "2025-10-15T14:30:00Z",
  "event_opening_date": "2025-10-15",
  "event_closing_date": "2025-10-15",
  "location": "123 Main St, Apt 4",
  "notes": "Please call on arrival",
  "agreement_file": ""
}

Response (example)

{
  "booking_id": "c3d4e5f6-g7h8-9012-3456-789012cdef3",
  "client": 5,
  "services": [
    {"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "name": "Leaky Faucet Repair"},
    {"id": "b2c3d4e5-f6g7-8901-2345-678901bcdef2", "name": "Pipe Replacement"}
  ],
  "booking_date_time": "2025-10-15T14:30:00Z",
  "event_opening_date": "2025-10-15",
  "event_closing_date": "2025-10-15",
  "status": "pending",
  "provider": null,
  "location": "123 Main St, Apt 4",
  "notes": "Please call on arrival",
  "agreement_file": "/media/agreements/booking_c3d4e5f6.pdf"
}

The total deposit amount is calculated as the sum of base_price for all selected services. Booked services are automatically removed from the user's checkout lists.

Checkout Lists

List the current user's checkout lists (temporary selections of services for booking).

Create a new checkout list with selected services. Reminder emails are scheduled at 24, 48, 72, and 96 hours. The final email at 96 hours lists unbooked services. The checkout list is deleted after 120 hours.

Request example

{
  "services": ["a1b2c3d4-e5f6-7890-1234-567890abcdef", "b2c3d4e5-f6g7-8901-2345-678901bcdef2"]
}

Response (example)

{
  "id": "d4e5f6g7-h8i9-0123-4567-890123def4",
  "user": 5,
  "services": ["a1b2c3d4-e5f6-7890-1234-567890abcdef", "b2c3d4e5-f6g7-8901-2345-678901bcdef2"],
  "services_details": [
    {"id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "name": "Leaky Faucet Repair", "price": "75.00"},
    {"id": "b2c3d4e5-f6g7-8901-2345-678901bcdef2", "name": "Pipe Replacement", "price": "150.00"}
  ],
  "total_value": "225.00",
  "created_at": "2025-10-15T10:00:00Z",
  "last_reminder_sent": null
}

Delete a checkout list.

Retrieve / Update / Delete Booking

Retrieve, update or delete a booking. Permissions vary by role: clients can retrieve their bookings, providers can retrieve assigned bookings, admins can manage all bookings.

Cancel Booking

Cancel a booking (clients only) — only allowed when status is pending. Cancellation may trigger refund flow via /api/finance/.

Assign Provider (Admin)

Assign a provider to a confirmed booking (admins only). Request body should include provider_id (UUID).

Request example

{
  "provider_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Create Complaint

Create a complaint (authenticated users).

Example

{
  "subject": "Late arrival",
  "description": "The provider arrived 2 hours late",
  "related_booking": 23
}

List / Retrieve Complaints

List complaints (admins or according to permission rules) and retrieve specific complaint details.

Submit Feedback

Submit general feedback (authenticated users).

Example

{
  "rating": 5,
  "comments": "Great service!",
  "service_id": 1
}

Transactions

List and retrieve transactions.

Example response

{
  "id": 101,
  "amount": "75.00",
  "status": "completed",
  "reference": "pay_abc123",
  "user": 5,
  "booking": 12
}

Earnings, Wallets & Payouts

Providers' earnings, wallet balances and payout requests. Payouts are created via /api/finance/payouts/.

Assignment Payouts

List assignment payouts.

Create a new assignment payout.

Retrieve, update, or delete a specific assignment payout. Assignment payouts track payments to service providers for completed assignments, with statuses: pending, credited_30_assign (30% on assign), credited_60_event (60% on event), settled.

Example response

{
  "id": 101,
  "assignment": 12,
  "payout_amount": "75.00",
  "status": "credited_30_assign",
  "credited_at_assign": "2025-10-15T10:00:00Z",
  "credited_at_event": null,
  "settled_at": null
}

Notifications

List notifications for the authenticated user (ordered newest first).

Custom action to mark a notification as read.

Example response

{
  "id": 33,
  "user": 5,
  "title": "Booking Confirmed",
  "body": "Your booking for 2025-10-15 has been confirmed.",
  "status": "unread",
  "created_at": "2025-10-01T12:00:00Z"
}

Messages

List messages (inbox). Message creation and retrieval are available via the standard endpoints.

Video Categories

List video categories.

Create a new video category.

Retrieve, update, or delete a specific video category.

Videos

List videos. Supports filtering by category.

Create a new video.

Retrieve, update, or delete a specific video.

Example response

{
  "id": 7,
  "title": "How to change a faucet",
  "description": "Step-by-step guide",
  "category": 2,
  "video_file": "/media/videos/faucet.mp4",
  "is_active": true
}

Categories

Retrieves a list of all service categories.

Filtering

?name=Cleaning&is_active=true

Create

{
    "name": "Home Repair",
    "description": "Services related to home repair and maintenance.",
    "is_active": true
}

Retrieve / Update / Delete

Services

Retrieves a list of all services. Filter by ?category=1&is_active=true.

Create

{
    "name": "Leaky Faucet Repair",
    "description": "Fixing leaky faucets in kitchens and bathrooms.",
    "base_price": "75.00",
    "is_active": true,
    "category": 1
}

Retrieve / Update / Delete

Assignments

Retrieves a list of all assignments.

Filtering

You can filter the results using query parameters. Example: ?status=pending&provider_id={uuid}

• request_id (integer, ID of the booking request)
• provider_id (UUID of the service provider user)
• assigned_by (integer, ID of the admin user)
• status (string, e.g., 'pending', 'in_progress', 'completed')
• expected_completion_date (date, YYYY-MM-DD)

Create

Creates a new assignment, linking a booking request to a provider.

{
    "request_id": 1,
    "provider_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "assigned_by": 2,
    "status": "pending",
    "notes": "Customer is available after 5 PM.",
    "expected_completion_date": "2024-12-25"
}

Retrieve / Update / Delete

Retrieves a specific assignment by its ID.

Updates an assignment.

Responses

Success (200 OK on GET/PUT/PATCH)

{
    "id": 1,
    "assigned_date": "2024-10-28T10:00:00Z",
    "status": "pending",
    "notes": "Customer is available after 5 PM.",
    "expected_completion_date": "2024-12-25",
    "request_id": 1,
    "provider_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "assigned_by": 2
}

Deletes an assignment.

Service Progress (Tracking)

Tracks the lifecycle of an assignment/booking from assigned → in_progress → completed → confirmed. Progress entries are created automatically when an assignment is created. The API enforces who can view and update progress records and when transitions are allowed (see rules below).

Endpoints

Who can access

• View (GET): admins, the client who owns the booking, and the assigned service provider.
• Create / Update (POST / PATCH / PUT): only service providers and clients (with rules below). Admins can view but should not change progress entries directly.

Business rules / automatic transitions

1. When an assignment is created (for example via /api/services/assignments/ or when a provider is assigned to a booking), an initial progress record is created automatically with status assigned.
2. If the service provider accepts/starts the work while the current date/time is between the booking's event_opening_date and event_closing_date (inclusive), the status automatically becomes in_progress. Providers may also POST a progress update setting status: "in_progress" — the API will validate the date window before allowing this transition.
3. Service providers can mark the work completed only after the booking's event_closing_date (i.e., the day after or later). Attempts to set completed before the closing date will return 400 Bad Request with an explanatory message.
4. After the provider marks a booking completed, the client can trigger the final confirmation: the client confirms the completed work which sets the booking/progress status to confirmed (this is a client-only action).
5. No status-changing updates to progress (by provider or client) are permitted on days outside the allowed windows described above — the API enforces these constraints.

Request examples

Provider starting work (allowed only during event window):

curl -X POST https://backend.lyenk.com/api/services/progress/ \
  -H "Authorization: Bearer <PROVIDER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"assignment": 12, "status": "in_progress", "notes": "Arrived on site, starting work."}'

Provider marking completed (allowed only after event_closing_date):

curl -X POST https://backend.lyenk.com/api/services/progress/ \
  -H "Authorization: Bearer <PROVIDER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"assignment": 12, "status": "completed", "notes": "Work finished. All tests passed."}'

Client confirming completed work (client-only final confirmation):

curl -X PATCH https://backend.lyenk.com/api/services/progress/34/ \
  -H "Authorization: Bearer <CLIENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed", "notes": "Client confirms work completed satisfactorily."}'

Example progress record response

{
  "id": 34,
  "assignment": 12,
  "booking_id": "a1b2c3d4-...",
  "status": "in_progress",
  "actor": 7,            
  "notes": "Arrived on site, starting work.",
  "created_at": "2025-10-15T15:00:00Z"
}

Implementation note: progress entries are created automatically when assignments are created. The API layer validates dates and roles before accepting status transitions. When transitions occur the underlying Booking.status is updated to reflect the new lifecycle state.