Drivers - Masar Eagle

Overview

The Drivers API provides comprehensive endpoints for managing driver profiles, registration workflows, document verification, and status management. All authenticated endpoints require a valid JWT token.

Authentication

All endpoints except Get Driver by ID require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

List Drivers

Retrieve a paginated list of all drivers with search functionality. Admin only.

Query Parameters

Page

integer

default:"1"

Page number for pagination

PageSize

integer

default:"20"

Number of items per page (max 100)

SearchTerm

string

Search by phone number or full name

IncludeDeleted

boolean

default:"false"

Include soft-deleted drivers in results

Response

Drivers

array

List of driver summaries

TotalCount

integer

Total number of drivers matching criteria

Page

integer

Current page number

PageSize

integer

Items per page

TotalPages

integer

Total number of pages

Example Request

curl -X GET "https://api.masareagles.com/api/drivers?Page=1&PageSize=20&SearchTerm=966" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "Drivers": [
    {
      "Id": "d_123456",
      "PhoneNumber": "+966501234567",
      "FullName": "أحمد محمد",
      "ProfilePictureUrl": "/uploads/drivers/d_123456/profile.jpg",
      "IsPhoneVerified": true,
      "IsProfileComplete": true,
      "IsRegistrationComplete": true,
      "IsActive": true,
      "VehicleCount": 2,
      "CreatedAt": "2024-01-15T10:30:00Z",
      "LastLoginAt": "2024-03-10T08:20:00Z"
    }
  ],
  "TotalCount": 150,
  "Page": 1,
  "PageSize": 20,
  "TotalPages": 8
}

Get Driver by ID

Retrieve detailed information about a specific driver including vehicles and verification status. Public endpoint.

Path Parameters

string

required

Driver unique identifier

Query Parameters

includeDeleted

boolean

Include soft-deleted driver data

Response

string

Driver unique identifier

PhoneNumber

string

Driver’s phone number

FullName

string

Driver’s full name

DateOfBirth

datetime

Driver’s date of birth

ProfilePictureUrl

string

URL to profile picture

IdentityDocumentUrl

string

URL to identity document

DrivingLicenseUrl

string

URL to driving license

IsPhoneVerified

boolean

Phone verification status

IsProfileComplete

boolean

Profile completion status

IsRegistrationComplete

boolean

Registration completion status

IsActive

boolean

Active status

Last login timestamp

VehicleCount

integer

Number of vehicles

Vehicles

array

List of driver’s vehicles

OverallRating

decimal

Average rating from reviews

TotalReviewsCount

integer

Total number of reviews

VerificationStatus

string

Verification status: Pending, Approved, Rejected, UnderReview

DefaultCurrencyId

string

Default currency for driver

HasWallet

boolean

Whether driver has a wallet

IsDeleted

boolean

Soft delete status

Example Request

curl -X GET "https://api.masareagles.com/api/drivers/d_123456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Driver Profile

Get comprehensive profile information for the authenticated driver including vehicles, verification progress, and currency settings.

Response

string

Driver ID

PhoneNumber

string

Phone number

FullName

string

Full name

DateOfBirth

date

Date of birth (YYYY-MM-DD)

ProfilePictureUrl

string

Profile picture URL

IdentityDocumentUrl

string

Identity document URL

DrivingLicenseUrl

string

Driving license URL

IsPhoneVerified

boolean

Phone verification status

IsProfileComplete

boolean

Profile completion status

IsActive

boolean

Active status

VehicleCount

integer

Number of vehicles

Vehicles

array

List of vehicles with details

OverallRating

decimal

Overall rating

TotalReviewsCount

integer

Total reviews count

VerificationStatus

string

Current verification status

Progress

number

Profile completion progress (0-100)

FieldStatuses

array

Verification status for each profile field

DefaultCurrencyId

string

Default currency ID

DisplayCurrencyId

string

Display currency ID

ShouldSelectCurrency

boolean

Whether driver needs to select currency

Example Request

curl -X GET "https://api.masareagles.com/api/drivers/profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Complete/Update Driver Profile

Complete or update driver profile with personal information and document uploads. Supports multipart/form-data for file uploads.

Request Body (Form Data)

FullName

string

Driver’s full name (2-100 characters)

DateOfBirth

date

Date of birth (driver must be 18-70 years old)

IdentityDocument

file

Identity document image (JPEG, PNG, PDF - max 10MB)

DrivingLicense

file

Driving license image (JPEG, PNG, PDF - max 10MB)

DeleteIdentityDocument

boolean

default:"false"

Set to true to delete existing identity document

DeleteDrivingLicense

boolean

default:"false"

Set to true to delete existing driving license

Response

string

Driver ID

FullName

string

Updated full name

DateOfBirth

date

Updated date of birth

IdentityDocumentUrl

string

URL to identity document

DrivingLicenseUrl

string

URL to driving license

IsProfileComplete

boolean

Profile completion status

Message

string

Success message

VerificationStatus

string

Current verification status

Progress

number

Profile completion progress percentage

FieldStatuses

array

Status of each profile field

Example Request

curl -X PUT "https://api.masareagles.com/api/drivers/profile/complete-and-update" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "FullName=أحمد محمد" \
  -F "DateOfBirth=1990-05-15" \
  -F "[email protected]" \
  -F "[email protected]"

Update Driver Status

Update a driver’s active/inactive status. Accessible by admins and the driver themselves.

Path Parameters

driverId

string

required

Driver unique identifier

Query Parameters

IsActive

boolean

required

Set driver active status (true/false)

Example Request

curl -X PUT "https://api.masareagles.com/api/drivers/d_123456/status?IsActive=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete Driver

Soft delete a driver and all associated vehicles. Admin only.

Path Parameters

driverId

string

required

Driver unique identifier

Response

Message

string

Success message confirming deletion

Example Request

curl -X DELETE "https://api.masareagles.com/api/drivers/d_123456" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "Message": "تم حذف السائق والمركبات بنجاح"
}

Submit Profile for Review

Submit driver profile for admin review after completing all required fields.

Example Request

curl -X POST "https://api.masareagles.com/api/drivers/profile/submit-for-review" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Driver Wallet

Get wallet information for the authenticated driver.

Example Request

curl -X GET "https://api.masareagles.com/api/drivers/me/wallet" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Default Currency

Update the driver’s default currency for transactions.

Request Body

CurrencyId

string

required

Currency identifier (e.g., “SAR”, “USD”)

Example Request

curl -X PUT "https://api.masareagles.com/api/drivers/me/default-currency" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"CurrencyId": "SAR"}'

Get Driver Company

Get the company associated with a driver.

Path Parameters

driverId

string

required

Driver unique identifier

Example Request

curl -X GET "https://api.masareagles.com/api/drivers/d_123456/company" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Error Responses

All endpoints may return the following error responses:

error

string

Error message in Arabic or English

Common Error Codes

400 Bad Request - Invalid request parameters or validation errors
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - Insufficient permissions
404 Not Found - Driver not found
500 Internal Server Error - Server error

Example Error Response

{
  "error": "لم يتم العثور على السائق"
}

Overview

Identity Service

Users Service

Trips Service

Wallet & Payments

Admin APIs

Notifications

​Overview

​Authentication

​List Drivers

​Query Parameters

​Response

​Example Request

​Example Response

​Get Driver by ID

​Path Parameters

​Query Parameters

​Response

​Example Request

​Get Driver Profile

​Response

​Example Request

​Complete/Update Driver Profile

​Request Body (Form Data)

​Response

​Example Request

​Update Driver Status

​Path Parameters

​Query Parameters

​Example Request

​Delete Driver

​Path Parameters

​Response

​Example Request

​Example Response

​Submit Profile for Review

​Example Request

​Get Driver Wallet

​Example Request

​Update Default Currency

​Request Body

​Example Request

​Get Driver Company

​Path Parameters

​Example Request

​Error Responses

​Common Error Codes

​Example Error Response

Build docs developers (and LLMs) love

Overview

Authentication

List Drivers

Query Parameters

Response

Example Request

Example Response

Get Driver by ID

Path Parameters

Query Parameters

Response

Example Request

Get Driver Profile

Response

Example Request

Complete/Update Driver Profile

Request Body (Form Data)

Response

Example Request

Update Driver Status

Path Parameters

Query Parameters

Example Request

Delete Driver

Path Parameters

Response

Example Request

Example Response

Submit Profile for Review

Example Request

Get Driver Wallet

Example Request

Update Default Currency

Request Body

Example Request

Get Driver Company

Path Parameters

Example Request

Error Responses

Common Error Codes

Example Error Response