Skip to main content

​
Overview

The Companies API provides endpoints for managing company profiles, credentials, drivers, vehicles, and public information. Companies can manage their own profiles while admins have full access to all company operations.

​
Authentication

Most endpoints require authentication. Include the JWT token in the Authorization header: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Get Company Profile

Get the current authenticated company’s profile information. Company role required.

​
Response

​
Id
string
Company unique identifier
​
Email
string
Company email address
​
Name
string
Company name
​
PhoneNumber
string
Company phone number
​
LogoUrl
string
URL to company logo
​
Address
string
Company physical address
​
CommercialRegistrationNumber
string
Commercial registration number
​
IsActive
boolean
Whether company account is active
​
IsProfileComplete
boolean
Whether profile is complete (requires Name and PhoneNumber)
​
LastLoginAt
datetime
Last login timestamp
​
CreatedAt
datetime
Account creation timestamp

​
Example Request

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

​
Example Response

{
  "Id": "c_345678",
  "Email": "[email protected]",
  "Name": "شركة النقل المتطور",
  "PhoneNumber": "+966112345678",
  "LogoUrl": "/uploads/companies/c_345678/logo.png",
  "Address": "الرياض، شارع الملك فهد",
  "CommercialRegistrationNumber": "1234567890",
  "IsActive": true,
  "IsProfileComplete": true,
  "LastLoginAt": "2024-03-10T10:00:00Z",
  "CreatedAt": "2024-01-01T00:00:00Z"
}

​
Update Company Profile

Update company profile information. Company role required.

​
Request Body

​
Name
string
Company name (max 200 characters)
​
PhoneNumber
string
Company phone number (digits, spaces, +, -, () allowed)
​
Address
string
Company address (max 500 characters)
​
CommercialRegistrationNumber
string
Commercial registration number (max 50 characters)

​
Response

Returns the same structure as Get Company Profile with updated values.

​
Example Request

curl -X PUT "https://api.masareagles.com/api/company/profile" \
  -H "Authorization: Bearer YOUR_COMPANY_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "شركة النقل المتطور للنقل",
    "PhoneNumber": "+966112345678",
    "Address": "الرياض، المملكة العربية السعودية",
    "CommercialRegistrationNumber": "1234567890"
  }'

​
Get Company Public Info

Get basic public information about a company. No authentication required.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Response

​
Id
string
Company ID
​
Name
string
Company name
​
LogoUrl
string
URL to company logo
​
OverallRating
decimal
Average rating from reviews
​
TotalReviewsCount
integer
Total number of reviews
​
IsActive
boolean
Active status

​
Example Request

curl -X GET "https://api.masareagles.com/api/companies/c_345678/public"

​
Example Response

{
  "Id": "c_345678",
  "Name": "شركة النقل المتطور",
  "LogoUrl": "/uploads/companies/c_345678/logo.png",
  "OverallRating": 4.7,
  "TotalReviewsCount": 125,
  "IsActive": true
}
Upload or update company logo. Company role required.

​
Request Body (Form Data)

Image file (JPEG, PNG, WebP - max 5MB, recommended: 512x512px)

​
Response

​
LogoUrl
string
URL to the uploaded logo
​
Message
string
Success message

​
Example Request

curl -X POST "https://api.masareagles.com/api/company/logo" \
  -H "Authorization: Bearer YOUR_COMPANY_JWT_TOKEN" \
  -F "[email protected]"
Delete company logo. Company role required.

​
Example Request

curl -X DELETE "https://api.masareagles.com/api/company/logo" \
  -H "Authorization: Bearer YOUR_COMPANY_JWT_TOKEN"

​
Update Company Credentials

Update company email and/or password. Company role required.

​
Request Body

​
Email
string
New email address (valid email format)
​
CurrentPassword
string
required
Current password for verification
​
NewPassword
string
New password (min 8 characters, requires uppercase, lowercase, digit, special char)

​
Response

​
Message
string
Success message
​
Email
string
Updated email address

​
Example Request

curl -X PUT "https://api.masareagles.com/api/company/credentials" \
  -H "Authorization: Bearer YOUR_COMPANY_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Email": "[email protected]",
    "CurrentPassword": "OldPassword123!",
    "NewPassword": "NewSecurePass456!"
  }'

​
List Company Drivers

Get all drivers associated with a company.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Query Parameters

​
Page
integer
default:"1"
Page number
​
PageSize
integer
default:"20"
Items per page
​
IsActive
boolean
Filter by active status

​
Response

​
Drivers
array
List of company drivers
​
TotalCount
integer
Total number of drivers
​
Page
integer
Current page
​
PageSize
integer
Items per page
​
TotalPages
integer
Total pages

​
Example Request

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

​
List Company Vehicles

Get all vehicles associated with a company.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Query Parameters

​
Page
integer
default:"1"
Page number
​
PageSize
integer
default:"20"
Items per page
​
VehicleTypeId
string
Filter by vehicle type

​
Response

​
Vehicles
array
List of company vehicles
​
TotalCount
integer
Total number of vehicles

​
Example Request

curl -X GET "https://api.masareagles.com/api/companies/c_345678/vehicles" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Admin: List All Companies

Retrieve a paginated list of all companies. Admin only.

​
Query Parameters

​
Page
integer
default:"1"
Page number
​
PageSize
integer
default:"20"
Items per page
​
SearchTerm
string
Search by name, email, or commercial registration number
​
IsActive
boolean
Filter by active status
​
IsProfileComplete
boolean
Filter by profile completion

​
Example Request

curl -X GET "https://api.masareagles.com/api/admin/companies?Page=1&IsActive=true" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

​
Admin: Get Company by ID

Get detailed company information. Admin only.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Example Request

curl -X GET "https://api.masareagles.com/api/admin/companies/c_345678" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

​
Admin: Create Company

Create a new company account. Admin only.

​
Request Body

​
Email
string
required
Company email address
​
Password
string
required
Initial password
​
Name
string
Company name
​
PhoneNumber
string
Company phone number

​
Example Request

curl -X POST "https://api.masareagles.com/api/admin/companies" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Email": "[email protected]",
    "Password": "SecurePass123!",
    "Name": "شركة جديدة",
    "PhoneNumber": "+966501234567"
  }'

​
Admin: Update Company

Update company information. Admin only.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Request Body

Same as Update Company Profile, plus:
​
IsActive
boolean
Set company active status

​
Example Request

curl -X PUT "https://api.masareagles.com/api/admin/companies/c_345678" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "شركة محدثة",
    "IsActive": true
  }'

​
Admin: Delete Company

Soft delete a company account. Admin only.

​
Path Parameters

​
companyId
string
required
Company unique identifier

​
Example Request

curl -X DELETE "https://api.masareagles.com/api/admin/companies/c_345678" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

​
Error Responses

All endpoints may return the following error responses:

​
Common Error Codes

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

​
Example Error Response

{
  "error": "فشل التحقق من البيانات",
  "details": [
    "اسم الشركة يجب أن لا يتجاوز 200 حرف"
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us