API Reference - Categories (Professions)

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108057

← Back to API Reference | Getting Started

Categories (Professions)

Categories (also called Professions) are the primary classification system for members and content on your directory. Each category can be associated with a category group and used to organize member listings, search results, and browse pages. Categories form a three-level hierarchy: top-level categories (this model) contain sub-categories and sub-sub-categories (the list_services model). The tree and import endpoints below work with the whole hierarchy in single calls.

Model name in URL: list_professions — DB table: list_professions
Permissions: The tree, import, and cascade-delete endpoints on this page are classified as Advanced and are deny-by-default for every API key — grant them individually under the key's API Permissions (Developer Hub » API Keys). Opening a key's permissions view automatically seeds permission rows for these endpoints. The member-read companion endpoint GET /api/v2/user/categories/{user_id} (see the Users reference) is a standard endpoint and is allowed by default.

The Category Object

FieldTypeDescription
profession_idintegerUnique category ID (primary key, read-only)
namestringDisplay name of the category
desctextLong description of the category
filenamestringURL-friendly slug for the category page
keywordstextSEO keywords associated with this category
iconstringIcon class or image reference for this category
imagestringPath to the category image
sort_orderintegerDisplay order for sorting categories
lead_pricedecimalDefault lead price for this category (nullable)
revision_timestamptimestampLast modified timestamp (auto-updated)

List Category Records

GET /api/v2/list_professions/get

Returns a paginated list of category records.

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/list_professions/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "profession_id": "1",
      "name": "Plumbers",
      "desc": "",
      "filename": "plumbers",
      "keywords": "plumber, plumbing, pipe repair",
      "icon": "",
      "image": "/images/cat.jpg",
      "sort_order": "0",
      "lead_price": null,
      "revision_timestamp": "2024-01-15 09:30:00"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Retrieve a Category Record

GET /api/v2/list_professions/get/{profession_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/list_professions/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "profession_id": "1",
      "name": "Plumbers",
      "desc": "",
      "filename": "plumbers",
      "keywords": "plumber, plumbing, pipe repair",
      "icon": "",
      "image": "/images/cat.jpg",
      "sort_order": "0",
      "lead_price": null,
      "revision_timestamp": "2024-01-15 09:30:00"
    }
  ],
  "total": "1",
  "current_page": 1,
  "total_pages": 1
}

Retrieve the Full Category Tree

GET /api/v2/list_professions/tree

Returns the entire nested category hierarchy — every top-level category with its sub-categories and sub-sub-categories — in one response, so integrations no longer need to assemble the tree from multiple flat calls. Two scoped variants are available: GET /api/v2/list_professions/tree/{profession_id} returns a single top-level category with its full nested tree, and GET /api/v2/list_services/tree/{service_id} returns a single sub-category with its sub-sub-categories.

Add ?include=member_counts to include a member_count field on every node.

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/list_professions/tree?include=member_counts" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "profession_id": 1,
      "name": "Home Services",
      "filename": "home-services",
      "member_count": 12,
      "sub_categories": [
        {
          "service_id": 1,
          "name": "Plumbing",
          "filename": "plumbing",
          "member_count": 3,
          "sub_sub_categories": [
            {
              "service_id": 2,
              "name": "Emergency Plumbing",
              "filename": "emergency-plumbing",
              "member_count": 1
            }
          ]
        }
      ]
    }
  ]
}

Create a Category Record

POST /api/v2/list_professions/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/list_professions/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "name=Electricians" \
  -d "filename=electricians" \
  -d "keywords=electrician,electrical,wiring"

Example Response

Copy
{
  "status": "success",
  "message": {
    "profession_id": "2",
    "name": "Electricians",
    "desc": "",
    "filename": "electricians",
    "keywords": "electrician,electrical,wiring",
    "icon": "",
    "image": "",
    "sort_order": "0",
    "lead_price": null,
    "revision_timestamp": null
  }
}

Bulk Import a Category Tree

POST /api/v2/list_professions/import

Creates an entire taxonomy in one call. Send a tree parameter containing a JSON array of top-level categories, each optionally nesting subcategories and sub_subcategories. The import is all-or-nothing: every node is validated first, and nothing is created if any node fails validation. The response returns the created counts plus the full created structure with all generated IDs.

Key naming: the import input and its response use subcategories / sub_subcategories (no underscore between "sub" and "categories"), while the tree read endpoints return sub_categories / sub_sub_categories.

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/list_professions/import" \
  -H "X-Api-Key: your-api-key-here" \
  --data-urlencode 'tree=[{"name":"Home Services","subcategories":[{"name":"Plumbing","sub_subcategories":[{"name":"Emergency Plumbing"}]},{"name":"Electrical"}]}]'

Example Response

Copy
{
  "status": "success",
  "message": {
    "created": {
      "professions": 1,
      "sub_categories": 2,
      "sub_sub_categories": 1
    },
    "tree": [
      {
        "profession_id": "46",
        "name": "Home Services",
        "filename": "home-services",
        "created": true,
        "subcategories": [
          {
            "service_id": "775",
            "name": "Plumbing",
            "filename": "plumbing",
            "sub_subcategories": [
              {
                "service_id": "776",
                "name": "Emergency Plumbing",
                "filename": "emergency-plumbing"
              }
            ]
          },
          {
            "service_id": "777",
            "name": "Electrical",
            "filename": "electrical",
            "sub_subcategories": []
          }
        ]
      }
    ]
  }
}

Update a Category Record

PUT /api/v2/list_professions/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/list_professions/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "profession_id=2" \
  -d "name=Licensed+Electricians" \
  -d "keywords=licensed+electrician,electrical,wiring"

Example Response

Copy
{
  "status": "success",
  "message": {
    "profession_id": "2",
    "name": "Licensed Electricians",
    "desc": "",
    "filename": "electricians",
    "keywords": "licensed electrician,electrical,wiring",
    "icon": "",
    "image": "",
    "sort_order": "0",
    "lead_price": null,
    "revision_timestamp": "2024-01-15 09:30:00"
  }
}

Delete a Category Record

DELETE /api/v2/list_professions/delete/{profession_id}

Deleting a category is guarded by a safety check. A category with no members and no child categories is deleted immediately. If the category has dependencies, the API rejects the request and returns the impact count instead. Add ?force=true to execute the full cascade: its sub-categories and sub-sub-categories are deleted, all rel_services associations are removed, and affected members have their profession_id reset to 0 (no category selected — they would need to pick a new one).

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/list_professions/delete/2" \
  -H "X-Api-Key: your-api-key-here"

Example Response (blocked by safety check)

Copy
{
  "status": "error",
  "message": "Cannot delete: category has dependencies. Use force=true to cascade delete.",
  "impact": {
    "members_affected": 4,
    "sub_categories": 2,
    "sub_sub_categories": 1,
    "rel_services_associations": 9
  }
}

Example Request (forced cascade)

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/list_professions/delete/2?force=true" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": "Category deleted with cascade. Members reset: 4, Sub categories deleted: 2, Sub-sub categories deleted: 1, Associations removed: 9"
}