API Reference - Services
Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108122
← Back to API Reference | Getting Started
Services
The Services table contains the master list of service offerings that can be associated with member categories (professions). Services are used throughout the platform for filtering search results, generating SEO pages, and displaying member specialties. This is primarily a reference table used for GET operations; while CRUD endpoints are available, service records are typically managed through the admin panel.
list_services — DB table: list_servicesThe Service Object
| Field | Type | Description |
|---|---|---|
service_id | integer | Unique service ID (primary key, read-only) |
name | string | Display name of the service (EG Plumbing Repairs); max 255 characters |
desc | text | Description of the service |
profession_id | integer | ID of the parent category (profession) this service belongs to; references category.category_id |
master_id | integer | ID of the master service record if this is a variant; 0 for top-level services |
filename | string | URL-friendly slug for the service page (EG plumbing-repairs); max 1000 characters |
keywords | string | Comma-separated SEO keywords for this service; max 255 characters |
revision_timestamp | timestamp | Last modified timestamp (auto-updated) |
sort_order | integer | Display sort order for this service within its category |
lead_price | number | Default lead price for this service type (nullable) |
image | string | Path to the service image (computed field, not stored directly in this table) |
List Services
Returns a paginated list of service records.
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/list_services/get?limit=25" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"service_id": "1",
"name": "Amateur Sports Teams",
"desc": "",
"profession_id": "1",
"master_id": "0",
"filename": "amateur-sports-teams",
"keywords": "",
"revision_timestamp": "2024-11-05 12:37:21",
"sort_order": "0",
"lead_price": "101.00",
"image": "/images/cat.jpg"
}
],
"total": "763",
"current_page": 1,
"total_pages": 31,
"next_page": "MipfKjI="
}Retrieve a Service Record
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/list_services/get/1" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": [
{
"service_id": "1",
"name": "Amateur Sports Teams",
"desc": "",
"profession_id": "1",
"master_id": "0",
"filename": "amateur-sports-teams",
"keywords": "",
"revision_timestamp": "2024-11-05 12:37:21",
"sort_order": "0",
"lead_price": "101.00",
"image": "/images/cat.jpg"
}
],
"total": "1",
"current_page": 1,
"total_pages": 1
}Retrieve a Sub-Category Tree
Returns a single sub-category with its nested sub-sub-categories. For the full site-wide hierarchy, or a single top-level category with everything under it, use the tree endpoints on the Categories (Professions) reference. Add ?include=member_counts to include a member_count field on every node.
Example Request
curl -X GET "https://www.yourdomain.com/api/v2/list_services/tree/1" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": {
"service_id": 1,
"name": "Amateur Sports Teams",
"filename": "amateur-sports-teams",
"sub_sub_categories": []
}
}Create a Service Record
The parent top-level category can be referenced by ID (profession_id) or by name (profession_name). When a name matches exactly one category it is used; if it matches more than one record the API returns an error listing every match with its ID so you can retry with the specific ID. Referenced parents are validated to exist, and sort_order defaults to 0 — the same behavior as the CSV import and the admin UI. To create a sub-sub-category, pass master_id (the parent sub-category's service_id).
Example Request
curl -X POST "https://www.yourdomain.com/api/v2/list_services/create" \ -H "X-Api-Key: your-api-key-here" \ -d "name=Emergency+Plumbing" \ -d "profession_id=5" \ -d "filename=emergency-plumbing" \ -d "keywords=emergency,plumbing,24-hour" \ -d "sort_order=10"
Example Response
{
"status": "success",
"message": {
"service_id": "764",
"name": "Emergency Plumbing",
"desc": null,
"profession_id": "5",
"master_id": null,
"filename": "emergency-plumbing",
"keywords": "emergency,plumbing,24-hour",
"revision_timestamp": null,
"sort_order": "10",
"lead_price": null
}
}Update a Service Record
Example Request
curl -X PUT "https://www.yourdomain.com/api/v2/list_services/update" \ -H "X-Api-Key: your-api-key-here" \ -d "service_id=764" \ -d "lead_price=75.00" \ -d "keywords=emergency,plumbing,24-hour,urgent"
Example Response
{
"status": "success",
"message": {
"service_id": "764",
"name": "Emergency Plumbing",
"desc": "",
"profession_id": "5",
"master_id": "0",
"filename": "emergency-plumbing",
"keywords": "emergency,plumbing,24-hour,urgent",
"revision_timestamp": "0000-00-00 00:00:00",
"sort_order": "10",
"lead_price": "75.00"
}
}Delete a Service Record
Deleting a sub-category is guarded by the same safety check as top-level categories. A sub-category with no members, no child sub-sub-categories, and no associations is deleted immediately. Otherwise the API rejects the request and returns the impact count. Add ?force=true to cascade: its sub-sub-categories are deleted and its rel_services associations removed — the affected members' top-level category is not changed. With force=true you can also pass reassign_members={service_id} and/or reassign_children={service_id} to move the member associations and/or child sub-sub-categories to another sub-category instead of deleting them (the target service_id is validated to exist).
Example Request
curl -X DELETE "https://www.yourdomain.com/api/v2/list_services/delete/764" \ -H "X-Api-Key: your-api-key-here"
Example Response (blocked by safety check)
{
"status": "error",
"message": "Cannot delete: sub category has dependencies. Use force=true to cascade delete, optionally with reassign_members and/or reassign_children to move them instead.",
"impact": {
"members_affected": 0,
"sub_subcategories": 1,
"rel_services_associations": 0
}
}Example Request (forced cascade)
curl -X DELETE "https://www.yourdomain.com/api/v2/list_services/delete/764?force=true" \ -H "X-Api-Key: your-api-key-here"
Example Response
{
"status": "success",
"message": "Subcategory deleted. Members reassigned: 0, children reparented: 0, sub-subcategories deleted: 1, associations removed: 0."
}