Mlatho — Book Service Pros
Mlatho — Book Service Pros · GPT Actions
Mlatho Service Marketplace API
Search and book trusted service professionals across Africa. Mlatho connects customers with vetted, rated professionals for plumbing, legal, electrical, cleaning, catering, IT support, beauty, tutoring, and many other service categories in South Africa and expanding to all Africa.
GET /api/serviceofferings/searchSearch for services on the Mlatho marketplaceSearch for available services by category, location, and price. Returns paginated results with pricing, professional ratings, and service details. Use this when a user needs to find a service professional in Africa.
GET /api/serviceofferings/{id}Get full details for a specific service offeringReturns comprehensive details about a service including pricing, duration, professional info, and ratings.
GET /api/serviceofferings/allGet all active service offeringsReturns all active service offerings on the marketplace. Use search endpoint for filtered results.
GET /api/categoriesList all service categoriesReturns all active service categories available on Mlatho (e.g. Legal, Plumbing, Electrical, Cleaning, Catering, IT Support, Beauty, Tutoring, Photography, Event Planning).
GET /api/categories/{id}Get a specific categoryGET /api/prosFind service professionalsFind vetted, rated service professionals on Mlatho. Filter by city and/or service category. Returns professional profiles with ratings, skills, verification status, and service areas.
GET /api/pros/featuredGet top-rated featured professionalsReturns up to 6 featured, top-rated professionals on the platform.
GET /api/pros/authenticated/{userId}Get a specific professional's profileGET /api/ratings/service-pro/{serviceProId}Get ratings and reviews for a professionalReturns paginated ratings with individual scores for communication, quality, punctuality, and value.
GET /api/ratings/top-ratedGet top-rated service professionals
原始 API 定义
{
"openapi": "3.1.0",
"info": {
"title": "Mlatho Service Marketplace API",
"description": "Search and book trusted service professionals across Africa.\nMlatho connects customers with vetted, rated professionals for plumbing, legal, electrical, \ncleaning, catering, IT support, beauty, tutoring, and many other service categories \nin South Africa and expanding to all Africa.\n",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.mlatho.com",
"description": "Production API"
}
],
"paths": {
"/api/serviceofferings/search": {
"get": {
"operationId": "searchServices",
"summary": "Search for services on the Mlatho marketplace",
"description": "Search for available services by category, location, and price. Returns paginated results\nwith pricing, professional ratings, and service details. Use this when a user needs to find\na service professional in Africa.\n",
"parameters": [
{
"name": "category",
"in": "query",
"description": "Service category to filter by (e.g. Legal, Plumbing, Electrical, Cleaning, Catering, IT Support, Beauty, Tutoring)",
"schema": {
"type": "string"
}
},
{
"name": "location",
"in": "query",
"description": "City or area to search in (e.g. Johannesburg, Cape Town, Durban, Lilongwe, Blantyre)",
"schema": {
"type": "string"
}
},
{
"name": "maxPrice",
"in": "query",
"description": "Maximum price in cents (e.g. 50000 for R500)",
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"description": "Page number for paginated results (default 1)",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"description": "Number of results per page (default 10)",
"schema": {
"type": "integer",
"default": 10
}
},
{
"name": "latitude",
"in": "query",
"description": "User latitude for distance-based sorting",
"schema": {
"type": "number",
"format": "double"
}
},
{
"name": "longitude",
"in": "query",
"description": "User longitude for distance-based sorting",
"schema": {
"type": "number",
"format": "double"
}
}
],
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"offerings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceOfferingSearchResult"
}
},
"page": {
"type": "integer"
},
"pageSize": {
"type": "integer"
},
"totalCount": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"/api/serviceofferings/{id}": {
"get": {
"operationId": "getServiceDetails",
"summary": "Get full details for a specific service offering",
"description": "Returns comprehensive details about a service including pricing, duration, professional info, and ratings.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "The service offering ID",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Service offering details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServiceOfferingDetail"
}
}
}
},
"404": {
"description": "Service not found"
}
}
}
},
"/api/serviceofferings/all": {
"get": {
"operationId": "getAllServices",
"summary": "Get all active service offerings",
"description": "Returns all active service offerings on the marketplace. Use search endpoint for filtered results.",
"responses": {
"200": {
"description": "All active offerings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"offerings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ServiceOfferingSearchResult"
}
},
"totalCount": {
"type": "integer"
}
}
}
}
}
}
}
}
},
"/api/categories": {
"get": {
"operationId": "getCategories",
"summary": "List all service categories",
"description": "Returns all active service categories available on Mlatho (e.g. Legal, Plumbing, Electrical, Cleaning, Catering, IT Support, Beauty, Tutoring, Photography, Event Planning).",
"responses": {
"200": {
"description": "List of categories",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
}
}
},
"/api/categories/{id}": {
"get": {
"operationId": "getCategoryById",
"summary": "Get a specific category",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Category details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Category"
}
}
}
}
}
}
},
"/api/pros": {
"get": {
"operationId": "findProfessionals",
"summary": "Find service professionals",
"description": "Find vetted, rated service professionals on Mlatho. Filter by city and/or service category.\nReturns professional profiles with ratings, skills, verification status, and service areas.\n",
"parameters": [
{
"name": "city",
"in": "query",
"description": "City to search in (e.g. Johannesburg, Cape Town, Durban, Pretoria, Lilongwe, Blantyre)",
"schema": {
"type": "string"
}
},
{
"name": "category",
"in": "query",
"description": "Service category to filter by",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "List of professionals",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Professional"
}
}
}
}
}
}
}
},
"/api/pros/featured": {
"get": {
"operationId": "getFeaturedProfessionals",
"summary": "Get top-rated featured professionals",
"description": "Returns up to 6 featured, top-rated professionals on the platform.",
"responses": {
"200": {
"description": "Featured professionals",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Professional"
}
}
}
}
}
}
}
},
"/api/pros/authenticated/{userId}": {
"get": {
"operationId": "getProfessionalProfile",
"summary": "Get a specific professional's profile",
"parameters": [
{
"name": "userId",
"in": "path",
"required": true,
"description": "The professional's user ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Professional profile",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Professional"
}
}
}
},
"404": {
"description": "Professional not found"
}
}
}
},
"/api/ratings/service-pro/{serviceProId}": {
"get": {
"operationId": "getProRatings",
"summary": "Get ratings and reviews for a professional",
"description": "Returns paginated ratings with individual scores for communication, quality, punctuality, and value.",
"parameters": [
{
"name": "serviceProId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Ratings and summary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RatingsResponse"
}
}
}
}
}
}
},
"/api/ratings/top-rated": {
"get": {
"operationId": "getTopRatedPros",
"summary": "Get top-rated service professionals",
"parameters": [
{
"name": "count",
"in": "query",
"description": "Number of top-rated pros to return (default 10)",
"schema": {
"type": "integer",
"default": 10
}
}
],
"responses": {
"200": {
"description": "Top-rated professionals",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TopRatedPro"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ServiceOfferingSearchResult": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"priceCents": {
"type": "integer",
"description": "Price in cents (e.g. 50000 = R500 or $500 depending on currency)"
},
"currency": {
"type": "string",
"description": "Currency code (ZAR for South Africa, USD for Malawi)"
},
"durationMin": {
"type": "integer",
"description": "Estimated service duration in minutes"
},
"pricingUnit": {
"type": "string",
"description": "Pricing unit (e.g. per_hour, flat_rate, per_session)"
},
"isActive": {
"type": "boolean"
},
"imageUrl": {
"type": "string"
},
"isOnlineService": {
"type": "boolean",
"description": "Whether service can be delivered remotely/online"
},
"proName": {
"type": "string"
},
"proLocation": {
"type": "string"
},
"proRating": {
"type": "number",
"format": "double"
},
"proReviewCount": {
"type": "integer"
},
"categoryId": {
"type": "integer"
},
"categoryName": {
"type": "string"
},
"distanceKm": {
"type": "number",
"format": "double",
"description": "Distance from queried location in km (when lat/lng provided)"
}
}
},
"ServiceOfferingDetail": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"priceCents": {
"type": "integer"
},
"currency": {
"type": "string"
},
"durationMin": {
"type": "integer"
},
"pricingUnit": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"proId": {
"type": "integer"
},
"proName": {
"type": "string"
},
"proLocation": {
"type": "string"
},
"proRating": {
"type": "number"
},
"proReviewCount": {
"type": "integer"
},
"proBio": {
"type": "string"
},
"proProfileImageUrl": {
"type": "string"
},
"imageUrl": {
"type": "string"
},
"isOnlineService": {
"type": "boolean"
},
"distanceKm": {
"type": "number"
}
}
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"isActive": {
"type": "boolean"
}
}
},
"Professional": {
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"displayName": {
"type": "string"
},
"bio": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"isActive": {
"type": "boolean"
},
"isVerified": {
"type": "boolean"
},
"isOnline": {
"type": "boolean"
},
"rating": {
"type": "number",
"format": "double"
},
"reviewCount": {
"type": "integer"
},
"categories": {
"type": "string",
"description": "JSON array of category names"
},
"skills": {
"type": "string",
"description": "JSON array of skill names"
},
"profileImageUrl": {
"type": "string"
}
}
},
"RatingsResponse": {
"type": "object",
"properties": {
"ratings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Rating"
}
},
"summary": {
"type": "object",
"properties": {
"averageRating": {
"type": "number"
},
"totalRatings": {
"type": "integer"
}
}
}
}
},
"Rating": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"overallRating": {
"type": "number"
},
"communicationRating": {
"type": "number"
},
"qualityRating": {
"type": "number"
},
"punctualityRating": {
"type": "number"
},
"valueRating": {
"type": "number"
},
"reviewText": {
"type": "string"
},
"customerName": {
"type": "string"
},
"serviceTitle": {
"type": "string"
},
"isVerified": {
"type": "boolean"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
"TopRatedPro": {
"type": "object",
"properties": {
"serviceProId": {
"type": "integer"
},
"averageRating": {
"type": "number"
},
"totalRatings": {
"type": "integer"
},
"fiveStarRatings": {
"type": "integer"
}
}
}
}
}
}